From 92473c8bef8a2969e2a649c6c84b3165ba342b0c Mon Sep 17 00:00:00 2001 From: Shantanu <12621235+hauntsaninja@users.noreply.github.com> Date: Fri, 6 Dec 2024 23:23:02 -0800 Subject: [PATCH] Warn about --follow-untyped-imports (#18249) Co-authored-by: Jelle Zijlstra Co-authored-by: Marc Mueller <30130371+cdce8p@users.noreply.github.com> --- docs/source/command_line.rst | 9 ++++++++- docs/source/config_file.rst | 12 +++++++++--- docs/source/running_mypy.rst | 35 +++++++++++++++++++++++++++++------ 3 files changed, 46 insertions(+), 10 deletions(-) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index 1d91625084fd..ea96e9f64790 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -168,7 +168,14 @@ imports. .. option:: --follow-untyped-imports - This flag makes mypy analyze imports without stubs or a py.typed marker. + This flag makes mypy analyze imports from installed packages even if + missing a :ref:`py.typed marker or stubs `. + + .. warning:: + + Note that analyzing all unannotated modules might result in issues + when analyzing code not designed to be type checked and may significantly + increase how long mypy takes to run. .. option:: --follow-imports {normal,silent,skip,error} diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index e970c23a9ecb..d7ae1b7a00df 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -320,12 +320,18 @@ section of the command line docs. :type: boolean :default: False - Typechecks imports from modules that do not have stubs or a py.typed marker. + Makes mypy analyze imports from installed packages even if missing a + :ref:`py.typed marker or stubs `. 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. Note that scanning all unannotated modules might - significantly increase the runtime of your mypy calls. + import statement. + + .. warning:: + + Note that analyzing all unannotated modules might result in issues + when analyzing code not designed to be type checked and may significantly + increase how long mypy takes to run. .. confval:: follow_imports diff --git a/docs/source/running_mypy.rst b/docs/source/running_mypy.rst index 91fe525c46e0..ff042b395e99 100644 --- a/docs/source/running_mypy.rst +++ b/docs/source/running_mypy.rst @@ -277,6 +277,25 @@ If you are getting this error, try to obtain type hints for the library you're u to the library -- see our documentation on creating :ref:`PEP 561 compliant packages `. +4. Force mypy to analyze the library as best as it can (as if the library provided + a ``py.typed`` file), despite it likely missing any type annotations. In general, + the quality of type checking will be poor and mypy may have issues when + analyzing code not designed to be type checked. + + You can do this via setting the + :option:`--follow-untyped-imports ` + command line flag or :confval:`follow_untyped_imports` config file option to True. + This option can be specified on a per-module basis as well:: + + # mypy.ini + [mypy-untyped_package.*] + follow_untyped_imports = True + + # pyproject.toml + [[tool.mypy.overrides]] + module = ["untyped_package.*"] + follow_untyped_imports = true + If you are unable to find any existing type hints nor have time to write your own, you can instead *suppress* the errors. @@ -295,9 +314,15 @@ not catch errors in its use. all import errors associated with that library and that library alone by adding the following section to your config file:: + # mypy.ini [mypy-foobar.*] ignore_missing_imports = True + # pyproject.toml + [[tool.mypy.overrides]] + module = ["foobar.*"] + ignore_missing_imports = true + Note: this option is equivalent to adding a ``# type: ignore`` to every import of ``foobar`` in your codebase. For more information, see the documentation about configuring @@ -311,9 +336,13 @@ not catch errors in its use. You can also set :confval:`disable_error_code`, like so:: + # mypy.ini [mypy] disable_error_code = import-untyped + # pyproject.toml + [tool.mypy] + disable_error_code = ["import-untyped"] You can also set the :option:`--ignore-missing-imports ` command line flag or set the :confval:`ignore_missing_imports` config file @@ -321,12 +350,6 @@ not catch errors in its use. recommend avoiding ``--ignore-missing-imports`` if possible: it's equivalent to adding a ``# type: ignore`` to all unresolved imports in your codebase. -4. To make mypy typecheck imports from modules without stubs or a py.typed - marker, you can set the :option:`--follow-untyped-imports ` - command line flag or set the :confval:`follow_untyped_imports` config file option to True, - either in the global section of your mypy config file, or individually on a - per-module basis. - Library stubs not installed ---------------------------