Skip to content

Commit d6b39c6

Browse files
author
hauntsaninja
committed
Document per-module follow_imports more explicitly
Helps with python#10842, python#10820 and others There have been a number of issues recently where having this spelt out a little more explicitly would help users. The introduction of `--exclude` also (pretty understandably) confuses users who don't realise mypy's recursive file discovery is a little separate from its dogged import following. I think it could be reasonable to change mypy's behaviour so that exclude also implies follow_imports=skip (or maybe silent), but it might be a little finnicky (one is a regex on filenames, the other is patterns on fully qualified module names). I'm also just wary of attempting to change this - import following configuration is probably one of the more complicated and poorly understood parts of mypy's UX - so passing on that for now.
1 parent cae5d3c commit d6b39c6

3 files changed

Lines changed: 20 additions & 6 deletions

File tree

‎docs/source/command_line.rst‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -60,10 +60,16 @@ for full details, see :ref:`running-mypy`.
6060
directories with a given name by e.g. ``--exclude /build/`` or
6161
those matching a subpath with ``--exclude /project/vendor/``.
6262

63-
Note that this flag only affects recursive discovery, that is, when mypy is
64-
discovering files within a directory tree or submodules of a package to
65-
check. If you pass a file or module explicitly it will still be checked. For
66-
instance, ``mypy --exclude '/setup.py$' but_still_check/setup.py``.
63+
Note that this flag only affects recursive directory tree discovery, that
64+
is, when mypy is discovering files within a directory tree or submodules of
65+
a package to check. If you pass a file or module explicitly it will still be
66+
checked. For instance, ``mypy --exclude '/setup.py$'
67+
but_still_check/setup.py``.
68+
69+
In particular, ``--exclude`` does not affect mypy's :ref:`import following
70+
<follow-imports>`. You can use a per-module :confval:`follow_imports` config
71+
option to additionally avoid mypy from following imports and checking code
72+
you do not wish to be checked.
6773

6874
Note that mypy will never recursively discover files and directories named
6975
"site-packages", "node_modules" or "__pycache__", or those whose name starts

‎docs/source/config_file.rst‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -254,6 +254,10 @@ section of the command line docs.
254254
``error``. For explanations see the discussion for the
255255
:option:`--follow-imports <mypy --follow-imports>` command line flag.
256256

257+
Using this option in a per-module section (potentially with a wildcard,
258+
as described at the top of this page) is a good way to prevent mypy from
259+
checking portions of your code.
260+
257261
If this option is used in a per-module section, the module name should
258262
match the name of the *imported* module, not the module containing the
259263
import statement.
@@ -924,10 +928,10 @@ Instead of using a ``mypy.ini`` file, a ``pyproject.toml`` file (as specified by
924928

925929
* Boolean values should be all lower case
926930

927-
Please see the `TOML Documentation`_ for more details and information on
931+
Please see the `TOML Documentation`_ for more details and information on
928932
what is allowed in a ``toml`` file. See `PEP 518`_ for more information on the layout
929933
and structure of the ``pyproject.toml`` file.
930-
934+
931935
Example ``pyproject.toml``
932936
**************************
933937

‎docs/source/running_mypy.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -384,6 +384,10 @@ We do not recommend using ``skip`` unless you know what you are doing:
384384
while this option can be quite powerful, it can also cause many
385385
hard-to-debug errors.
386386

387+
Adjusting import following behaviour is often most useful when restricted to
388+
specific modules. This can be accomplished by setting a per-module
389+
:confval:`follow_imports` config option.
390+
387391

388392
.. _mapping-paths-to-modules:
389393

0 commit comments

Comments
 (0)