From 3eabeddcc971a2dcf117ebf909a90d5e26675131 Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Tue, 9 Oct 2018 07:50:10 -0700 Subject: [PATCH] Add docs for --namespace-packages (#5749) Follow-up for #5691. Should be cherry-picked into the release (#5741). Fixes #5757. --- docs/source/command_line.rst | 20 ++++++++++++++++++++ docs/source/config_file.rst | 4 ++++ 2 files changed, 24 insertions(+) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index 8f6d0bc45d7e..2eeb56f45d5c 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -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 + `. + + 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. + ``--ignore-missing-imports`` This flag makes mypy ignore all missing imports. It is equivalent to adding ``# type: ignore`` comments to all unresolved imports @@ -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/ diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index a17b885c13dd..f1ca113341c6 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -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 `. +``namespace_packages`` (bool, default False) + Enables PEP 420 style namespace packages. See :ref:`the + corresponding flag ` 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 `. Defaults to