Typing PEPs: Link to the typing spec as canonical documentation

[JelleZijlstra]

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:

• 586 Literal Types: 3.8 PEP 586: Mark as Final #3666
• 589 TypedDict: Type Hints for Dictionaries with a Fixed Set of Keys: 3.8 PEP 589: Mark as Final #3667
• 591 Adding a final qualifier to typing: 3.8 PEP 591: Mark as Final #3668
• 593 Flexible function and variable annotations: 3.9 PEP 593: Mark as Final #3669
• 604 Allow writing union types as X | Y: 3.10 PEP 604: Mark as Final #3677
• 613 Explicit Type Aliases: 3.10 PEP 613: Mark as Final #3670
• 646 Variadic Generics: 3.11 PEP 646: Mark as Final #3671
• 647 User-Defined Type Guards: 3.10 PEP 647: Mark as Final #3577
• 655 Marking individual TypedDict items as required or potentially-missing: 3.11 PEP 655: Mark as Final #3672
• 675 Arbitrary Literal String Type: 3.11 PEP 675: Mark as Final #3673
• 681 Data Class Transforms: 3.11 PEP 681: Mark as Final #3674
• 688 Making the buffer protocol accessible in Python: 3.12 PEP 688: Mark as Final #3678
• 692 Using TypedDict for more precise **kwargs typing: 3.12 PEP 692: Mark as Final #3679
• 695 Type Parameter Syntax: 3.12 PEP 695: Mark as Final #3675
• 698 Override Decorator for Static Typing: 3.12 PEP 698: Mark as Final #3676

Later:

• 563 Postponed Evaluation of Annotations: 3.7 - mark as Superseded by PEP 649 once that lands (hopefully in 3.13)

[hugovk]

And PR #3575 added the ability to add canonical link banners to the typing spec via intersphinx, like:

.. canonical-typing-spec:: :ref:`typing:paramspec`

[hugovk]

I've updated the OP with a checklist.

[hugovk]

[ ] 563 Postponed Evaluation of Annotations: 3.7

Where is the spec for this one?

[JelleZijlstra]

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).

[hugovk]

• 604 Allow writing union types as X | Y: 3.10
• 688 Making the buffer protocol accessible in Python: 3.12
• 692 Using TypedDict for more precise **kwargs typing: 3.12

And how about the specs for these three?

[AlexWaygood]

[ ] 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

[JelleZijlstra]

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

[hugovk]

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: PEP 646 grammar changes are not documented cpython#115528
• The rest are 3.13, too early for those