python
Typing PEPs: Link to the typing spec as canonical documentation
The text of typing PEPs has often served as the canonical reference for how aspects of the type system work. Now that we have the typing spec in place, we should link to it as the canonical documentation, just as we do for packing PEPs that link to packaging.python.org.
(Cross-referencing python/typing#1531, which should make this easier by adding more link targets within the spec.)
TODO:
From https://peps.python.org/topic/typing/#accepted-peps-accepted-may-not-be-implemented-yet:
- [x] 586 Literal Types: 3.8 https://github.com/python/peps/pull/3666
- [x] 589 TypedDict: Type Hints for Dictionaries with a Fixed Set of Keys: 3.8 https://github.com/python/peps/pull/3667
- [x] 591 Adding a final qualifier to typing: 3.8 https://github.com/python/peps/pull/3668
- [x] 593 Flexible function and variable annotations: 3.9 https://github.com/python/peps/pull/3669
- [x] 604 Allow writing union types as X | Y: 3.10 https://github.com/python/peps/pull/3677
- [x] 613 Explicit Type Aliases: 3.10 https://github.com/python/peps/pull/3670
- [ ] 646 Variadic Generics: 3.11 https://github.com/python/peps/pull/3671
- [x] 647 User-Defined Type Guards: 3.10 https://github.com/python/peps/pull/3577
- [x] 655 Marking individual TypedDict items as required or potentially-missing: 3.11 https://github.com/python/peps/pull/3672
- [x] 675 Arbitrary Literal String Type: 3.11 https://github.com/python/peps/pull/3673
- [x] 681 Data Class Transforms: 3.11 https://github.com/python/peps/pull/3674
- [x] 688 Making the buffer protocol accessible in Python: 3.12 https://github.com/python/peps/pull/3678
- [x] 692 Using TypedDict for more precise **kwargs typing: 3.12 https://github.com/python/peps/pull/3679
- [x] 695 Type Parameter Syntax: 3.12 https://github.com/python/peps/pull/3675
- [x] 698 Override Decorator for Static Typing: 3.12 https://github.com/python/peps/pull/3676
Later:
- [ ] 563 Postponed Evaluation of Annotations: 3.7 - mark as Superseded by PEP 649 once that lands (hopefully in 3.13)
And PR https://github.com/python/peps/pull/3575 added the ability to add canonical link banners to the typing spec via intersphinx, like:
.. canonical-typing-spec:: :ref:`typing:paramspec`
PEP 563 was mostly about runtime behavior, not typing behavior. I think it should not be marked final, but Superseded by PEP 649 once that lands (hopefully in 3.13).
And how about the specs for these three?
[ ] 604 Allow writing union types as X | Y: 3.10
https://docs.python.org/3/library/stdtypes.html#union-type might do pretty well for that one
688 should point to https://docs.python.org/3/reference/datamodel.html#emulating-buffer-types.
692 should point to https://typing.readthedocs.io/en/latest/spec/callables.html#unpack-for-keyword-arguments
Almost done!
https://peps.python.org/topic/typing/#accepted-peps-accepted-may-not-be-implemented-yet shows:
Accepted PEPs (accepted; may not be implemented yet)
| PEP | Title | Authors | ||
|---|---|---|---|---|
| SA | 563 | Postponed Evaluation of Annotations | Łukasz Langa | 3.7 |
| SA | 646 | Variadic Generics | Mark Mendoza, Matthew Rahtz, Pradeep Kumar Srinivasan, Vincent Siles | 3.11 |
| SA | 649 | Deferred Evaluation Of Annotations Using Descriptors | Larry Hastings | 3.13 |
| SA | 696 | Type Defaults for Type Parameters | James Hilton-Balfe | 3.13 |
| SA | 702 | Marking deprecations using the type system | Jelle Zijlstra | 3.13 |
| SA | 705 | TypedDict: Read-only items | Alice Purcell | 3.13 |
- 563 is pending being superseded by 649 in 3.13
- 646 is pending docs update: https://github.com/python/cpython/issues/115528
- The rest are 3.13, too early for those
All done except for PEP 563/649, which is being implemented for 3.14, so we can mark that as final separately when the time comes.
Thanks all, let's close this!