diff --git a/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py b/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py index fa147578775..00f7b789fec 100644 --- a/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py +++ b/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 " "`__ " - "for how to propose changes." + "for how to propose changes to the typing spec." ) admonition_class = nodes.attention diff --git a/peps/pep-0012.rst b/peps/pep-0012.rst index 8f684fdf0f1..9ca94ed2304 100644 --- a/peps/pep-0012.rst +++ b/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. diff --git a/peps/pep-0526.rst b/peps/pep-0526.rst index 6529afbe229..118b77e4397 100644 --- a/peps/pep-0526.rst +++ b/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 ====== diff --git a/peps/pep-0544.rst b/peps/pep-0544.rst index 1b2d75f3728..3b0ec6af333 100644 --- a/peps/pep-0544.rst +++ b/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 diff --git a/peps/pep-0560.rst b/peps/pep-0560.rst index 2626238643f..ea934589d3e 100644 --- a/peps/pep-0560.rst +++ b/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 ======== diff --git a/peps/pep-0585.rst b/peps/pep-0585.rst index efd78761d76..f8e674b8872 100644 --- a/peps/pep-0585.rst +++ b/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 ======== diff --git a/peps/pep-0586.rst b/peps/pep-0586.rst index 99fe92ca8df..4dd36e6f0fa 100644 --- a/peps/pep-0586.rst +++ b/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 ======== diff --git a/peps/pep-0589.rst b/peps/pep-0589.rst index d4b07b45a0a..194df0fd5f6 100644 --- a/peps/pep-0589.rst +++ b/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 ======== diff --git a/peps/pep-0591.rst b/peps/pep-0591.rst index e19260f176c..03d09d6cda5 100644 --- a/peps/pep-0591.rst +++ b/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 ` + and :ref:`typing:uppercase-final`/:py:data:`typing.Final` Abstract ======== diff --git a/peps/pep-0593.rst b/peps/pep-0593.rst index d7072f7a52b..23787e15453 100644 --- a/peps/pep-0593.rst +++ b/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 -------- diff --git a/peps/pep-0612.rst b/peps/pep-0612.rst index 78aac53b30c..d218284b840 100644 --- a/peps/pep-0612.rst +++ b/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 -------- diff --git a/peps/pep-0613.rst b/peps/pep-0613.rst index 108cd958389..6aaf9b2478d 100644 --- a/peps/pep-0613.rst +++ b/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 ======== diff --git a/peps/pep-0647.rst b/peps/pep-0647.rst index 8d1131106bd..b6f02e466fe 100644 --- a/peps/pep-0647.rst +++ b/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 ======== diff --git a/peps/pep-0655.rst b/peps/pep-0655.rst index 1590a3a2d6c..263cdb09685 100644 --- a/peps/pep-0655.rst +++ b/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 ======== diff --git a/peps/pep-0673.rst b/peps/pep-0673.rst index 89408c420d4..5244cefeeb9 100644 --- a/peps/pep-0673.rst +++ b/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 ======== diff --git a/peps/pep-0675.rst b/peps/pep-0675.rst index 9cf7ab3ec74..1f41253fb47 100644 --- a/peps/pep-0675.rst +++ b/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 ======== diff --git a/peps/pep-0681.rst b/peps/pep-0681.rst index 8f7450e7062..2463d766ef1 100644 --- a/peps/pep-0681.rst +++ b/peps/pep-0681.rst @@ -14,7 +14,8 @@ Post-History: `24-Apr-2021 `__ 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 ` Abstract ======== diff --git a/peps/pep-0698.rst b/peps/pep-0698.rst index 7f83ef1a522..84d3b1ddaf5 100644 --- a/peps/pep-0698.rst +++ b/peps/pep-0698.rst @@ -16,7 +16,8 @@ Post-History: `20-May-2022 `__, 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 ` Abstract ========