From 26ff0235b853f0254f397e8818296c230d2319a9 Mon Sep 17 00:00:00 2001 From: wyattscarpenter Date: Thu, 15 May 2025 23:51:20 -0700 Subject: [PATCH 1/4] improve documentation about --install-types --- docs/source/command_line.rst | 11 +++++++++++ docs/source/running_mypy.rst | 15 +++++++++------ 2 files changed, 20 insertions(+), 6 deletions(-) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index 5efec6855593..644a8229447c 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -1238,6 +1238,13 @@ Miscellaneous stubs at the end of the run, but only if any missing modules were detected. + It is not recommended to use this option in `CI/CD + `_, as it will make your + dependencies less reproducible. Instead, you should require and + install type dependencies like you would any other (test) dependency, + eg by using an dependency section in your `pyproject.toml + `_. + .. note:: This is new in mypy 0.900. Previous mypy versions included a @@ -1258,6 +1265,10 @@ Miscellaneous stub packages were found, they are installed and then another run is performed. + It is not recommended to use ``--install-types --non-interactive`` + in `CI/CD `_; see the other + flag for more details. + .. option:: --junit-xml JUNIT_XML_OUTPUT_FILE Causes mypy to generate a JUnit XML test result document with diff --git a/docs/source/running_mypy.rst b/docs/source/running_mypy.rst index 9f7461d24f72..813df0a058db 100644 --- a/docs/source/running_mypy.rst +++ b/docs/source/running_mypy.rst @@ -382,26 +382,29 @@ the library, you will get a message like this: main.py:1: note: (or run "mypy --install-types" to install all missing stub packages) You can resolve the issue by running the suggested pip commands. + If you're running mypy in CI, you can ensure the presence of any stub packages you need the same as you would any other test dependency, e.g. by adding them to -the appropriate ``requirements.txt`` file. +the appropriate ``requirements.txt`` file or dependency section of ``pyproject.toml``. -Alternatively, add the :option:`--install-types ` -to your mypy command to install all known missing stubs: +The :option:`--install-types ` flag +makes mypy list and (after a prompt) install all known missing stubs: .. code-block:: text mypy --install-types This is slower than explicitly installing stubs, since it effectively -runs mypy twice -- the first time to find the missing stubs, and +runs mypy twice — the first time to find the missing stubs, and the second time to type check your code properly after mypy has installed the stubs. It also can make controlling stub versions harder, -resulting in less reproducible type checking. +resulting in less reproducible type checking — it might even install +incompatible versions of your project's non-type dependencies, if the +type stubs require them! By default, :option:`--install-types ` shows a confirmation prompt. Use :option:`--non-interactive ` to install all suggested -stub packages without asking for confirmation *and* type check your code: +stub packages without asking for confirmation *and* then type check your code. If you've already installed the relevant third-party libraries in an environment other than the one mypy is running in, you can use :option:`--python-executable From 2b02e02f8af1617145d09ef3b2e0073874568c25 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sat, 8 Nov 2025 04:29:35 +0000 Subject: [PATCH 2/4] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/running_mypy.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/running_mypy.rst b/docs/source/running_mypy.rst index 813df0a058db..2cc2983f309e 100644 --- a/docs/source/running_mypy.rst +++ b/docs/source/running_mypy.rst @@ -400,7 +400,7 @@ the second time to type check your code properly after mypy has installed the stubs. It also can make controlling stub versions harder, resulting in less reproducible type checking — it might even install incompatible versions of your project's non-type dependencies, if the -type stubs require them! +type stubs require them! By default, :option:`--install-types ` shows a confirmation prompt. Use :option:`--non-interactive ` to install all suggested From f22d18b0bf439f844d0f590d322582355dfbf46d Mon Sep 17 00:00:00 2001 From: wyattscarpenter Date: Sat, 8 Nov 2025 02:02:29 -0500 Subject: [PATCH 3/4] Clean up infelicitous verbiage --- docs/source/command_line.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index 644a8229447c..6ea6a3f69c8e 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -1242,7 +1242,7 @@ Miscellaneous `_, as it will make your dependencies less reproducible. Instead, you should require and install type dependencies like you would any other (test) dependency, - eg by using an dependency section in your `pyproject.toml + such as by using a dependency section in your `pyproject.toml `_. .. note:: From d53443e145853d1106c81b3e6f9ea8bd5ba1e63d Mon Sep 17 00:00:00 2001 From: wyattscarpenter Date: Sat, 8 Nov 2025 16:59:12 -0800 Subject: [PATCH 4/4] incorporate suggestions --- docs/source/command_line.rst | 7 +++---- docs/source/running_mypy.rst | 4 ++-- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index 6ea6a3f69c8e..41ea31575791 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -1238,8 +1238,8 @@ Miscellaneous stubs at the end of the run, but only if any missing modules were detected. - It is not recommended to use this option in `CI/CD - `_, as it will make your + It is not recommended to use this option in Continuous Integration + / Continuous Delivery (CI/CD), as it will make your dependencies less reproducible. Instead, you should require and install type dependencies like you would any other (test) dependency, such as by using a dependency section in your `pyproject.toml @@ -1266,8 +1266,7 @@ Miscellaneous is performed. It is not recommended to use ``--install-types --non-interactive`` - in `CI/CD `_; see the other - flag for more details. + in CI/CD; see the other flag for more details. .. option:: --junit-xml JUNIT_XML_OUTPUT_FILE diff --git a/docs/source/running_mypy.rst b/docs/source/running_mypy.rst index 2cc2983f309e..c97aa1c1cde1 100644 --- a/docs/source/running_mypy.rst +++ b/docs/source/running_mypy.rst @@ -395,10 +395,10 @@ makes mypy list and (after a prompt) install all known missing stubs: mypy --install-types This is slower than explicitly installing stubs, since it effectively -runs mypy twice — the first time to find the missing stubs, and +runs mypy twice -- the first time to find the missing stubs, and the second time to type check your code properly after mypy has installed the stubs. It also can make controlling stub versions harder, -resulting in less reproducible type checking — it might even install +resulting in less reproducible type checking -- it might even install incompatible versions of your project's non-type dependencies, if the type stubs require them!