Procedure for changing the spec

Typing
1

I just posted a PR explaining the procedure for changing the typing spec. It’s what we’ve already followed for a few changes that are in flight, but I think the intended procedure hasn’t been documented very clearly, so I’m proposing to add the procedure to the spec itself, where it will hopefully be easy to find.

The procedure is as follows:

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.
  • 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.
  • Substantive changes that do not rise to the level of a PEP must
    be approved by the Typing Council. The procedure is described below.

Changes that need Typing Council approval go through three steps:

My hope is that this procedure is as simple as possible while giving enough opportunity for community input and ensuring that future changes improve the quality of the spec.

7 Likes
3

It would be great to have something more concrete around what needs a PEP.

  • Anything which needs a new type or extends/changes core behaviour of an existing type seems pretty clearly in need of a PEP; e.g. PEP 705 adding ReadOnly, or a potential PEP allowing ReadOnly to be used in more places
  • Does nailing down ambiguity in existing types need a PEP? e.g. the recent pinning down of inheritance and Any? This only affects typecheckers, not runtime Python, is that sufficiently non-major?

Knowing where the boundary is would be very helpful, I think.

4

I’m not opposed to adding a more concrete definition, but I don’t know if it will be possible to come up with sufficiently precise wording. My intuition for your concrete examples and a few others that I thought of:

  • Adding a new special form like ReadOnly definitely needs a PEP
  • Expanding ReadOnly to a totally new context (e.g., using it in protocols) would need a PEP. Analogy: PEP 692.
  • PEP 724 (stricter TypeGuards) was appropriately a PEP because it changed a behavior that was central to a previously accepted PEP.
  • TypeGuard/bool compatibility, which also changed a behavior codified in a previous PEP, didn’t need a new PEP because it concerned an edge case that wasn’t central to the previous PEP.
  • The Any inheritance issue doesn’t need a PEP as it is mostly clarifying an ambiguity that is present in the existing spec.

If in doubt about a specific issue, feel free to ask and people on the Typing Council can give their opinion on whether a specific change needs a PEP.

2 Likes