Implement PEP 561 searching #4403
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,114 @@ | ||
| .. _installed-packages: | ||
|
|
||
| Using Installed Packages | ||
| ======================== | ||
|
|
||
| `PEP 561 <https://www.python.org/dev/peps/pep-0561/>`_ specifies how to mark | ||
| a package as supporting type checking. Below is a summary of how to create | ||
| PEP 561 compatible packages and have mypy use them in type checking. | ||
|
|
||
| Making PEP 561 compatible packages | ||
| ********************************** | ||
|
|
||
| Packages that must be imported at runtime and supply type information should | ||
| put a ``py.typed`` in their package directory. For example, with a directory | ||
| structure as follows: | ||
|
|
||
| .. code-block:: text | ||
|
|
||
| setup.py | ||
| package_a/ | ||
| __init__.py | ||
| lib.py | ||
| py.typed | ||
|
|
||
| the setup.py might look like: | ||
|
|
||
| .. code-block:: python | ||
|
|
||
| from distutils.core import setup | ||
|
|
||
| setup( | ||
| name="SuperPackageA", | ||
| author="Me", | ||
| version="0.1", | ||
| package_data={"package_a": ["py.typed"]}, | ||
| packages=["package_a"] | ||
| ) | ||
|
|
||
| Some packages have a mix of stub files and runtime files. These packages also require | ||
| a ``py.typed`` file. An example can be seen below: | ||
|
|
||
| .. code-block:: text | ||
|
|
||
| setup.py | ||
| package_b/ | ||
| __init__.py | ||
| lib.py | ||
| lib.pyi | ||
| py.typed | ||
|
|
||
| the setup.py might look like: | ||
|
|
||
| .. code-block:: python | ||
|
|
||
| from distutils.core import setup | ||
|
|
||
| setup( | ||
| name="SuperPackageB", | ||
| author="Me", | ||
| version="0.1", | ||
| package_data={"package_b": ["py.typed", "lib.pyi"]}, | ||
| packages=["package_b"] | ||
| ) | ||
|
|
||
| In this example, both ``lib.py`` and ``lib.pyi`` exist. At runtime, ``lib.py`` | ||
| will be used, however mypy will use ``lib.pyi``. | ||
|
|
||
| If the package is stub-only (not imported at runtime), the package should have | ||
| a prefix of the runtime package name and a suffix of ``-stubs``. | ||
| A ``py.typed`` file is not needed for stub-only packages. For example, if we | ||
| had stubs for ``package_c``, we might do the following: | ||
|
|
||
| .. code-block:: text | ||
|
|
||
| setup.py | ||
| package_c-stubs/ | ||
| __init__.pyi | ||
| lib.pyi | ||
|
|
||
| the setup.py might look like: | ||
|
|
||
| .. code-block:: python | ||
|
|
||
| from distutils.core import setup | ||
|
|
||
| setup( | ||
| name="SuperPackageC", | ||
| author="Me", | ||
| version="0.1", | ||
| package_data={"package_c-stubs": ["__init__.pyi", "lib.pyi"]}, | ||
| packages=["package_c-stubs"] | ||
| ) | ||
|
|
||
| Using PEP 561 compatible packages with mypy | ||
| ******************************************* | ||
|
|
||
| Generally, you do not need to do anything to use installed packages for the | ||
| Python executable used to run mypy. They should be automatically picked up by | ||
| mypy and used for type checking. | ||
|
There was a problem hiding this comment. I'm guessing that custom import hooks are not supported? There was a problem hiding this comment. No. Custom import hooks are not supported by mypy normally, and this doesn't add support for that either. Do you have a specific need for that? There was a problem hiding this comment. Nope, but it might be nice to note in the docs exactly where mypy stops respecting the normal import mechanics. Are zip imports supported? There was a problem hiding this comment. I will add a note of that to the docs, and no, zip imports are not supported to my knowledge. There was a problem hiding this comment. How do There was a problem hiding this comment. See #4277 for the namespace packages implementation. That will be added later. There was a problem hiding this comment. Hm, is there a dependency between this and #4277? Which should be merged first? |
||
|
|
||
| By default, mypy searches for packages installed for the Python executable | ||
| running mypy. It is highly unlikely you want this situation if you have | ||
| installed typed packages in another Python's package directory. | ||
|
|
||
| Generally, you can use the ``--python-version`` flag and mypy will try to find | ||
| the correct package directory. If that fails, you can use the | ||
| ``--python-executable`` flag to point to the exact executable, and mypy will | ||
| find packages installed for that Python executable. | ||
|
|
||
| Note that mypy does not support some more advanced import features, such as zip | ||
| imports, namespace packages, and custom import hooks. | ||
|
|
||
| If you do not want to use typed packages, use the ``--no-site-packages`` flag | ||
| to disable searching. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Where did this option come from, and if it's introduced in this patch, should it be documented too?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It was introduced in #4526 but not added to the docs it seems.
I suppose it would be better to have it formally documented in a seperate PR.(Guido wants me to add it)There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
(FWIW the reason it didn't appear in the docs right away was simply that we don't regenerate this list every time we add a flag. But we should.)