1.. _installed-packages:
2
3Using installed packages
4========================
5
6Packages installed with pip can declare that they support type
7checking. For example, the `aiohttp
8<https://docs.aiohttp.org/en/stable/>`_ package has built-in support
9for type checking.
10
11Packages can also provide stubs for a library. For example,
12``types-requests`` is a stub-only package that provides stubs for the
13`requests <https://requests.readthedocs.io/en/master/>`_ package.
14Stub packages are usually published from `typeshed
15<https://github.com/python/typeshed>`_, a shared repository for Python
16library stubs, and have a name of form ``types-<library>``. Note that
17many stub packages are not maintained by the original maintainers of
18the package.
19
20The sections below explain how mypy can use these packages, and how
21you can create such packages.
22
23.. note::
24
25   :pep:`561` specifies how a package can declare that it supports
26   type checking.
27
28Using installed packages with mypy (PEP 561)
29********************************************
30
31Typically mypy will automatically find and use installed packages that
32support type checking or provide stubs. This requires that you install
33the packages in the Python environment that you use to run mypy.  As
34many packages don't support type checking yet, you may also have to
35install a separate stub package, usually named
36``types-<library>``. (See :ref:`fix-missing-imports` for how to deal
37with libraries that don't support type checking and are also missing
38stubs.)
39
40If you have installed typed packages in another Python installation or
41environment, mypy won't automatically find them. One option is to
42install another copy of those packages in the environment in which you
43use to run mypy. Alternatively, you can use the
44:option:`--python-executable <mypy --python-executable>` flag to point
45to the target Python executable, and mypy will find packages installed
46for that Python executable.
47
48Note that mypy does not support some more advanced import features,
49such as zip imports and custom import hooks.
50
51If you don't want to use installed packages that provide type
52information at all, use the :option:`--no-site-packages <mypy
53--no-site-packages>` flag to disable searching for installed packages.
54
55Note that stub-only packages cannot be used with ``MYPYPATH``. If you
56want mypy to find the package, it must be installed. For a package
57``foo``, the name of the stub-only package (``foo-stubs``) is not a
58legal package name, so mypy will not find it, unless it is installed
59(see :pep:`PEP 561: Stub-only Packages <561#stub-only-packages>` for
60more information).
61
62Creating PEP 561 compatible packages
63************************************
64
65.. note::
66
67  You can generally ignore this section unless you maintain a package on
68  PyPI, or want to publish type information for an existing PyPI
69  package.
70
71:pep:`561` describes three main ways to distribute type
72information:
73
741. A package has inline type annotations in the Python implementation.
75
762. A package ships :ref:`stub files <stub-files>` with type
77   information alongside the Python implementation.
78
793. A package ships type information for another package separately as
80   stub files (also known as a "stub-only package").
81
82If you want to create a stub-only package for an existing library, the
83simplest way is to contribute stubs to the `typeshed
84<https://github.com/python/typeshed>`_ repository, and a stub package
85will automatically be uploaded to PyPI.
86
87If you would like to publish a library package to a package repository
88yourself (e.g. on PyPI) for either internal or external use in type
89checking, packages that supply type information via type comments or
90annotations in the code should put a ``py.typed`` file in their
91package directory. For example, here is a typical directory structure:
92
93.. code-block:: text
94
95    setup.py
96    package_a/
97        __init__.py
98        lib.py
99        py.typed
100
101The ``setup.py`` file could look like this:
102
103.. code-block:: python
104
105    from distutils.core import setup
106
107    setup(
108        name="SuperPackageA",
109        author="Me",
110        version="0.1",
111        package_data={"package_a": ["py.typed"]},
112        packages=["package_a"]
113    )
114
115.. note::
116
117   If you use :doc:`setuptools <setuptools:index>`, you must pass the option ``zip_safe=False`` to
118   ``setup()``, or mypy will not be able to find the installed package.
119
120Some packages have a mix of stub files and runtime files. These packages also
121require a ``py.typed`` file. An example can be seen below:
122
123.. code-block:: text
124
125    setup.py
126    package_b/
127        __init__.py
128        lib.py
129        lib.pyi
130        py.typed
131
132The ``setup.py`` file might look like this:
133
134.. code-block:: python
135
136    from distutils.core import setup
137
138    setup(
139        name="SuperPackageB",
140        author="Me",
141        version="0.1",
142        package_data={"package_b": ["py.typed", "lib.pyi"]},
143        packages=["package_b"]
144    )
145
146In this example, both ``lib.py`` and the ``lib.pyi`` stub file exist. At
147runtime, the Python interpreter will use ``lib.py``, but mypy will use
148``lib.pyi`` instead.
149
150If the package is stub-only (not imported at runtime), the package should have
151a prefix of the runtime package name and a suffix of ``-stubs``.
152A ``py.typed`` file is not needed for stub-only packages. For example, if we
153had stubs for ``package_c``, we might do the following:
154
155.. code-block:: text
156
157    setup.py
158    package_c-stubs/
159        __init__.pyi
160        lib.pyi
161
162The ``setup.py`` might look like this:
163
164.. code-block:: python
165
166    from distutils.core import setup
167
168    setup(
169        name="SuperPackageC",
170        author="Me",
171        version="0.1",
172        package_data={"package_c-stubs": ["__init__.pyi", "lib.pyi"]},
173        packages=["package_c-stubs"]
174    )
175
176If you have separate stubs for Python 2 and Python 3, you can place
177the Python 2 stubs in a directory with the suffix ``-python2-stubs``.
178We recommend that Python 2 and Python 3 stubs are bundled together for
179simplicity, instead of distributing them separately.
180