About this specification

This document was created following the acceptance of PEP 729 to serve as a specification for the Python type system. The initial text consists of the “Specification” sections of PEP 484 and subsequent typing-related PEPs, pasted together and reorganized. This creates a document that encompasses all aspects of the type system that have been specified in PEPs, but not necessarily a coherent whole. The hope is that incremental improvements will be made to this document to make it more coherent and complete.

Changing the specification

Changes to the specification come in three kinds:

  • Minor, non-substantive changes can simply be proposed as PRs to the python/typing repository, and may be merged by anyone with commit access. Such changes may include formatting fixes, linking improvements, etc.

  • Substantive changes that do not rise to the level of a PEP must be approved by the Typing Council. The procedure is described below.

  • Major changes should go through the PEP process, as described in PEP 1. What counts as a major change is not precisely defined, but it would generally include any change of a similar magnitude to previous typing PEPs.

Changes that need Typing Council approval go through three steps:

The Typing Council has published some guidance on useful information to gather when proposing a change to the spec, including:

  • A survey of the current behavior of major type checkers.

  • A rationale for why the proposed behavior is better than alternatives.

  • An implementation or proposed implementation of the proposed behavior in at least one major type checker.