The Python Type System

This document describes a specification for the Python type system.

The type system aims to provide a standard syntax for type annotations,opening up Python code to easier static analysis and refactoring,potential runtime type checking, and (perhaps, in some contexts)code generation utilizing type information.

Of these goals, static analysis is the most important. This includessupport for off-line type checkers such as mypy, as well as providinga standard notation that can be used by IDEs for code completion andrefactoring.

Purpose

This specification aims to provide a full description of the Pythontype system. For type checker authors, it provides a completedescription of expected semantics. For library authors, it providesguarantees to rely on when working with multiple type checkers.

The type system was originally specified in a series of PEPs, startingwithPEP 484. This document is intended to replace those PEPs, andwas initially created by merging the specification sections of thevarious PEPs. However, the PEPs are uneven in depth and do not fullycover all aspects of the type system. Addressing these issues is anongoing project.

Non-goals

While the typing module contains some building blocks forruntime type checking – in particular theget_type_hints()function – third party packages would have to be developed toimplement specific runtime type checking functionality, for exampleusing decorators or metaclasses. Using type hints for performanceoptimizations is left as an exercise for the reader.

It should also be emphasized thatPython will remain a dynamicallytyped language, and there is no desire to ever make type hintsmandatory, even by convention.

Interpretation

The definition of “MAY”, “MUST”, and “SHOULD”, and “SHOULD NOT” areto be interpreted as described inRFC 2119.