Welcome to mypy documentation!

Mypy is a static type checker for Python 3 and Python 2.7.

First steps

• Introduction
• Getting started
  • Installing and running mypy
  • Function signatures and dynamic vs static typing
  • More function signatures
  • Additional types, and the typing module
  • Local type inference
  • Library stubs and typeshed
  • Configuring mypy
  • Next steps
• Using mypy with an existing codebase
  • Start small
  • Mypy runner script
  • Continuous Integration
  • Annotate widely imported modules
  • Write annotations as you go
  • Automate annotation of legacy code
  • Speed up mypy runs
  • Introduce stricter options

Cheat sheets

• Type hints cheat sheet (Python 3)
  • Variables
  • Built-in types
  • Functions
  • When you’re puzzled or when things are complicated
  • Standard “duck types”
  • Classes
  • Coroutines and asyncio
  • Miscellaneous
  • Decorators
• Type hints cheat sheet (Python 2)
  • Built-in types
  • Functions
  • When you’re puzzled or when things are complicated
  • Standard “duck types”
  • Classes
  • Miscellaneous
  • Decorators

Type system reference

• Built-in types
  • Simple types
  • Any type
  • Generic types
• Type inference and type annotations
  • Type inference
  • Explicit types for variables
  • Explicit types for collections
  • Compatibility of container types
  • Context in type inference
  • Declaring multiple variable types at a time
  • Starred expressions
  • Silencing type errors
• Kinds of types
  • Class types
  • The Any type
  • Tuple types
  • Callable types (and lambdas)
  • Union types
  • Optional types and the None type
  • Disabling strict optional checking
  • Type aliases
  • Named tuples
  • The type of class objects
  • Text and AnyStr
  • Generators
• Class basics
  • Instance and class attributes
  • Annotating __init__ methods
  • Class attribute annotations
  • Overriding statically typed methods
  • Abstract base classes and multiple inheritance
  • Slots
• 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
  • Predefined protocols
  • Simple user-defined protocols
  • Defining subprotocols and subclassing protocols
  • Recursive protocols
  • Using isinstance() with protocols
  • Callback protocols
• Dynamically typed code
  • Operations on Any values
  • Any vs. object
• Type checking Python 2 code
  • Multi-line Python 2 function annotations
  • Additional notes
• Type narrowing
  • Type narrowing expressions
  • Casts
  • User-Defined Type Guards
• Duck type compatibility
• Stub files
  • Creating a stub
  • Stub file syntax
  • Using stub file syntax at runtime
• Generics
  • Defining generic classes
  • Generic class internals
  • Defining sub-classes of generic classes
  • Generic functions
  • Generic methods and generic self
  • Variance of generic types
  • Type variables with value restriction
  • Type variables with upper bounds
  • Declaring decorators
  • Generic protocols
  • Generic type aliases
• More types
  • The NoReturn type
  • NewTypes
  • Function overloading
  • Advanced uses of self-types
  • Typing async/await
  • TypedDict
• Literal types
  • Parameterizing Literals
  • Declaring literal variables
  • Intelligent indexing
  • Tagged unions
  • Exhaustiveness checks
  • Limitations
• Final names, methods and classes
  • Final names
  • Final methods
  • Final classes
• Metaclasses
  • Defining a metaclass
  • Metaclass usage example
  • Gotchas and limitations of metaclass support

Configuring and running mypy

• Running mypy and managing imports
  • Specifying code to be checked
  • Reading a list of files from a file
  • How mypy handles imports
  • Missing imports
  • Following imports
  • Mapping file paths to modules
  • How imports are found
  • Other advice and best practices
  • Directories specific to Python 2 (@python2)
• 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
  • Configuration comment format
• Mypy daemon (mypy server)
  • Basic usage
  • Daemon client commands
  • Additional daemon flags
  • Static inference of annotations
• Using installed packages
  • Using installed packages with mypy (PEP 561)
  • Creating PEP 561 compatible packages
• Extending and integrating mypy
  • Integrating mypy into another Python application
  • Extending mypy using plugins
  • Configuring mypy to use plugins
  • High-level overview
  • Current list of plugin hooks
  • Notes about the semantic analyzer
• Automatic stub generation (stubgen)
  • Specifying what to stub
  • Specifying how to generate stubs
  • Additional flags
• Automatic stub testing (stubtest)
  • What stubtest does and does not do
  • Example
  • Usage

Miscellaneous

• 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
  • Runtime definition of methods and functions
• Error codes
  • Displaying error codes
  • Silencing errors based on 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]
  • 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]
• Additional features
  • Dataclasses
  • The attrs package
  • Using a remote cache to speed up mypy runs
  • Extended Callable types
• 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?

Indices and tables

• Index
• Search Page