From 20473d417498219bfa712f49158aefdb965015e7 Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Fri, 14 Jul 2023 17:16:30 +0100 Subject: [PATCH 1/4] gh-106745: typing docs: Clarify that removal of PEP-585 aliases is not currently planned --- Doc/library/typing.rst | 70 +++++++++++++++++++++++++++--------------- 1 file changed, 45 insertions(+), 25 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 0cf875582f7f42..b0b3ba60ce2a18 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -3101,6 +3101,7 @@ Constant .. versionadded:: 3.5.2 .. _generic-concrete-collections: +.. _deprecated-aliases: Deprecated aliases ------------------ @@ -3109,16 +3110,21 @@ This module defines several deprecated aliases to pre-existing standard library classes. These were originally included in the typing module in order to support parameterizing these generic classes using ``[]``. However, the aliases became redundant in Python 3.9 when the -corresponding pre-existing classes were enhanced to support ``[]``. +corresponding pre-existing classes were enhanced to support ``[]`` (see +:pep:`585`). -The redundant types are deprecated as of Python 3.9 but no -deprecation warnings are issued by the interpreter. -It is expected that type checkers will flag the deprecated types -when the checked program targets Python 3.9 or newer. +The redundant types are deprecated as of Python 3.9. However, while the aliases +may be removed at some point, but removal is not currently planned for the +foreseeable future. As such, no deprecation warnings are currently issued by +the interpreter. -The deprecated types will be removed from the :mod:`typing` module -no sooner than the first Python version released 5 years after the release of Python 3.9.0. -See details in :pep:`585`—*Type Hinting Generics In Standard Collections*. +If at some point it is decided to remove these deprecated aliases, a +deprecation warning will be issued by the interpreter for at least two releases +prior to removal. The aliases are guaranteed to remain in the typing module +without deprecation warnings until at least Python 3.14. + +Type checkers are encouraged to flag uses of the deprecated types if the +program they are checking targets Python 3.9 or newer. .. _corresponding-to-built-in-types: @@ -3651,20 +3657,34 @@ Certain features in ``typing`` are deprecated and may be removed in a future version of Python. The following table summarizes major deprecations for your convenience. This is subject to change, and not all deprecations are listed. -+-------------------------------------+---------------+-------------------+----------------+ -| Feature | Deprecated in | Projected removal | PEP/issue | -+=====================================+===============+===================+================+ -| ``typing`` versions of standard | 3.9 | Undecided | :pep:`585` | -| collections | | | | -+-------------------------------------+---------------+-------------------+----------------+ -| ``typing.ByteString`` | 3.9 | 3.14 | :gh:`91896` | -+-------------------------------------+---------------+-------------------+----------------+ -| ``typing.Text`` | 3.11 | Undecided | :gh:`92332` | -+-------------------------------------+---------------+-------------------+----------------+ -| ``typing.Hashable`` and | 3.12 | Undecided | :gh:`94309` | -| ``typing.Sized`` | | | | -+-------------------------------------+---------------+-------------------+----------------+ -| ``typing.TypeAlias`` | 3.12 | Undecided | :pep:`695` | -+-------------------------------------+---------------+-------------------+----------------+ -| ``typing.no_type_check_decorator`` | 3.13 | 3.15 | :gh:`106309` | -+-------------------------------------+---------------+-------------------+----------------+ +.. list-table:: + :header-rows: 1 + + * - Feature + - Deprecated in + - Projected removal + - PEP/issue + * - ``typing`` versions of standard collections + - 3.9 + - Undecided (see :ref:`deprecated-aliases` for more information) + - :pep:`585` + * - :class:`typing.ByteString` + - 3.9 + - 3.14 + - :gh:`91896` + * - :data:`typing.Text` + - 3.11 + - Undecided + - :gh:`92332` + * - :class:`typing.Hashable` and :class:`typing.Sized` + - 3.12 + - Undecided + - :gh:`94309` + * - :data:`typing.TypeAlias` + - 3.12 + - Undecided + - :pep:`695` + * - :func:`@typing.no_type_check_decorator ` + - 3.13 + - 3.15 + - :gh:`106309` From 62ec6e08b8b64ce41b206fcd20da551e379e4c74 Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Fri, 14 Jul 2023 17:21:14 +0100 Subject: [PATCH 2/4] Wordsmithing --- Doc/library/typing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index b0b3ba60ce2a18..da64beb1a90ad1 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -3114,9 +3114,9 @@ corresponding pre-existing classes were enhanced to support ``[]`` (see :pep:`585`). The redundant types are deprecated as of Python 3.9. However, while the aliases -may be removed at some point, but removal is not currently planned for the -foreseeable future. As such, no deprecation warnings are currently issued by -the interpreter. +may be removed at some point, removal of these aliases is not currently planned +for the foreseeable future. As such, no deprecation warnings are currently +issued by the interpreter for these aliases. If at some point it is decided to remove these deprecated aliases, a deprecation warning will be issued by the interpreter for at least two releases From e6dc18b72cff40f2db1e03d0ed1c8f465d75cba7 Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Fri, 14 Jul 2023 17:22:28 +0100 Subject: [PATCH 3/4] . --- Doc/library/typing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index da64beb1a90ad1..99cc033ad86d4d 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -3114,9 +3114,9 @@ corresponding pre-existing classes were enhanced to support ``[]`` (see :pep:`585`). The redundant types are deprecated as of Python 3.9. However, while the aliases -may be removed at some point, removal of these aliases is not currently planned -for the foreseeable future. As such, no deprecation warnings are currently -issued by the interpreter for these aliases. +may be removed at some point, removal of these aliases is not currently +planned. As such, no deprecation warnings are currently issued by the +interpreter for these aliases. If at some point it is decided to remove these deprecated aliases, a deprecation warning will be issued by the interpreter for at least two releases From 7b6d7bfa0ec5190547d2345e881c804ff425043c Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Fri, 14 Jul 2023 17:23:56 +0100 Subject: [PATCH 4/4] Clarify recommendation to type checkers --- 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 99cc033ad86d4d..0265a39ce646f4 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -3124,7 +3124,7 @@ prior to removal. The aliases are guaranteed to remain in the typing module without deprecation warnings until at least Python 3.14. Type checkers are encouraged to flag uses of the deprecated types if the -program they are checking targets Python 3.9 or newer. +program they are checking targets a minimum Python version of 3.9 or newer. .. _corresponding-to-built-in-types: