Skip to content

gh-106745: typing docs: Clarify that removal of PEP-585 aliases is not currently planned #106748

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jul 14, 2023
Merged

gh-106745: typing docs: Clarify that removal of PEP-585 aliases is not currently planned #106748

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
20473d4
gh-106745: typing docs: Clarify that removal of PEP-585 aliases is no…
AlexWaygood Jul 14, 2023
62ec6e0
Wordsmithing
AlexWaygood Jul 14, 2023
e6dc18b
.
AlexWaygood Jul 14, 2023
7b6d7bf
Clarify recommendation to type checkers
AlexWaygood Jul 14, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 45 additions & 25 deletions Doc/library/typing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3101,6 +3101,7 @@ Constant
.. versionadded:: 3.5.2

.. _generic-concrete-collections:
.. _deprecated-aliases:

Deprecated aliases
------------------
Expand All @@ -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, removal of these aliases is not currently
planned. As such, no deprecation warnings are currently issued by the
interpreter for these aliases.

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aha, so these are "soft deprecated".

https://peps.python.org/pep-0387/#soft-deprecation

It's a new term added in python/peps#3182.

Would referencing that help add clarity?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm honestly not sure it would add clarity, to be honest :/ I feel like it might be just another cross-reference that people would have to look up if they're reading the docs.

I'm not aware of another module that has a similar situation where so much of the module is soft-deprecated. (In Python 3.13, 42 out of 101 items in typing.__all__ are soft-deprecated!) So I think I'd rather keep a verbose description in the typing docs of how we'll be specifically handling the typing deprecations, and treat them as their own unique thing, without reference to the broader concept of "soft deprecation"

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay!

(optparse and getopt (and likely several other modules) are 100% soft deprecated :)

Copy link
Member Author

@AlexWaygood AlexWaygood Jul 14, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(optparse and getopt (and likely several other modules) are 100% soft deprecated :)

True!

(I still think I'd rather keep the explanation of what these deprecations mean inside the typing docs, though, rather than linking to the broader concept of soft deprecations. It's pretty important information for a lot of people who'll be visiting the docs.)


Type checkers are encouraged to flag uses of the deprecated types if the
program they are checking targets a minimum Python version of 3.9 or newer.

.. _corresponding-to-built-in-types:

Expand Down Expand Up @@ -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 <no_type_check_decorator>`
- 3.13
- 3.15
- :gh:`106309`