Welcome to mypy documentation!#
Mypy is a static type checker for Python 3 and Python 2.7. If you sprinkle your code with type annotations, mypy can type check your code and find common bugs. As mypy is a static analyzer, or a lint-like tool, the type annotations are just hints for mypy and don’t interfere when running your program. You run your program with a standard Python interpreter, and the annotations are treated effectively as comments.
Using the Python 3 annotation syntax (using PEP 484 and PEP 526 notation) or a comment-based annotation syntax for Python 2 code, you will be able to efficiently annotate your code and use mypy to check the code for common errors. Mypy has a powerful and easy-to-use type system with modern features such as type inference, generics, callable types, tuple types, union types, and structural subtyping.
As a developer, you decide how to use mypy in your workflow. You can always escape to dynamic typing as mypy’s approach to static typing doesn’t restrict what you can do in your programs. Using mypy will make your programs easier to understand, debug, and maintain.
This documentation provides a short introduction to mypy. It will help you get started writing statically typed code. Knowledge of Python and a statically typed object-oriented language, such as Java, are assumed.
Note
Mypy is used in production by many companies and projects, but mypy is officially beta software. There will be occasional changes that break backward compatibility. The mypy development team tries to minimize the impact of changes to user code.
Contents#
- Built-in types
- Type inference and type annotations
- Kinds of types
- Class basics
- Annotation issues at runtime
- String literal types
- Future annotations import (PEP 563)
- typing.TYPE_CHECKING
- Class name forward references
- Import cycles
- Using classes that are generic in stubs but not at runtime
- Using types defined in stubs but not at runtime
- Using generic builtins
- Using X | Y syntax for Unions
- Using new additions to the typing module
- Protocols and structural subtyping
- Dynamically typed code
- Type checking Python 2 code
- Type narrowing
- Duck type compatibility
- Stub files
- Generics
- More types
- Literal types and Enums
- Final names, methods and classes
- Metaclasses
- Running mypy and managing imports
- The mypy command line
- Specifying what to type check
- Optional arguments
- Config file
- Import discovery
- Platform configuration
- Disallow dynamic typing
- Untyped definitions and calls
- None and Optional handling
- Configuring warnings
- Miscellaneous strictness flags
- Configuring error messages
- Incremental mode
- Advanced options
- Report generation
- Miscellaneous
- The mypy configuration file
- Config file format
- Per-module and global options
- Inverting option values
- Examples
- Import discovery
- Platform configuration
- Disallow dynamic typing
- Untyped definitions and calls
- None and Optional handling
- Configuring warnings
- Suppressing errors
- Miscellaneous strictness flags
- Configuring error messages
- Incremental mode
- Advanced options
- Report generation
- Miscellaneous
- Using a pyproject.toml file
- Example
pyproject.toml
- Inline configuration
- Mypy daemon (mypy server)
- Using installed packages
- Extending and integrating mypy
- Automatic stub generation (stubgen)
- Automatic stub testing (stubtest)
- Common issues and solutions
- Can’t install mypy using pip
- No errors reported for obviously wrong code
- Spurious errors and locally silencing the checker
- Ignoring a whole file
- Unexpected errors about ‘None’ and/or ‘Optional’ types
- Issues with code at runtime
- Mypy runs are slow
- Types of empty collections
- Redefinitions with incompatible types
- Invariance vs covariance
- Declaring a supertype as variable type
- Complex type tests
- Python version and system platform checks
- Displaying the type of an expression
- Silencing linters
- Covariant subtyping of mutable protocol members is rejected
- Dealing with conflicting names
- Using a development mypy build
- Variables vs type aliases
- Incompatible overrides
- Unreachable code
- Narrowing and inner functions
- Supported Python features
- Error codes
- Error codes enabled by default
- Check that attribute exists [attr-defined]
- Check that attribute exists in each union item [union-attr]
- Check that name is defined [name-defined]
- Check arguments in calls [call-arg]
- Check argument types [arg-type]
- Check calls to overloaded functions [call-overload]
- Check validity of types [valid-type]
- Require annotation if variable type is unclear [var-annotated]
- Check validity of overrides [override]
- Check that function returns a value [return]
- Check that return value is compatible [return-value]
- Check types in assignment statement [assignment]
- Check type variable values [type-var]
- Check uses of various operators [operator]
- Check indexing operations [index]
- Check list items [list-item]
- Check dict items [dict-item]
- Check TypedDict items [typeddict-item]
- Check that type of target is known [has-type]
- Check that import target can be found [import]
- Check that each name is defined once [no-redef]
- Check that called function returns a value [func-returns-value]
- Check instantiation of abstract classes [abstract]
- Check the target of NewType [valid-newtype]
- Check the return type of __exit__ [exit-return]
- Check that naming is consistent [name-match]
- Check that overloaded functions have an implementation [no-overload-impl]
- Check that coroutine return value is used [unused-coroutine]
- Check types in assert_type [assert-type]
- Report syntax errors [syntax]
- Miscellaneous checks [misc]
- Error codes for optional checks
- Check that type arguments exist [type-arg]
- Check that every function has an annotation [no-untyped-def]
- Check that cast is not redundant [redundant-cast]
- Check that comparisons are overlapping [comparison-overlap]
- Check that no untyped functions are called [no-untyped-call]
- Check that function does not return Any value [no-any-return]
- Check that types have no Any components due to missing imports [no-any-unimported]
- Check that statement or expression is unreachable [unreachable]
- Check that expression is redundant [redundant-expr]
- Check that expression is not implicitly true in boolean context [truthy-bool]
- Check that
# type: ignore
include an error code [ignore-without-code] - Check that awaitable return value is used [unused-awaitable]
- Additional features
- Frequently Asked Questions
- Why have both dynamic and static typing?
- Would my project benefit from static typing?
- Can I use mypy to type check my existing Python code?
- Will static typing make my programs run faster?
- How do I type check my Python 2 code?
- Is mypy free?
- Can I use duck typing with mypy?
- I like Python and I have no need for static typing
- How are mypy programs different from normal Python?
- How is mypy different from Cython?
- Does it run on PyPy?
- Mypy is a cool project. Can I help?