[3.10] bo-45655: Add "relevant PEPs" section to typing documentation (GH-29302)

The list of PEPs at the top of the documentation for the ``typing`` module has
become too long to be readable. This PR proposes presenting this
information in a more structured and readable way by adding a new "relevant
PEPs" section to the ``typing`` docs.

(cherry picked from commit 03db1bbfd2d3f5a343c293b2f0e09a1e962df7ea)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: Łukasz Langa <lukasz@langa.pl>

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index c402c73b487eab00e933c2eb11e02221a813bfae..e5b0468399e50bc0a56a7a14e17ae2584eb75497 100644 (file)
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -17,13 +17,11 @@
 
 --------------
 
-This module provides runtime support for type hints as specified by
-:pep:`484`, :pep:`526`, :pep:`544`, :pep:`586`, :pep:`589`, :pep:`591`,
-:pep:`593`, :pep:`612`, :pep:`613` and :pep:`647`.
-The most fundamental support consists of the types :data:`Any`, :data:`Union`,
-:data:`Tuple`, :data:`Callable`, :class:`TypeVar`, and
-:class:`Generic`.  For full specification please see :pep:`484`.  For
-a simplified introduction to type hints see :pep:`483`.
+This module provides runtime support for type hints. The most fundamental
+support consists of the types :data:`Any`, :data:`Union`, :data:`Tuple`,
+:data:`Callable`, :class:`TypeVar`, and :class:`Generic`. For a full
+specification, please see :pep:`484`. For a simplified introduction to type
+hints, see :pep:`483`.
 
 
 The function below takes and returns a string and is annotated as follows::
@@ -35,6 +33,42 @@ In the function ``greeting``, the argument ``name`` is expected to be of type
 :class:`str` and the return type :class:`str`. Subtypes are accepted as
 arguments.
 
+.. _relevant-peps:
+
+Relevant PEPs
+=============
+
+Since the initial introduction of type hints in :pep:`484` and :pep:`483`, a
+number of PEPs have modified and enhanced Python's framework for type
+annotations. These include:
+
+* :pep:`526`: Syntax for Variable Annotations
+     *Introducing* syntax for annotating variables outside of function
+     definitions, and :data:`ClassVar`
+* :pep:`544`: Protocols: Structural subtyping (static duck typing)
+     *Introducing* :class:`Protocol` and the
+     :func:`@runtime_checkable<runtime_checkable>` decorator
+* :pep:`585`: Type Hinting Generics In Standard Collections
+     *Introducing* the ability to use builtin collections and ABCs as
+     :term:`generic types<generic type>`
+* :pep:`586`: Literal Types
+     *Introducing* :data:`Literal`
+* :pep:`589`: TypedDict: Type Hints for Dictionaries with a Fixed Set of Keys
+     *Introducing* :class:`TypedDict`
+* :pep:`591`: Adding a final qualifier to typing
+     *Introducing* :data:`Final` and the :func:`@final<final>` decorator
+* :pep:`593`: Flexible function and variable annotations
+     *Introducing* :data:`Annotated`
+* :pep:`604`: Allow writing union types as ``X | Y``
+     *Introducing* :data:`types.UnionType` and the ability to use
+     the binary-or operator ``|`` as syntactic sugar for a union of types
+* :pep:`612`: Parameter Specification Variables
+     *Introducing* :class:`ParamSpec` and :data:`Concatenate`
+* :pep:`613`: Explicit Type Aliases
+     *Introducing* :data:`TypeAlias`
+* :pep:`647`: User-Defined Type Guards
+     *Introducing* :data:`TypeGuard`
+
 .. _type-aliases:
 
 Type aliases

diff --git a/Doc/tools/susp-ignored.csv b/Doc/tools/susp-ignored.csv
index 54360c2f8ebaa94960b1b6f702e04b46464510d8..9cbd09ad20357147577de6f71a6d6587c44d0c91 100644 (file)
--- a/Doc/tools/susp-ignored.csv
+++ b/Doc/tools/susp-ignored.csv
@@ -376,7 +376,7 @@ library/importlib.metadata,,:main,"EntryPoint(name='wheel', value='wheel.cli:mai
 library/importlib.metadata,,`,loading the metadata for packages for the indicated ``context``.
 library/re,,`,"`"
 using/configure,84,:db2,=db1:db2:...
-library/typing,1011,`,# Type of ``val`` is narrowed to ``str``
-library/typing,1011,`,"# Else, type of ``val`` is narrowed to ``float``."
-library/typing,1011,`,# Type of ``val`` is narrowed to ``List[str]``.
-library/typing,1011,`,# Type of ``val`` remains as ``List[object]``.
+library/typing,,`,# Type of ``val`` is narrowed to ``str``
+library/typing,,`,"# Else, type of ``val`` is narrowed to ``float``."
+library/typing,,`,# Type of ``val`` is narrowed to ``List[str]``.
+library/typing,,`,# Type of ``val`` remains as ``List[object]``.

diff --git a/Misc/NEWS.d/next/Documentation/2021-10-28-19-22-55.bpo-45655.aPYGaS.rst b/Misc/NEWS.d/next/Documentation/2021-10-28-19-22-55.bpo-45655.aPYGaS.rst
new file mode 100644 (file)
index 0000000..fc5b3d0
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2021-10-28-19-22-55.bpo-45655.aPYGaS.rst
@@ -0,0 +1,2 @@
+Add a new "relevant PEPs" section to the top of the documentation for the
+``typing`` module. Patch by Alex Waygood.