From 73351bb81a917bb2a919a810afadad957082c472 Mon Sep 17 00:00:00 2001 From: Ethan Smith Date: Tue, 7 Aug 2018 13:15:00 -0700 Subject: [PATCH 1/3] Document stub packages incompatibility with MYPYPATH --- docs/source/installed_packages.rst | 3 +++ docs/source/stubs.rst | 4 +++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/source/installed_packages.rst b/docs/source/installed_packages.rst index 5ad6c274b726..489bf9e881aa 100644 --- a/docs/source/installed_packages.rst +++ b/docs/source/installed_packages.rst @@ -30,6 +30,9 @@ 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 cannot be used with ``MYPYPATH``. If you want mypy +to find the package, it must be installed. + Making PEP 561 compatible packages ********************************** diff --git a/docs/source/stubs.rst b/docs/source/stubs.rst index f363835aff9b..96f8be21c5f2 100644 --- a/docs/source/stubs.rst +++ b/docs/source/stubs.rst @@ -25,7 +25,9 @@ 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``. If a directory contains both a ``.py`` and a ``.pyi`` file for the same module, the ``.pyi`` file takes precedence. This way you can From b7eb209be8c14550b6ed0f9489ca712b14fcf1bc Mon Sep 17 00:00:00 2001 From: Ethan Smith Date: Tue, 7 Aug 2018 17:15:15 -0700 Subject: [PATCH 2/3] Respond to review --- docs/source/installed_packages.rst | 6 ++++-- docs/source/running_mypy.rst | 5 +++++ docs/source/stubs.rst | 2 +- 3 files changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/source/installed_packages.rst b/docs/source/installed_packages.rst index 489bf9e881aa..68c8a4760761 100644 --- a/docs/source/installed_packages.rst +++ b/docs/source/installed_packages.rst @@ -30,8 +30,10 @@ 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 cannot be used with ``MYPYPATH``. If you want mypy -to find the package, it must be installed. +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. Making PEP 561 compatible packages ********************************** diff --git a/docs/source/running_mypy.rst b/docs/source/running_mypy.rst index 949538642f93..3f21abe115e5 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, they 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 96f8be21c5f2..a2620bf0c472 100644 --- a/docs/source/stubs.rst +++ b/docs/source/stubs.rst @@ -27,7 +27,7 @@ Here is an overview of how to create a stub file: Use the normal Python file name conventions for modules, e.g. ``csv.pyi`` 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``. +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 From e2c392e36a4d1dcf0cb0c92515dbb3af36af9cce Mon Sep 17 00:00:00 2001 From: Ethan Smith Date: Fri, 31 Aug 2018 12:10:50 -0700 Subject: [PATCH 3/3] Respond to review --- docs/source/installed_packages.rst | 4 +++- docs/source/running_mypy.rst | 2 +- docs/source/stubs.rst | 5 +++-- 3 files changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/source/installed_packages.rst b/docs/source/installed_packages.rst index 68c8a4760761..9336b8f376f6 100644 --- a/docs/source/installed_packages.rst +++ b/docs/source/installed_packages.rst @@ -33,7 +33,9 @@ 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. +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 3f21abe115e5..127cb4c5dc34 100644 --- a/docs/source/running_mypy.rst +++ b/docs/source/running_mypy.rst @@ -306,7 +306,7 @@ This is computed from the following items: .. note:: - You cannot point to a PEP 561 package via the MYPYPATH, they must be + 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 diff --git a/docs/source/stubs.rst b/docs/source/stubs.rst index a2620bf0c472..eb68dba35e4b 100644 --- a/docs/source/stubs.rst +++ b/docs/source/stubs.rst @@ -26,8 +26,9 @@ Here is an overview of how to create a stub file: Use the normal Python file name conventions for modules, e.g. ``csv.pyi`` 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 `). +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