From 214cee97bfc85671f2e7b6ec6a415b797adcff49 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Thu, 28 Oct 2021 19:24:05 +0100 Subject: [PATCH 1/4] bpo-45655: Add "relevant PEPs" section to ``typing`` documentation 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. --- Doc/library/typing.rst | 42 +++++++++++++++---- .../2021-10-28-19-22-55.bpo-45655.aPYGaS.rst | 2 + 2 files changed, 37 insertions(+), 7 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2021-10-28-19-22-55.bpo-45655.aPYGaS.rst diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index e5e7941833bebb..39006ae0d49980 100644 --- 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,36 @@ 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` decorator +* :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` decorator +* :pep:`593`: Flexible function and variable annotations + *Introducing* :data:`Annotated` +* :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/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 index 00000000000000..fc5b3d07888175 --- /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. From 9d4ecca08575f1b4b594ab5c3d9e736a962da866 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Thu, 28 Oct 2021 19:33:00 +0100 Subject: [PATCH 2/4] Remove trailing whitespace --- Doc/library/typing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 39006ae0d49980..6baeb9bb37e889 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -38,7 +38,7 @@ arguments. Relevant PEPs ============= -Since the initial introduction of type hints in :pep:`484` and :pep:`483`, a +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: From 4788120251596d2f68ab4515eceeb39691dae569 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Langa?= Date: Thu, 28 Oct 2021 21:20:33 +0200 Subject: [PATCH 3/4] Add two more PEPs --- Doc/library/typing.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 6baeb9bb37e889..bc2e0e1e09ae38 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -48,6 +48,9 @@ annotations. These include: * :pep:`544`: Protocols: Structural subtyping (static duck typing) *Introducing* :class:`Protocol` and the :func:`@runtime_checkable` decorator +* :pep:`585`: Type Hinting Generics In Standard Collections + *Introducing* the ability to use builtin collections and ABCs as + :term:`generic types ` * :pep:`586`: Literal Types *Introducing* :data:`Literal` * :pep:`589`: TypedDict: Type Hints for Dictionaries with a Fixed Set of Keys @@ -56,6 +59,9 @@ annotations. These include: *Introducing* :data:`Final` and the :func:`@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 the union * :pep:`612`: Parameter Specification Variables *Introducing* :class:`ParamSpec` and :data:`Concatenate` * :pep:`613`: Explicit Type Aliases From 7d90863c1dc0cd74e8be0f5efe333e35a76d4709 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Thu, 28 Oct 2021 20:33:44 +0100 Subject: [PATCH 4/4] Remove trailing whitespace, tweak `UnionType` wording --- Doc/library/typing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index bc2e0e1e09ae38..6f501ec136ee6e 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -50,7 +50,7 @@ annotations. These include: :func:`@runtime_checkable` decorator * :pep:`585`: Type Hinting Generics In Standard Collections *Introducing* the ability to use builtin collections and ABCs as - :term:`generic types ` + :term:`generic types` * :pep:`586`: Literal Types *Introducing* :data:`Literal` * :pep:`589`: TypedDict: Type Hints for Dictionaries with a Fixed Set of Keys @@ -61,7 +61,7 @@ annotations. These include: *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 the union + 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