Skip to content

gh-132941: Soft deprecate various typing classes #154480

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

Open
srittau wants to merge 6 commits into
base: main
Choose a base branch
from
Open

gh-132941: Soft deprecate various typing classes #154480

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b410a8b
Soft deprecate various typing classes
srittau Jul 22, 2026
6013f1f
Fix missing space
srittau Jul 22, 2026
bb72945
Add missing type parameters
srittau Jul 22, 2026
467ec51
Use soft deprecation marker
srittau Jul 22, 2026
65cf186
Add items to the soft deprecations document
srittau Jul 22, 2026
f867aeb
Add items to deprecations table
srittau Jul 22, 2026
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
16 changes: 16 additions & 0 deletions Doc/deprecations/soft-deprecations.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,19 @@ There are no plans to remove :term:`soft deprecated` APIs.

(Contributed by Gregory P. Smith in :gh:`86519` and
Hugo van Kemenade in :gh:`148100`.)

* The following typing-related classes are :term:`soft deprecated`:

* :class:`typing.Optional` in favor of the dedicated union syntax
(``X | None``)
* :class:`typing.NoReturn` in favor of :class:`typing.Never`
* :class:`typing.ForwardRef` in favor of :class:`annotationlib.ForwardRef`
* :class:`types.UnionType` in favor of :class:`typing.Union` (but see below)

Creating :class:`typing.Union` instances using the constructor is also
deprecated. Use the dedicated union syntax (``X | Y``) instead.

Explicitly inheriting from :class:`typing.Generic` is also deprecated.
Use the dedicated syntax for :ref:`generic functions <generic-functions>`,
:ref:`generic classes <generic-classes>`, and
:ref:`generic type aliases <generic-type-aliases>` instead.
4 changes: 4 additions & 0 deletions Doc/library/types.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -318,6 +318,10 @@ Standard names are defined for the following types:

This is now an alias for :class:`typing.Union`.

.. soft-deprecated:: 3.16

Use :class:`typing.Union` instead.

@sobolevn sobolevn Jul 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Maybe we should suggest using |?

@JelleZijlstra JelleZijlstra Jul 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

The | syntax creates instances of typing.Union, which types.UnionType is now an alias for (as the line before indicates).

I think this is clear enough when combined with the previous line.

@srittau srittau Jul 22, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I think both would be beneficial:

Use the ``X | Y`` syntax to create ``Union`` instances and :class:typing.Union for all other purposes.


.. class:: TracebackType(tb_next, tb_frame, tb_lasti, tb_lineno)

The type of traceback objects such as found in ``sys.exception().__traceback__``.
Expand Down
Loading
Loading