I propose a new way to govern the Python type system: a committee that maintains a
specification and conformance test suite.
There are a few interrelated problems with the way we currently manage the Python type system:
PEPs are the only specification
The Python language reference covers the symbols in the typing module, but does
not (and should not) go into detail on how the full type system should work.
But PEPs aren’t meant to be living documents; they are change proposals.
It’s hard to clarify the specification
Because the PEPs are the only specification we have, anything that could be seen
as a change to the specification would theoretically require a new PEP. But that
is often too heavy a process for a small change.
The type system is underspecified
While the PEPs provide a specification, they are often not sufficiently precise
(sometimes intentionally so). This is especially true as the combinatorial
complexity of the type system has grown.
It ends up falling to individual type checkers to decide how to navigate
underspecified areas. In cases where type checkers informally coordinate, this
results in de facto standards that aren’t clearly recorded anywhere, making
the type system less accessible to newcomers.
The Steering Council is not well-placed to solve the above problems
The SC has the entire language in its remit, and is not well-placed to make
decisions that are purely about the type system —- if only because they don’t have
the time to deal with type system arcana alongside their other responsibilities.
This is similar in spirit to the reasons why the Steering Council sometimes uses
We propose the creation of a new group, let’s call it the Typing Council. This group will
be responsible for developing and maintaining the Python type system, and
responsible for solving the above problems.
The “operations and process” section describes how this group would operate and
The more exciting “projects” section describes solutions to the above problems
that the Typing Council could shepherd.
We’re open to changing the details here, but this is a possible description of how
the council would operate.
The council has three members, which are appointed by the Steering Council among
prominent community members, such as Python core developers and maintainers of
major type checkers. Normally council members serve one-year terms, renewable
indefinitely, but they may resign or be removed by the Steering Council at any
time. (Removal by the Steering Council should be an exceptional situation in
case of major misconduct, inactivity, or similar situations.)
The council would operate primarily through reviews of GitHub PRs. Regular
meetings are likely not necessary, but the council may set up video calls, a
private chat, or whatever other mechanism they decide upon internally.
The council should aim for transparency, posting all decisions publicly, with a
rationale if possible.
Just like today, the Python Steering Council would remain responsible for the
overall direction of the Python language and would continue to decide on
typing-related PEPs. However, smaller changes to the type system could be made
by the Typing Council directly, and the Steering Council may delegate the
decision on some PEPs to the Typing Council.
Some examples of how past and recent issues could have been handled under this model:
- A PEP like PEP 695 (type parameter syntax),
which changes the language syntax,
would be decided upon by the Steering Council, but they could consult the
Typing Council for opinions or endorsements. Similarly, PEPs like
PEP 702 would be decided upon by the Steering
Council, because it expands the type system beyond pure typing. Other examples we
expect would be decided by the SC include PEPs like
PEP 718 and PEP 727.
- A PEP like PEP 698 (
which affects only users of type checkers
and does not change the overall language, would likely be delegated by the SC
to the Typing Council for a decision, exactly as any other PEP delegation.
Other examples we expect would be delegated include PEPs like
PEP 647, PEP 655,
PEP 673, PEP 675.
- Adding a smaller feature, such as
Neveras an alias for
NoReturn, would be
done by means of a PR to the spec and conformance test suite. The Typing
Council would then decide whether or not to merge the PR. They may ask for the
feature to be specified and discussed in a PEP if they feel that is warranted.
- If there is confusion about the interpretation of some part of the spec, like
happened recently with partial stubs in PEP
somebody would make a PR to the typing specifications to clarify the
spec, and then the Typing Council would decide on the spec change.
Here are some efforts a Typing Council would be responsible for.
A conformance test suite would provide machine checkable documentation for how
type checkers should check Python code, accompanied by the results of major type
checker implementations on the test suite. A rough sketch for what this could
look like is GitHub - hauntsaninja/type_checker_consistency.
This would contain prescriptive tests from behavior prescribed by previous PEPs
and descriptive tests that let us document behavior of existing implementations
in areas that are not prescribed by any standard. These descriptions would be
useful to inform efforts below and to identify areas of focus for
A specification could initially be created by stitching together the
specification sections from the existing PEPs, and then gradually improved to
clarify points of confusion and cover more areas.
Kevin Millikin’s document on “Python Static Types”
could provide a basis for formalizing much of the spec.
The specification has a few audiences:
- For type checkers, it provides a description of how an idealized type checker
should behave. Individual type checkers have different goals and technical
constraints and they are free to deviate from the spec if they do not have the
resources to fully implement it or if they believe a different behavior better
serves their users. However, they should document such deviations from the
- For projects such as typeshed, or libraries that want to be compatible with
multiple type checkers, it provides a set of rules that they can follow to
make their code understood by type checkers.
- For people who want to propose changes to the type system, it provides a
foundation for any new proposals.
There are different opinions within the community about how formal such a
specification should be. This document does not aim to resolve those
disagreements, but it provides a process that would enable the creation of a
spec at the community’s desired level of formality.
Documentation is important for the success of the Python type system, so
the Typing Council should ensure that there is good documentation for the
As mentioned previously, PEPs are point in time change proposals aimed at
multiple audiences that are hard to clarify. This makes them ill-suited as user
documentation. The specification discussed in the previous section would
be a living document, but it would likely be too technical to serve as
documentation for normal usage.
Therefore, a separate user-facing reference for the type system would be
useful. Such an effort could expand the documentation on
Static Typing with Python — typing documentation.
This is an informal writeup. I previously shared it privately with a few people (including @hauntsaninja, who helped to greatly improve the text—thanks!), to a generally positive reception. If it is received well, I will convert it into
a PEP and approved by the Steering Council. Then the SC will appoint the initial
Typing Council, which should then start putting together the spec.