The existing TypedDict spec is a concatenation of four different PEPs that introduced and extended the feature set of TypedDict, and it shows; the text is repetitive and doesn’t read as a coherent whole.
Now that PEP 728 has been accepted, I took the opportunity to reorganize and rewrite the text in its entirety to make it more coherent. I unified the discussion of NotRequired, ReadOnly, extra_items=, etc. into the main text and removed excessive examples and discussion from the spec text.
The general approach I took is to first define the kinds of TypedDicts that
can exist, then explain the syntax for defining TypedDicts, then discuss
other aspects of TypedDict types.
I introduce some new terminology around PEP 728 to make it easier to talk
about the different kinds of TypedDict. TypedDicts are defined to have a
property called openness, which can have three states:
- Open: all TypedDicts prior to PEP 728. These allow arbitrary extra keys in assignability, but the constructor only allows known keys.
- Closed: no extra keys are allowed (closed=True)
- With extra items: extra_items=… from PEP 728
This change is not intended to prescribe any changes in type checker behavior, but it’s a lot of changed and new text. In particular, I wrote the assignability rules from scratch in order to cover the implications of non-required, read-only, and extra items coherently. Please take a look and let me know if you find something that doesn’t make sense or that departs from the meaning of the previous spec.