Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

#

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Add docs for --namespace-packages #5749

Merged
merged 1 commit into from
Oct 9, 2018
Merged

Add docs for --namespace-packages #5749

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions docs/source/command_line.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,24 @@ Import discovery
The following flags customize how exactly mypy discovers and follows
imports.

``--namespace-packages``
This flag enables import discovery to use namespace packages (see
`PEP 420`_). In particular, this allows discovery of imported
packages that don't have an ``__init__.py`` (or ``__init__.pyi``)
file.

Namespace packages are found (using the PEP 420 rules, which
prefers "classic" packages over namespace packages) along the
module search path -- this is primarily set from the source files
passed on the command line, the ``MYPYPATH`` environment variable,
and the :ref:`mypy_path config option
<config-file-import-discovery-global>`.

Note that this only affects import discovery -- for modules and
packages explicitly passed on the command line, mypy still
searches for ``__init__.py[i]`` files in order to determine the
fully-qualified module/package name.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe it would be worth talking about what to do in order to explicitly check code in namespace packages?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about things like mypy -m foo.bar if foo is a namespace package? Users may expect it to work, since the module name is explicit. Similarly, what about mypy -p foo if foo is a namespace package?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, none of those currently work. Maybe they should, but I don't have time to make it work in this release (command line files/modules/packages use an entirely different code path than imported modules). I'll open a new issue.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mypy -c 'import foo.bar', I suppose?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, there are still problems with that. I'm not sure why. Will try to look into this before the release goes out.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe #5758?


``--ignore-missing-imports``
This flag makes mypy ignore all missing imports. It is equivalent
to adding ``# type: ignore`` comments to all unresolved imports
Expand Down Expand Up @@ -570,6 +588,8 @@ Miscellaneous
have many scripts that import a large package, the behavior enabled
by this flag is often more convenient.)

.. _PEP 420: https://www.python.org/dev/peps/pep-0420/

.. _PEP 561: https://www.python.org/dev/peps/pep-0561/

.. _lxml: https://pypi.org/project/lxml/
4 changes: 4 additions & 0 deletions docs/source/config_file.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -304,6 +304,10 @@ Note: this section describes only global-only import discovery options. See abov
a list of import discovery options that may be used
:ref:`both per-module and globally <config-file-import-discovery-per-module>`.

``namespace_packages`` (bool, default False)
Enables PEP 420 style namespace packages. See :ref:`the
corresponding flag <import-discovery>` for more information.

``python_executable`` (string)
Specifies the path to the Python executable to inspect to collect
a list of available :ref:`PEP 561 packages <installed-packages>`. Defaults to
Expand Down