Skip to content

Commit

Permalink
Clarify docs surrounding install-types (#14003)
Browse files Browse the repository at this point in the history
See #13681

More clearly point out the speed cost and the alternative of installing
stub packages directly
  • Loading branch information
hauntsaninja authored Nov 4, 2022
1 parent 11a040d commit 428b172
Showing 1 changed file with 15 additions and 31 deletions.
46 changes: 15 additions & 31 deletions docs/source/running_mypy.rst
Original file line number Diff line number Diff line change
Expand Up @@ -322,34 +322,27 @@ the library, you will get a message like this:
main.py:1: note: Hint: "python3 -m pip install types-PyYAML"
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 command or
commands. Alternatively, you can use :option:`--install-types <mypy
--install-types>` to install all known missing stubs:
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.

.. code-block:: text
mypy --install-types
This installs any stub packages that were suggested in the previous
mypy run. You can also use your normal mypy command line with the
extra :option:`--install-types <mypy --install-types>` option to
install missing stubs at the end of the run (if any were found).

Use :option:`--install-types <mypy --install-types>` with
:option:`--non-interactive <mypy --non-interactive>` to install all suggested
stub packages without asking for confirmation, *and* type check your
code, in a single command:
Alternatively, add the :option:`--install-types <mypy --install-types>`
to your mypy command to install all known missing stubs:

.. code-block:: text
mypy --install-types --non-interactive src/
mypy --install-types
This can be useful in Continuous Integration jobs if you'd prefer not
to manage stub packages manually. This is somewhat slower than
explicitly installing stubs before running mypy, since it may type
check your code twice -- the first time to find the missing stubs, and
This is slower than explicitly installing stubs, since if effectively
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.
installed the stubs. It also can make controlling stub versions harder,
resulting in less reproducible type checking.

By default, :option:`--install-types <mypy --install-types>` shows a confirmation prompt.
Use :option:`--non-interactive <mypy --non-interactive>` to install all suggested
stub packages without asking for confirmation *and* 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
Expand Down Expand Up @@ -394,15 +387,6 @@ this error, try:
you must run ``mypy ~/foo-project/src`` (or set the ``MYPYPATH`` to
``~/foo-project/src``.

In some rare cases, you may get the "Cannot find implementation or library
stub for module" error even when the module is installed in your system.
This can happen when the module is both missing type hints and is installed
on your system in an unconventional way.

In this case, follow the steps above on how to handle
:ref:`missing type hints in third party libraries <missing-type-hints-for-third-party-library>`.


.. _finding-imports:

How imports are found
Expand Down

0 comments on commit 428b172

Please sign in to comment.