Many typing PEPs: add more links to canonical docs (#3821)

pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py

@@ -108,19 +108,16 @@ class CanonicalTypingSpecBanner(PEPBanner):
     """Insert a specialized admonition for the typing specification."""
 
     admonition_pre_template = (
-        "This PEP is a historical document. "
-        "The up-to-date, canonical spec, {link_content}, is maintained on "
-        f"the `typing specs site <{TYPING_SPEC_BASE_URL}>`__."
-    )
-    admonition_pre_text = (
-        "This PEP is a historical document. "
-        "The up-to-date, canonical specifications are maintained on "
-        f"the `typing specs site <{TYPING_SPEC_BASE_URL}>`__."
+        "This PEP is a historical document: see {link_content} for up-to-date "
+        "specs and documentation. Canonical typing specs are maintained at "
+        f"the `typing specs site <{TYPING_SPEC_BASE_URL}>`__; "
+        "runtime typing behaviour is described in the CPython documentation."
     )
+    admonition_pre_text = admonition_pre_template
     admonition_post_text = (
         "See the `typing specification update process "
         "<https://typing.readthedocs.io/en/latest/spec/meta.html>`__ "
-        "for how to propose changes."
+        "for how to propose changes to the typing spec."
     )
     admonition_class = nodes.attention
 

peps/pep-0012.rst

@@ -693,6 +693,21 @@ which renders as:
 
     .. canonical-pypa-spec:: :ref:`packaging:core-metadata`
 
+For a typing PEP that introduces no new runtime objects,
+you might use something like the first one of these;
+for a typing PEP that introduces a new object to the typing module at runtime,
+you might use the second::
+
+   .. canonical-typing-spec:: :ref:`typing:packaging-typed-libraries`
+   .. canonical-typing-spec:: :ref:`typing:literal-types` and
+                              :py:data:`typing.Literal`
+
+The two render as:
+
+   .. canonical-typing-spec:: :ref:`typing:packaging-typed-libraries`
+   .. canonical-typing-spec:: :ref:`typing:literal-types` and
+                              :py:data:`typing.Literal`
+
 The argument accepts arbitrary reST,
 so you can include multiple linked docs/specs and name them whatever you like,
 and you can also include directive content that will be inserted into the text.

peps/pep-0526.rst

@@ -12,6 +12,9 @@ Python-Version: 3.6
 Post-History: 30-Aug-2016, 02-Sep-2016
 Resolution: https://mail.python.org/pipermail/python-dev/2016-September/146282.html
 
+.. canonical-typing-spec:: :ref:`python:annassign`,
+                           :ref:`typing:classvar` and
+                           :py:data:`typing.ClassVar`
 
 Status
 ======

peps/pep-0544.rst

@@ -10,7 +10,8 @@ Created: 05-Mar-2017
 Python-Version: 3.8
 Resolution: https://mail.python.org/archives/list/typing-sig@python.org/message/FDO4KFYWYQEP3U2HVVBEBR3SXPHQSHYR/
 
-.. canonical-typing-spec:: :ref:`typing:protocols`
+.. canonical-typing-spec:: :ref:`typing:protocols` and
+                           :py:class:`typing.Protocol`
 
 
 Abstract

peps/pep-0560.rst

@@ -9,8 +9,9 @@ Python-Version: 3.7
 Post-History: 09-Sep-2017, 14-Nov-2017
 Resolution: https://mail.python.org/pipermail/python-dev/2017-December/151038.html
 
-.. canonical-doc:: :external+python:meth:`object.__class_getitem__` and
-                   :external+python:meth:`object.__mro_entries__`
+.. canonical-doc:: the documentation for
+                   :external+python:meth:`~object.__class_getitem__` and
+                   :external+python:meth:`~object.__mro_entries__`
 
 Abstract
 ========

peps/pep-0585.rst

@@ -12,6 +12,9 @@ Created: 03-Mar-2019
 Python-Version: 3.9
 Resolution: https://mail.python.org/archives/list/python-dev@python.org/thread/HW2NFOEMCVCTAFLBLC3V7MLM6ZNMKP42/
 
+.. canonical-doc:: :ref:`python:types-genericalias`
+                   and the documentation for :meth:`~object.__class_getitem__`
+
 Abstract
 ========
 

peps/pep-0586.rst

@@ -11,7 +11,8 @@ Python-Version: 3.8
 Post-History: 14-Mar-2019
 Resolution: https://mail.python.org/archives/list/typing-sig@python.org/message/FDO4KFYWYQEP3U2HVVBEBR3SXPHQSHYR/
 
-.. canonical-typing-spec:: :ref:`typing:literal-types`
+.. canonical-typing-spec:: :ref:`typing:literal-types` and
+                           :py:data:`typing.Literal`
 
 Abstract
 ========

peps/pep-0589.rst

@@ -12,7 +12,8 @@ Python-Version: 3.8
 Post-History:
 Resolution: https://mail.python.org/archives/list/typing-sig@python.org/message/FDO4KFYWYQEP3U2HVVBEBR3SXPHQSHYR/
 
-.. canonical-typing-spec:: :ref:`typing:typeddict`
+.. canonical-typing-spec:: :ref:`typing:typeddict` and
+                           :py:class:`typing.TypedDict`
 
 Abstract
 ========

peps/pep-0591.rst

@@ -11,7 +11,8 @@ Python-Version: 3.8
 Post-History:
 Resolution: https://mail.python.org/archives/list/typing-sig@python.org/message/FDO4KFYWYQEP3U2HVVBEBR3SXPHQSHYR/
 
-.. canonical-typing-spec:: :ref:`typing:at-final` and :ref:`typing:uppercase-final`
+.. canonical-typing-spec:: :ref:`typing:at-final`/:py:func:`@typing.final <typing.final>`
+                           and :ref:`typing:uppercase-final`/:py:data:`typing.Final`
 
 Abstract
 ========

peps/pep-0593.rst

@@ -10,7 +10,8 @@ Created: 26-Apr-2019
 Python-Version: 3.9
 Post-History: 20-May-2019
 
-.. canonical-typing-spec:: :ref:`annotated`
+.. canonical-typing-spec:: :ref:`typing:annotated` and
+                           :py:data:`typing.Annotated`
 
 Abstract
 --------

peps/pep-0612.rst

@@ -11,7 +11,8 @@ Created: 18-Dec-2019
 Python-Version: 3.10
 Post-History: 18-Dec-2019, 13-Jul-2020
 
-.. canonical-typing-spec:: :ref:`typing:paramspec`
+.. canonical-typing-spec:: :ref:`typing:paramspec` and
+                           :py:class:`typing.ParamSpec`
 
 Abstract
 --------

peps/pep-0613.rst

@@ -10,7 +10,8 @@ Created: 21-Jan-2020
 Python-Version: 3.10
 Post-History: 21-Jan-2020
 
-.. canonical-typing-spec:: :ref:`typing:type-aliases`
+.. canonical-typing-spec:: :ref:`typing:type-aliases` and
+                           :py:data:`typing.TypeAlias`
 
 Abstract
 ========

peps/pep-0647.rst

@@ -11,7 +11,8 @@ Python-Version: 3.10
 Post-History: 28-Dec-2020, 09-Apr-2021
 Resolution: https://mail.python.org/archives/list/python-dev@python.org/thread/2ME6F6YUVKHOQYKSHTVQQU5WD4CVAZU4/
 
-.. canonical-typing-spec:: :ref:`typing:typeguard`
+.. canonical-typing-spec:: :ref:`typing:typeguard` and
+                           :py:data:`typing.TypeGuard`
 
 Abstract
 ========

peps/pep-0655.rst

@@ -11,7 +11,9 @@ Python-Version: 3.11
 Post-History: 31-Jan-2021, 11-Feb-2021, 20-Feb-2021, 26-Feb-2021, 17-Jan-2022, 28-Jan-2022
 Resolution: https://mail.python.org/archives/list/python-dev@python.org/message/AJEDNVC3FXM5QXNNW5CR4UCT4KI5XVUE/
 
-.. canonical-typing-spec:: :ref:`typing:required-notrequired`
+.. canonical-typing-spec:: :ref:`typing:required-notrequired`,
+                           :py:data:`typing.Required` and
+                           :py:data:`typing.NotRequired`
 
 Abstract
 ========

peps/pep-0673.rst

@@ -12,7 +12,8 @@ Python-Version: 3.11
 Post-History: 17-Nov-2021
 Resolution: https://mail.python.org/archives/list/python-dev@python.org/thread/J7BWL5KWOPQQK5KFWKENVLXW6UGSPTGI/
 
-.. canonical-typing-spec:: :ref:`typing:self`
+.. canonical-typing-spec:: :ref:`typing:self` and
+                           :py:data:`typing.Self`
 
 Abstract
 ========

peps/pep-0675.rst

@@ -11,7 +11,8 @@ Python-Version: 3.11
 Post-History: 07-Feb-2022
 Resolution: https://mail.python.org/archives/list/python-dev@python.org/message/XEOOSSPNYPGZ5NXOJFPLXG2BTN7EVRT5/
 
-.. canonical-typing-spec:: :ref:`typing:literalstring`
+.. canonical-typing-spec:: :ref:`typing:literalstring` and
+                           :py:data:`typing.LiteralString`
 
 Abstract
 ========

peps/pep-0681.rst

@@ -14,7 +14,8 @@ Post-History: `24-Apr-2021 <https://mail.python.org/archives/list/typing-sig@pyt
               `22-Feb-2022 <https://mail.python.org/archives/list/typing-sig@python.org/thread/BW6CB6URC4BCN54QSG2STINU2M7V4TQQ/>`__
 Resolution: https://mail.python.org/archives/list/python-dev@python.org/message/R4A2IYLGFHKFDYJPSDA5NFJ6N7KRPJ6D/
 
-.. canonical-typing-spec:: :ref:`typing:dataclass-transform`
+.. canonical-typing-spec:: :ref:`typing:dataclass-transform` and
+                           :py:func:`@typing.dataclass_transform <typing.dataclass_transform>`
 
 Abstract
 ========

peps/pep-0698.rst

@@ -16,7 +16,8 @@ Post-History: `20-May-2022 <https://mail.python.org/archives/list/typing-sig@pyt
               `07-Nov-2022 <https://discuss.python.org/t/pep-698-a-typing-override-decorator/20839>`__,
 Resolution: https://discuss.python.org/t/pep-698-a-typing-override-decorator/20839/11
 
-.. canonical-typing-spec:: :ref:`typing:override`
+.. canonical-typing-spec:: :ref:`typing:override` and
+                           :py:func:`@typing.override <typing.override>`
 
 Abstract
 ========