Document stub-only packages incompatibility with MYPYPATH #5428
Conversation
There was a problem hiding this comment.
Some more broader comments:
-
Do we also need to update anything in this section of the docs? http://mypy.readthedocs.io/en/latest/running_mypy.html#how-imports-are-found
-
Do you think it might be a good idea to add instructions on using pip to create an editable install somewhere? I don't think it's a feature of pip a lot of people are familiar with, so it might be good to mention that's an alternative so that people aren't stuck when they realize they can't use MYPYPATH.
docs/source/stubs.rst
Outdated
| @@ -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 | |||
There was a problem hiding this comment.
Maybe link to the PEP 561 page here? I think this is the first time we mention it on this page.
There was a problem hiding this comment.
Sure, that is a good idea.
docs/source/installed_packages.rst
Outdated
| @@ -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. | |||
There was a problem hiding this comment.
Can you clarify either here or somewhere else on this page what it means for a package to be "stub-only"? E.g. is a stub-only package a package that contains only .pyi files, or is a stub-only package one that has a name ending in -stub, contains only .pyi files, and contains a file named py.typed?
(And if you do decide to add the exact definition somewhere else on the page, we should probably link to that here.)
Similarly, maybe clarify what it means for a package to be "installed"?
There was a problem hiding this comment.
I think ideally the docs should have a glossary, and this would be good to add there. I think linking to PEP 561 https://www.python.org/dev/peps/pep-0561/#stub-only-packages in this case is enough.
No, I don't think it is relevant there, that section doesn't talk a lot about MYPYPATH.
That might be a good idea, but I don't think an editable install is necessarily the best solution for everyone. That is why I want to say "install" over "editable install", because for most uses (those in a virtualenv) a regular install is better for general packaging purposes. |
Is that what we want, though? If somebody is looking at that section, I imagine it's because they're running into issues getting their imports to resolve. That might be due to a number of different issues -- one of which might include confusion on how exactly MYPYPATH works. In that case, perhaps it would be helpful for those readers if that section did talk more about MYPYPATH (or links to a page that does)?
Mkay, sounds good. |
OK, I will add something there too. |
|
@gvanrossum when you look at #5517 tomorrow perhaps you could briefly take a look at this as well? |
|
Will do! |
docs/source/installed_packages.rst
Outdated
| Note that stub-only packages (defined in | ||
| `PEP 561 <https://www.python.org/dev/peps/pep-0561/#stub-only-packages>`_) | ||
| cannot be used with ``MYPYPATH``. If you want mypy to find the package, it must | ||
| be installed. |
There was a problem hiding this comment.
Maybe explain that the reason is that the stubs for foo are in a folder named foo-stubs?
docs/source/running_mypy.rst
Outdated
| @@ -304,6 +304,11 @@ This is computed from the following items: | |||
| - The relevant directories of the | |||
| `typeshed <https://github.com/python/typeshed>`_ repo. | |||
|
|
|||
| .. note:: | |||
|
|
|||
| You cannot point to a PEP 561 package via the MYPYPATH, they must be | |||
There was a problem hiding this comment.
they -> it (or change the first half to plural :-).
docs/source/stubs.rst
Outdated
| @@ -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 | |||
Closes #5386.