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 12 commits into
base: main
Choose a base branch
from
+114 −67
Open

gh-132941: Soft deprecate various typing classes #154480

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
12 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
c94c53b
Merge branch 'main' into typing-deprecations
srittau Oct 20, 2026
66f5110
Use a semicolon
srittau Oct 20, 2026
000a298
Split aliases from classes
srittau Oct 20, 2026
3b2eb5a
Reshuffle deprecations document
srittau Oct 20, 2026
31b9a9f
Suggest `X | Y` in deprecation message
srittau Oct 20, 2026
d78de26
Merge branch 'main' into typing-deprecations
srittau Oct 28, 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
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`.

.. deprecated:: 3.16
Comment thread
srittau marked this conversation as resolved.
Outdated

Use :class:`typing.Union` instead.
Comment thread
srittau marked this conversation as resolved.
Outdated

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

The type of traceback objects such as found in ``sys.exception().__traceback__``.
Expand Down
107 changes: 53 additions & 54 deletions Doc/library/typing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -582,32 +582,17 @@ can be parameterised at runtime (e.g. ``LoggedVar[int]`` below)::
A generic type can have any number of type variables. All varieties of
:class:`TypeVar` are permissible as parameters for a generic type::

from typing import TypeVar, Generic, Sequence
from typing import Sequence

class WeirdTrio[T, B: Sequence[bytes], S: (int, str)]:
...

OldT = TypeVar('OldT', contravariant=True)
OldB = TypeVar('OldB', bound=Sequence[bytes], covariant=True)
OldS = TypeVar('OldS', int, str)

class OldWeirdTrio(Generic[OldT, OldB, OldS]):
...

Each type variable argument to :class:`Generic` must be distinct.
This is thus invalid::

from typing import TypeVar, Generic
...

class Pair[M, M]: # SyntaxError
...

T = TypeVar('T')

class Pair(Generic[T, T]): # INVALID
...

Generic classes can also inherit from other classes::

from collections.abc import Sized
Expand Down Expand Up @@ -678,7 +663,8 @@ to this is that a list of types can be used to substitute a :class:`ParamSpec`::
>>> Z[int, [dict, float]]
__main__.Z[int, [dict, float]]

Classes generic over a :class:`ParamSpec` can also be created using explicit
For compatibility with Python 3.11 and below, classes generic over a
:class:`ParamSpec` can also be created using explicit
inheritance from :class:`Generic`. In this case, ``**`` is not used::

from typing import ParamSpec, Generic
Expand Down Expand Up @@ -949,7 +935,7 @@ using ``[]``.
They can be used to indicate that a function never returns,
such as :func:`sys.exit`::

from typing import Never # or NoReturn
from typing import Never

def stop() -> Never:
raise RuntimeError('no way')
Expand All @@ -958,7 +944,7 @@ using ``[]``.
called, as there are no valid arguments, such as
:func:`assert_never`::

from typing import Never # or NoReturn
from typing import Never

def never_call_me(arg: Never) -> None:
pass
Expand All @@ -971,7 +957,7 @@ using ``[]``.
case str():
print("It's a str")
case _:
never_call_me(arg) # OK, arg is of type Never (or NoReturn)
never_call_me(arg) # OK, arg is of type Never

:data:`!Never` and :data:`!NoReturn` have the same meaning in the type system
and static type checkers treat both equivalently.
Expand All @@ -984,6 +970,9 @@ using ``[]``.

Added :data:`Never`.

.. deprecated:: 3.16
``NoReturn`` is deprecated, please use ``Never`` instead.
Comment thread
srittau marked this conversation as resolved.
Outdated

.. data:: Self

Special type to represent the current enclosed class.
Expand All @@ -1005,11 +994,7 @@ using ``[]``.
This annotation is semantically equivalent to the following,
albeit in a more succinct fashion::

from typing import TypeVar

Self = TypeVar("Self", bound="Foo")

class Foo:
class Foo[Self: Foo]:
def return_self(self: Self) -> Self:
...
return self
Expand Down Expand Up @@ -1057,17 +1042,15 @@ using ``[]``.

.. testcode::

from typing import Generic, TypeAlias, TypeVar

T = TypeVar("T")
from typing import TypeAlias

# "Box" does not exist yet,
# so we have to use quotes for the forward reference on Python <3.12.
# so we have to use quotes for the forward reference on Python <3.14.
# Using ``TypeAlias`` tells the type checker that this is a type alias declaration,
# not a variable assignment to a string.
BoxOfStrings: TypeAlias = "Box[str]"

class Box(Generic[T]):
class Box[T]:
@classmethod
def make_box_of_strings(cls) -> BoxOfStrings: ...

Expand Down Expand Up @@ -1140,6 +1123,10 @@ These can be used as types in annotations. They all support subscription using
Python, use
``get_origin(obj) is typing.Union or get_origin(obj) is types.UnionType``.

.. deprecated:: 3.16
Creating unions using ``Union[X, Y]`` is deprecated. Use ``X | Y``
instead.

.. data:: Optional

``Optional[X]`` is equivalent to ``X | None`` (or ``Union[X, None]``).
Expand All @@ -1160,9 +1147,13 @@ These can be used as types in annotations. They all support subscription using
...

.. versionchanged:: 3.10
Optional can now be written as ``X | None``. See
``Optional[X]`` can now be written as ``X | None``. See
:ref:`union type expressions<types-union>`.

.. deprecated:: 3.16
``Optional`` is deprecated. Instead, use ``X | None`` to create optional
unions and :class:`Union` to refer to the union type.

.. data:: Concatenate

Special form for annotating higher-order functions.
Expand Down Expand Up @@ -1775,6 +1766,8 @@ without the dedicated syntax, as documented below.
``Generic``. In this case, the type parameters must be declared
separately::

from typing import Generic, TypeVar

KT = TypeVar('KT')
VT = TypeVar('VT')

Expand All @@ -1783,6 +1776,10 @@ without the dedicated syntax, as documented below.
...
# Etc.

.. deprecated:: 3.16
Explicitly inheriting from ``Generic`` is deprecated. Use the dedicated
syntax for declaring type variables instead.

.. _typevar:

.. class:: TypeVar(name, *constraints, bound=None, covariant=False, contravariant=False, infer_variance=False, default=typing.NoDefault)
Expand Down Expand Up @@ -2166,8 +2163,7 @@ without the dedicated syntax, as documented below.

type IntFunc[**P] = Callable[P, int]

For compatibility with Python 3.11 and earlier, ``ParamSpec`` objects
can also be created as follows::
``ParamSpec`` objects can also be explicitly created as follows::

P = ParamSpec('P')

Expand Down Expand Up @@ -3507,7 +3503,7 @@ Introspection helpers
This is often the same as :func:`annotationlib.get_annotations`, but this
function makes the following changes to the annotations dictionary:

* Forward references encoded as string literals or :class:`ForwardRef`
* Forward references encoded as string literals or :class:`annotationlib.ForwardRef`
objects are handled by evaluating them in *globalns*, *localns*, and
(where applicable) *obj*'s :ref:`type parameter <type-params>` namespace.
If *globalns* or *localns* is not given, appropriate namespace
Expand Down Expand Up @@ -3554,7 +3550,7 @@ Introspection helpers
See the documentation on :data:`Annotated` for more information.

.. versionchanged:: 3.11
Previously, ``Optional[t]`` was added for function and method annotations
Previously, ``t | None`` was added for function and method annotations
if a default value equal to ``None`` was set.
Now the annotation is returned unchanged.

Expand Down Expand Up @@ -3709,6 +3705,9 @@ Introspection helpers
behaviors of this class have been changed; for example, after a ``ForwardRef`` has
been evaluated, the evaluated value is no longer cached.

.. deprecated:: 3.16
Use :class:`annotationlib.ForwardRef` instead.

.. function:: evaluate_forward_ref(forward_ref, *, owner=None, globals=None, locals=None, type_params=None, format=annotationlib.Format.VALUE)

Evaluate an :class:`annotationlib.ForwardRef` as a :term:`type hint`.
Expand Down Expand Up @@ -3881,7 +3880,7 @@ Aliases to built-in types
:class:`builtins.tuple <tuple>` now supports subscripting (``[]``).
See :pep:`585` and :ref:`types-genericalias`.

.. class:: Type(Generic[CT_co])
.. class:: Type[CT_co]
Comment thread
srittau marked this conversation as resolved.

Deprecated alias to :class:`type`.

Expand Down Expand Up @@ -4037,7 +4036,7 @@ Aliases to container ABCs in :mod:`collections.abc`
:class:`collections.abc.Collection` now supports subscripting (``[]``).
See :pep:`585` and :ref:`types-genericalias`.

.. class:: Container(Generic[T_co])
.. class:: Container[T_co]

Deprecated alias to :class:`collections.abc.Container`.

Expand All @@ -4061,7 +4060,7 @@ Aliases to container ABCs in :mod:`collections.abc`
:class:`collections.abc.KeysView` now supports subscripting (``[]``).
See :pep:`585` and :ref:`types-genericalias`.

.. class:: Mapping(Collection[KT], Generic[KT, VT_co])
.. class:: Mapping[KT, VT_co](Collection[KT])

Deprecated alias to :class:`collections.abc.Mapping`.

Expand All @@ -4077,7 +4076,7 @@ Aliases to container ABCs in :mod:`collections.abc`
:class:`collections.abc.MappingView` now supports subscripting (``[]``).
See :pep:`585` and :ref:`types-genericalias`.

.. class:: MutableMapping(Mapping[KT, VT])
.. class:: MutableMapping[KT, VT](Mapping[KT, VT])

Deprecated alias to :class:`collections.abc.MutableMapping`.

Expand All @@ -4086,7 +4085,7 @@ Aliases to container ABCs in :mod:`collections.abc`
now supports subscripting (``[]``).
See :pep:`585` and :ref:`types-genericalias`.

.. class:: MutableSequence(Sequence[T])
.. class:: MutableSequence[T](Sequence[T])

Deprecated alias to :class:`collections.abc.MutableSequence`.

Expand All @@ -4095,23 +4094,23 @@ Aliases to container ABCs in :mod:`collections.abc`
now supports subscripting (``[]``).
See :pep:`585` and :ref:`types-genericalias`.

.. class:: MutableSet(AbstractSet[T])
.. class:: MutableSet[T](AbstractSet[T])

Deprecated alias to :class:`collections.abc.MutableSet`.

.. deprecated:: 3.9
:class:`collections.abc.MutableSet` now supports subscripting (``[]``).
See :pep:`585` and :ref:`types-genericalias`.

.. class:: Sequence(Reversible[T_co], Collection[T_co])
.. class:: Sequence[T_co](Reversible[T_co], Collection[T_co])

Deprecated alias to :class:`collections.abc.Sequence`.

.. deprecated:: 3.9
:class:`collections.abc.Sequence` now supports subscripting (``[]``).
See :pep:`585` and :ref:`types-genericalias`.

.. class:: ValuesView(MappingView, Collection[_VT_co])
.. class:: ValuesView[VT_co](MappingView, Collection[VT_co])

Deprecated alias to :class:`collections.abc.ValuesView`.

Expand All @@ -4124,7 +4123,7 @@ Aliases to container ABCs in :mod:`collections.abc`
Aliases to asynchronous ABCs in :mod:`collections.abc`
""""""""""""""""""""""""""""""""""""""""""""""""""""""

.. class:: Coroutine(Awaitable[ReturnType], Generic[YieldType, SendType, ReturnType])
.. class:: Coroutine[YieldType, SendType, ReturnType](Awaitable[ReturnType])

Deprecated alias to :class:`collections.abc.Coroutine`.

Expand All @@ -4138,7 +4137,7 @@ Aliases to asynchronous ABCs in :mod:`collections.abc`
:class:`collections.abc.Coroutine` now supports subscripting (``[]``).
See :pep:`585` and :ref:`types-genericalias`.

.. class:: AsyncGenerator(AsyncIterator[YieldType], Generic[YieldType, SendType])
.. class:: AsyncGenerator[YieldType, SendType](AsyncIterator[YieldType])

Deprecated alias to :class:`collections.abc.AsyncGenerator`.

Expand All @@ -4156,7 +4155,7 @@ Aliases to asynchronous ABCs in :mod:`collections.abc`
.. versionchanged:: 3.13
The ``SendType`` parameter now has a default.

.. class:: AsyncIterable(Generic[T_co])
.. class:: AsyncIterable[T_co]

Deprecated alias to :class:`collections.abc.AsyncIterable`.

Expand All @@ -4166,7 +4165,7 @@ Aliases to asynchronous ABCs in :mod:`collections.abc`
:class:`collections.abc.AsyncIterable` now supports subscripting (``[]``).
See :pep:`585` and :ref:`types-genericalias`.

.. class:: AsyncIterator(AsyncIterable[T_co])
.. class:: AsyncIterator[T_co](AsyncIterable[T_co])

Deprecated alias to :class:`collections.abc.AsyncIterator`.

Expand All @@ -4176,7 +4175,7 @@ Aliases to asynchronous ABCs in :mod:`collections.abc`
:class:`collections.abc.AsyncIterator` now supports subscripting (``[]``).
See :pep:`585` and :ref:`types-genericalias`.

.. class:: Awaitable(Generic[T_co])
.. class:: Awaitable[T_co]

Deprecated alias to :class:`collections.abc.Awaitable`.

Expand All @@ -4191,15 +4190,15 @@ Aliases to asynchronous ABCs in :mod:`collections.abc`
Aliases to other ABCs in :mod:`collections.abc`
"""""""""""""""""""""""""""""""""""""""""""""""

.. class:: Iterable(Generic[T_co])
.. class:: Iterable[T_co]

Deprecated alias to :class:`collections.abc.Iterable`.

.. deprecated:: 3.9
:class:`collections.abc.Iterable` now supports subscripting (``[]``).
See :pep:`585` and :ref:`types-genericalias`.

.. class:: Iterator(Iterable[T_co])
.. class:: Iterator[T_co](Iterable[T_co])

Deprecated alias to :class:`collections.abc.Iterator`.

Expand All @@ -4222,7 +4221,7 @@ Aliases to other ABCs in :mod:`collections.abc`
``Callable`` now supports :class:`ParamSpec` and :data:`Concatenate`.
See :pep:`612` for more details.

.. class:: Generator(Iterator[YieldType], Generic[YieldType, SendType, ReturnType])
.. class:: Generator[YieldType, SendType, ReturnType](Iterator[YieldType])

Deprecated alias to :class:`collections.abc.Generator`.

Expand All @@ -4244,7 +4243,7 @@ Aliases to other ABCs in :mod:`collections.abc`
.. deprecated:: 3.12
Use :class:`collections.abc.Hashable` directly instead.

.. class:: Reversible(Iterable[T_co])
.. class:: Reversible[T_co](Iterable[T_co])

Deprecated alias to :class:`collections.abc.Reversible`.

Expand All @@ -4264,7 +4263,7 @@ Aliases to other ABCs in :mod:`collections.abc`
Aliases to :mod:`contextlib` ABCs
"""""""""""""""""""""""""""""""""

.. class:: ContextManager(Generic[T_co, ExitT_co])
.. class:: ContextManager[T_co, ExitT_co]

Deprecated alias to :class:`contextlib.AbstractContextManager`.

Expand All @@ -4283,7 +4282,7 @@ Aliases to :mod:`contextlib` ABCs
.. versionchanged:: 3.13
Added the optional second type parameter, ``ExitT_co``.

.. class:: AsyncContextManager(Generic[T_co, AExitT_co])
.. class:: AsyncContextManager[T_co, AExitT_co]

Deprecated alias to :class:`contextlib.AbstractAsyncContextManager`.

Expand Down
5 changes: 5 additions & 0 deletions Misc/NEWS.d/next/Documentation/2026-07-22-14-01-52.gh-issue-132941.XyPgse.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
Soft deprecate various typing-related classes: :class:`typing.Optional`,
:class:`typing.NoReturn`, :class:`typing.ForwardRef`,
:class:`types.UnionType`. Also deprecate creating :class:`typing.Union`
instances using the constructor and explicitly inheriting from
:class:`typing.Generic`.
Loading