From e8273d3ed3a87718778c0979a4518e07a7a87760 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Tue, 11 Jun 2024 23:12:09 +0100 Subject: [PATCH] Many typing PEPs: add more links to canonical docs (#3821) --- .../pep_processor/parsing/pep_banner_directive.py | 15 ++++++--------- peps/pep-0012.rst | 15 +++++++++++++++ peps/pep-0526.rst | 3 +++ peps/pep-0544.rst | 3 ++- peps/pep-0560.rst | 5 +++-- peps/pep-0585.rst | 3 +++ peps/pep-0586.rst | 3 ++- peps/pep-0589.rst | 3 ++- peps/pep-0591.rst | 3 ++- peps/pep-0593.rst | 3 ++- peps/pep-0612.rst | 3 ++- peps/pep-0613.rst | 3 ++- peps/pep-0647.rst | 3 ++- peps/pep-0655.rst | 4 +++- peps/pep-0673.rst | 3 ++- peps/pep-0675.rst | 3 ++- peps/pep-0681.rst | 3 ++- peps/pep-0698.rst | 3 ++- 18 files changed, 57 insertions(+), 24 deletions(-) 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 fa1475787..00f7b789f 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 8f684fdf0..9ca94ed23 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 6529afbe2..118b77e43 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 1b2d75f37..3b0ec6af3 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 262623864..ea934589d 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 efd78761d..f8e674b88 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 99fe92ca8..4dd36e6f0 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 d4b07b45a..194df0fd5 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 e19260f17..03d09d6cd 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 d7072f7a5..23787e154 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 78aac53b3..d218284b8 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 108cd9583..6aaf9b247 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 8d1131106..b6f02e466 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 1590a3a2d..263cdb096 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 89408c420..5244cefee 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 9cf7ab3ec..1f41253fb 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 8f7450e70..2463d766e 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 7f83ef1a5..84d3b1dda 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 ========