diff --git a/docs/source/installed_packages.rst b/docs/source/installed_packages.rst index 5ad6c274b726..9336b8f376f6 100644 --- a/docs/source/installed_packages.rst +++ b/docs/source/installed_packages.rst @@ -30,6 +30,13 @@ 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. +Note that stub-only packages (defined in +`PEP 561 `_) +cannot be used with ``MYPYPATH``. If you want mypy to find the package, it must +be installed. For a package ``foo``, the name of the stub-only package +(``foo-stubs``) is not a legal package name, so mypy will not find it, unless +it is installed. + Making PEP 561 compatible packages ********************************** diff --git a/docs/source/running_mypy.rst b/docs/source/running_mypy.rst index 949538642f93..127cb4c5dc34 100644 --- a/docs/source/running_mypy.rst +++ b/docs/source/running_mypy.rst @@ -304,6 +304,11 @@ This is computed from the following items: - The relevant directories of the `typeshed `_ repo. +.. note:: + + You cannot point to a PEP 561 package via the MYPYPATH, it must be + installed (see :ref:`PEP 561 support `) + For sources given on the command line, the path is adjusted by crawling up from the given file or package to the nearest directory that does not contain an ``__init__.py`` or ``__init__.pyi`` file. diff --git a/docs/source/stubs.rst b/docs/source/stubs.rst index f363835aff9b..eb68dba35e4b 100644 --- a/docs/source/stubs.rst +++ b/docs/source/stubs.rst @@ -25,7 +25,10 @@ Here is an overview of how to create a stub file: $ export MYPYPATH=~/work/myproject/stubs Use the normal Python file name conventions for modules, e.g. ``csv.pyi`` -for module ``csv``. Use a subdirectory with ``__init__.pyi`` for packages. +for module ``csv``. Use a subdirectory with ``__init__.pyi`` for packages. Note +that `PEP 561 `_ stub-only packages +must be installed, and may not be pointed at through the ``MYPYPATH`` +(see :ref:`PEP 561 support `). If a directory contains both a ``.py`` and a ``.pyi`` file for the same module, the ``.pyi`` file takes precedence. This way you can