From d6b39c6f3777b99bc1142c849c591a1db20d973b Mon Sep 17 00:00:00 2001 From: hauntsaninja <> Date: Tue, 20 Jul 2021 20:14:00 -0700 Subject: [PATCH] Document per-module follow_imports more explicitly Helps with #10842, #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. --- docs/source/command_line.rst | 14 ++++++++++---- docs/source/config_file.rst | 8 ++++++-- docs/source/running_mypy.rst | 4 ++++ 3 files changed, 20 insertions(+), 6 deletions(-) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index 2d82d2b83517..3e577bc162c3 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -60,10 +60,16 @@ for full details, see :ref:`running-mypy`. directories with a given name by e.g. ``--exclude /build/`` or those matching a subpath with ``--exclude /project/vendor/``. - Note that this flag only affects recursive discovery, that is, when mypy is - discovering files within a directory tree or submodules of a package to - check. If you pass a file or module explicitly it will still be checked. For - instance, ``mypy --exclude '/setup.py$' but_still_check/setup.py``. + Note that this flag only affects recursive directory tree discovery, that + is, when mypy is discovering files within a directory tree or submodules of + a package to check. If you pass a file or module explicitly it will still be + checked. For instance, ``mypy --exclude '/setup.py$' + but_still_check/setup.py``. + + In particular, ``--exclude`` does not affect mypy's :ref:`import following + `. You can use a per-module :confval:`follow_imports` config + option to additionally avoid mypy from following imports and checking code + you do not wish to be checked. Note that mypy will never recursively discover files and directories named "site-packages", "node_modules" or "__pycache__", or those whose name starts diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index cc3a0bc78392..5f2660fbaade 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -254,6 +254,10 @@ section of the command line docs. ``error``. For explanations see the discussion for the :option:`--follow-imports ` command line flag. + Using this option in a per-module section (potentially with a wildcard, + as described at the top of this page) is a good way to prevent mypy from + checking portions of your code. + If this option is used in a per-module section, the module name should match the name of the *imported* module, not the module containing the import statement. @@ -924,10 +928,10 @@ Instead of using a ``mypy.ini`` file, a ``pyproject.toml`` file (as specified by * Boolean values should be all lower case -Please see the `TOML Documentation`_ for more details and information on +Please see the `TOML Documentation`_ for more details and information on what is allowed in a ``toml`` file. See `PEP 518`_ for more information on the layout and structure of the ``pyproject.toml`` file. - + Example ``pyproject.toml`` ************************** diff --git a/docs/source/running_mypy.rst b/docs/source/running_mypy.rst index d4061fcdc103..db04452b4e5a 100644 --- a/docs/source/running_mypy.rst +++ b/docs/source/running_mypy.rst @@ -384,6 +384,10 @@ We do not recommend using ``skip`` unless you know what you are doing: while this option can be quite powerful, it can also cause many hard-to-debug errors. +Adjusting import following behaviour is often most useful when restricted to +specific modules. This can be accomplished by setting a per-module +:confval:`follow_imports` config option. + .. _mapping-paths-to-modules: