diff --git a/.readthedocs.yaml b/.readthedocs.yaml index d9961999..4bd4a2b1 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -13,6 +13,9 @@ build: - npm install -g mystmd # Build the site - cd docs && myst build --html + # Redirect the old /guides/mypy/ URL to /guides/typing/ + - mkdir -p docs/_build/html/guides/mypy + - cp redirect-stubs/guides/mypy/index.html docs/_build/html/guides/mypy/index.html # Copy the output to Read the Docs expected location - mkdir -p $READTHEDOCS_OUTPUT/html/ - cp -r docs/_build/html/. "$READTHEDOCS_OUTPUT/html" diff --git a/docs/guides/index.md b/docs/guides/index.md index e3a78dcd..3c3a4638 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -37,7 +37,7 @@ WebAssembly! All checks point to a linked badge in the guide. [tutorials]: /tutorials/index.md [style]: /guides/style.md -[mypy]: /guides/mypy.md +[mypy]: /guides/typing.md [docs]: /guides/docs.md [simple packaging]: /guides/packaging_simple.md [compiled packaging]: /guides/packaging_compiled.md diff --git a/docs/guides/style.md b/docs/guides/style.md index 8236d808..6f6d4ea9 100644 --- a/docs/guides/style.md +++ b/docs/guides/style.md @@ -786,7 +786,7 @@ for a specific rule); the standard `# type: ignore` is honored as well. ::: :::: -[mypy page]: /guides/mypy.md +[mypy page]: /guides/typing.md ## Setuptools specific checks diff --git a/docs/guides/mypy.md b/docs/guides/typing.md similarity index 85% rename from docs/guides/mypy.md rename to docs/guides/typing.md index 46bafcd5..d6d577a3 100644 --- a/docs/guides/mypy.md +++ b/docs/guides/typing.md @@ -22,15 +22,16 @@ expected really gives you a much better idea of what is going on and what you can do and can't do. But the key goal is: static type checking! There are a collection of static type -checkers, the most "official" and famous of which is MyPy. You can think of this -as the "compiler" for compiled languages like C++; it checks to make sure you -are not lying about the types. For example, passing in anything that is not an -int to `f` will fail a mypy check, _before you run or deploy any code_. +checkers to choose from. You can think of a type checker as the "compiler" for +compiled languages like C++; it checks to make sure you are not lying about the +types. For example, passing in anything that is not an int to `f` will fail the +type checker, _before you run or deploy any code_. -Your tests cannot test every possible branch, every line of code. MyPy can -(though it doesn't by default, due to gradual typing). You may have code that -runs rarely, that requires remote resources, that is slow, etc. All those can be -checked by MyPy. It also keeps you (too?) truthful in your types. +Your tests cannot test every possible branch, every line of code. A type +checker can (though it doesn't by default, due to gradual typing). You may have +code that runs rarely, that requires remote resources, that is slow, etc. All +those can be checked by the type checker. It also keeps you (too?) truthful in +your types. ### Adding types @@ -45,20 +46,22 @@ There are three ways to add types. libraries you don't control this way. If you have a library you don't control, you can add "type stubs" for it, then -give MyPy your stubs directory. MyPy will pull the types from your stubs. If you -are writing code for a Raspberry Pi, for example, you could add the stubs for +give the type checker your stubs directory. It will pull the types from your +stubs. If you are writing code for a Raspberry Pi, for example, you could add +the stubs for the Pi libraries, and then validate your code, without ever even installing the Pi-only libraries! You do not have to add types for every object - most of the time, you just need -it for parameters and returns from functions. When running MyPy, you can use -`reveal_type(...)` to show the inferred type of any object, which is like a -print statement but at type-checking time, or `reveal_locals()` to see all local -types. +it for parameters and returns from functions. When running the type checker, you +can use `reveal_type(...)` to show the inferred type of any object, which is +like a print statement but at type-checking time, or `reveal_locals()` to see +all local types. ### Configuration -By default, MyPy does as little as possible, so that you can add it iteratively +By default, the type checker does as little as possible, so that you can add it +iteratively to a code base. By default: - All untyped variables and return values will be `Any`. @@ -74,8 +77,8 @@ suggestions. For a library to support typing, it has to a) add types using any of the three methods, and b) add a `py.typed` empty file to indicate that it's okay to look -for types inside it. MyPy also looks in `typeshed`, which is a library full of -type hints for (mostly) the standard library. +for types inside it. The type checker also looks in `typeshed`, which is a +library full of type hints for (mostly) the standard library. Third party libraries that are typed sometimes forget this last step, by the way! @@ -114,8 +117,8 @@ This will print `A` because you removed B via the type narrowing using the ### Protocols -One of the best features of MyPy is support for structural subtyping via -Protocols - formalized duck-typing, basically. This allows cross library +One of the best features of type checkers is support for structural subtyping +via Protocols - formalized duck-typing, basically. This allows cross library interoperability, unlike traditional inheritance. Here’s how it works: ```python @@ -173,8 +176,8 @@ Static typing has some great features worth checking out: - Literals - TypedDict - Nicer NamedTuple definition (very popular in Python 3 code) -- MyPy validates with the Python version you ask for, regardless of what version - you are actually running. +- The type checker validates with the Python version you ask for, regardless of + what version you are actually running. ## Complete example diff --git a/docs/index.md b/docs/index.md index 0e159215..af43824e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -80,7 +80,7 @@ by NSF grant [OAC-2209877][]. [style checking]: /guides/style.md [testing]: /guides/pytest.md [documentation]: /guides/docs.md -[static typing]: /guides/mypy.md +[static typing]: /guides/typing.md [ci]: /guides/gha_pure.md [right in the guide]: /guides/repo_review.md diff --git a/docs/myst.yml b/docs/myst.yml index ed00f642..0a7ae7cd 100644 --- a/docs/myst.yml +++ b/docs/myst.yml @@ -26,7 +26,7 @@ project: - file: guides/packaging_compiled.md - file: guides/packaging_classic.md - file: guides/style.md - - file: guides/mypy.md + - file: guides/typing.md - file: guides/gha_basic.md - file: guides/gha_pure.md - file: guides/gha_wheels.md diff --git a/redirect-stubs/guides/mypy/index.html b/redirect-stubs/guides/mypy/index.html new file mode 100644 index 00000000..56a8b62a --- /dev/null +++ b/redirect-stubs/guides/mypy/index.html @@ -0,0 +1 @@ +