Mypy: Optional Static Typing for Python

Common errors

• Cannot find implementation or library stub for module named 'foo'

  cause Mypy cannot locate the Python module 'foo' or its associated type stubs (.pyi files), often because it's a third-party library without stubs, a local module not on Mypy's search path, or not installed in the environment Mypy is checking.
  fix Install the module (e.g., `pip install foo`), install its type stubs (e.g., `pip install types-foo` or `mypy --install-types`), add the module's parent directory to `MYPYPATH`, or configure `mypy.ini` with `ignore_missing_imports = True` for the specific module (e.g., `[mypy-foo.*] ignore_missing_imports = True`).

• Incompatible types in assignment (expression has type "X", variable has type "Y")

  cause You are attempting to assign a value of one type (expression type 'X') to a variable that has been explicitly or implicitly typed as another incompatible type ('Y').
  fix Ensure the assigned value's type matches the variable's expected type, or explicitly annotate the variable with a `Union` type if it can legitimately hold different types, or use `cast()` if you are certain about the type and want to override Mypy.

• Need type annotation for 'variable_name'

  cause Mypy is unable to infer the precise type of a variable, typically occurring with empty collections (e.g., `[]`, `{}`) or when `--disallow-untyped-defs` or `warn_incomplete_defs` is enabled, requiring an explicit type hint.
  fix Add an explicit type annotation to the variable, especially for empty containers (e.g., `my_list: list[str] = []` or `my_dict: dict[str, int] = {}`).

• Name 'name' is not defined

  cause Mypy detects a reference to a name (variable, function, class, or module) that has not been defined or properly imported within the current scope. This often indicates a typo or a missing import.
  fix Correct any typos in the name, ensure the item is imported from the correct module, or define the name before its first use.

• Function does not return a value

  cause A function or method is annotated with a return type other than `None` (or implicitly expected to return a value), but there is a code path where it implicitly returns `None` (e.g., by reaching the end of the function without an explicit `return` statement).
  fix Ensure all code paths within the function explicitly return a value consistent with its return type annotation, or change the return type annotation to `None` if the function is not meant to return anything.

Warnings

• breaking Mypy 1.9 introduced breaking changes due to an updated typeshed version, dropping support for Python 3.7.
  Fix: Upgrade to Python 3.8 or later to maintain compatibility.
• gotcha Using 'Final' and 'TypedDict' from 'typing' requires Python 3.8 or later; for earlier versions, install 'typing_extensions'.
  Fix: Install 'typing_extensions' to use these features on older Python versions.
• gotcha Mypy reported a 'Missing target' error, indicating that it was called without specifying any files, modules, or packages to type-check. This is a usage error.
  Fix: Ensure that the 'mypy' command is followed by the path to the files, modules, or packages you intend to type-check, for example: 'mypy my_script.py' or 'mypy -m my_package'.
• breaking Mypy failed because no target module, package, or files were specified. The 'mypy' command requires at least one argument indicating what to type-check.
  Fix: Ensure the 'mypy' command is invoked with a target, such as 'mypy your_module.py', 'mypy --package your_package', or 'mypy --module your_module'.

Install

• pip install mypy Install Mypy

Imports

• Final

  from typing import Final

  Use 'Final' from 'typing' to indicate constants; 'typing_extensions' is needed for Python versions prior to 3.8.
• TypedDict

  from typing import TypedDict

  Use 'TypedDict' from 'typing' for defining typed dictionaries; 'typing_extensions' is needed for Python versions prior to 3.8.

Quickstart

Integrate Mypy into your Python application by importing 'mypy.api' and calling the 'run' function with command-line arguments. This allows programmatic access to Mypy's type checking capabilities.

import sys
from mypy import api

result = api.run(sys.argv[1:])

if result[0]:
    print('\nType checking report:\n')
    print(result[0])  # stdout

if result[1]:
    print('\nError report:\n')
    print(result[1])  # stderr

sys.exit(result[2])  # exit status