-
-
Notifications
You must be signed in to change notification settings - Fork 2.8k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This makes it possible to use inline types from installed packages and use installed stubs according to PEP 561. Adds `--python-executable` and `--no-site-packages` command-line options. PEP 561: https://www.python.org/dev/peps/pep-0561/ Fixes #2625, #1190, #965.
- Loading branch information
Showing
24 changed files
with
573 additions
and
65 deletions.
There are no files selected for viewing
This file contains 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 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 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,123 @@ | ||
.. _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. | ||
|
||
Using PEP 561 compatible packages with mypy | ||
******************************************* | ||
|
||
Generally, you do not need to do anything to use installed packages that | ||
support typing for the Python executable used to run mypy. Note that most | ||
packages do not support typing. Packages that do support typing should be | ||
automatically picked up by mypy and used for type checking. | ||
|
||
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. | ||
|
||
Making PEP 561 compatible packages | ||
********************************** | ||
|
||
PEP 561 notes three main ways to distribute type information. The first is a | ||
package that has only inline type annotations in the code itself. The second is | ||
a package that ships stub files with type information alongside the runtime | ||
code. The third method, also known as a "stub only package" is a package that | ||
ships type information for a package separately as stub files. | ||
|
||
If you would like to publish a library package to a package repository (e.g. | ||
PyPI) for either internal or external use in type checking, packages that | ||
supply type information via type comments or annotations in the code 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, the Python | ||
interpeter will use ``lib.py``, but mypy will use ``lib.pyi`` instead. | ||
|
||
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"] | ||
) |
This file contains 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
Oops, something went wrong.