diff --git a/Doc/deprecations/soft-deprecations.rst b/Doc/deprecations/soft-deprecations.rst index a270052788ef2a..136fd1a1252318 100644 --- a/Doc/deprecations/soft-deprecations.rst +++ b/Doc/deprecations/soft-deprecations.rst @@ -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 `, + :ref:`generic classes `, and + :ref:`generic type aliases ` instead. diff --git a/Doc/library/types.rst b/Doc/library/types.rst index 38a77119769d72..05ec1f8bb26de0 100644 --- a/Doc/library/types.rst +++ b/Doc/library/types.rst @@ -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. + .. class:: TracebackType(tb_next, tb_frame, tb_lasti, tb_lineno) The type of traceback objects such as found in ``sys.exception().__traceback__``. diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index c909b8bad6d726..0d39015fb26f95 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -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 @@ -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 @@ -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') @@ -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 @@ -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. @@ -984,6 +970,9 @@ using ``[]``. Added :data:`Never`. + .. soft-deprecated:: 3.16 + ``NoReturn`` is deprecated, please use ``Never`` instead. + .. data:: Self Special type to represent the current enclosed class. @@ -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 @@ -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: ... @@ -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``. + .. soft-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]``). @@ -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`. + .. soft-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. @@ -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') @@ -1783,6 +1776,10 @@ without the dedicated syntax, as documented below. ... # Etc. + .. soft-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) @@ -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') @@ -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 ` namespace. If *globalns* or *localns* is not given, appropriate namespace @@ -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. @@ -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`. @@ -3824,7 +3823,7 @@ program they are checking targets a minimum Python version of 3.9 or newer. Aliases to built-in types """"""""""""""""""""""""" -.. class:: Dict(dict, MutableMapping[KT, VT]) +.. class:: Dict[KT, VT](dict, MutableMapping[KT, VT]) Deprecated alias to :class:`dict`. @@ -3836,7 +3835,7 @@ Aliases to built-in types :class:`builtins.dict ` now supports subscripting (``[]``). See :pep:`585` and :ref:`types-genericalias`. -.. class:: List(list, MutableSequence[T]) +.. class:: List[T](list, MutableSequence[T]) Deprecated alias to :class:`list`. @@ -3849,7 +3848,7 @@ Aliases to built-in types :class:`builtins.list ` now supports subscripting (``[]``). See :pep:`585` and :ref:`types-genericalias`. -.. class:: Set(set, MutableSet[T]) +.. class:: Set[T](set, MutableSet[T]) Deprecated alias to :class:`builtins.set `. @@ -3861,7 +3860,7 @@ Aliases to built-in types :class:`builtins.set ` now supports subscripting (``[]``). See :pep:`585` and :ref:`types-genericalias`. -.. class:: FrozenSet(frozenset, AbstractSet[T_co]) +.. class:: FrozenSet[T_co](frozenset, AbstractSet[T_co]) Deprecated alias to :class:`builtins.frozenset `. @@ -3881,7 +3880,7 @@ Aliases to built-in types :class:`builtins.tuple ` now supports subscripting (``[]``). See :pep:`585` and :ref:`types-genericalias`. -.. class:: Type(Generic[CT_co]) +.. class:: Type[CT_co] Deprecated alias to :class:`type`. @@ -3899,7 +3898,7 @@ Aliases to built-in types Aliases to types in :mod:`collections` """""""""""""""""""""""""""""""""""""" -.. class:: DefaultDict(collections.defaultdict, MutableMapping[KT, VT]) +.. class:: DefaultDict[KT, VT](collections.defaultdict, MutableMapping[KT, VT]) Deprecated alias to :class:`collections.defaultdict`. @@ -3909,7 +3908,7 @@ Aliases to types in :mod:`collections` :class:`collections.defaultdict` now supports subscripting (``[]``). See :pep:`585` and :ref:`types-genericalias`. -.. class:: OrderedDict(collections.OrderedDict, MutableMapping[KT, VT]) +.. class:: OrderedDict[KT, VT](collections.OrderedDict, MutableMapping[KT, VT]) Deprecated alias to :class:`collections.OrderedDict`. @@ -3919,7 +3918,7 @@ Aliases to types in :mod:`collections` :class:`collections.OrderedDict` now supports subscripting (``[]``). See :pep:`585` and :ref:`types-genericalias`. -.. class:: ChainMap(collections.ChainMap, MutableMapping[KT, VT]) +.. class:: ChainMap[KT, VT](collections.ChainMap, MutableMapping[KT, VT]) Deprecated alias to :class:`collections.ChainMap`. @@ -3929,7 +3928,7 @@ Aliases to types in :mod:`collections` :class:`collections.ChainMap` now supports subscripting (``[]``). See :pep:`585` and :ref:`types-genericalias`. -.. class:: Counter(collections.Counter, Dict[T, int]) +.. class:: Counter[T](collections.Counter, Dict[T, int]) Deprecated alias to :class:`collections.Counter`. @@ -3939,7 +3938,7 @@ Aliases to types in :mod:`collections` :class:`collections.Counter` now supports subscripting (``[]``). See :pep:`585` and :ref:`types-genericalias`. -.. class:: Deque(deque, MutableSequence[T]) +.. class:: Deque[T](deque, MutableSequence[T]) Deprecated alias to :class:`collections.deque`. @@ -3997,7 +3996,7 @@ Aliases to other concrete types Aliases to container ABCs in :mod:`collections.abc` """"""""""""""""""""""""""""""""""""""""""""""""""" -.. class:: AbstractSet(Collection[T_co]) +.. class:: AbstractSet[T_co](Collection[T_co]) Deprecated alias to :class:`collections.abc.Set`. @@ -4027,7 +4026,7 @@ Aliases to container ABCs in :mod:`collections.abc` .. deprecated-removed:: 3.9 3.17 -.. class:: Collection(Sized, Iterable[T_co], Container[T_co]) +.. class:: Collection[T_co](Sized, Iterable[T_co], Container[T_co]) Deprecated alias to :class:`collections.abc.Collection`. @@ -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`. @@ -4045,7 +4044,7 @@ Aliases to container ABCs in :mod:`collections.abc` :class:`collections.abc.Container` now supports subscripting (``[]``). See :pep:`585` and :ref:`types-genericalias`. -.. class:: ItemsView(MappingView, AbstractSet[tuple[KT_co, VT_co]]) +.. class:: ItemsView[KT_co, VT_co](MappingView, AbstractSet[tuple[KT_co, VT_co]]) Deprecated alias to :class:`collections.abc.ItemsView`. @@ -4053,7 +4052,7 @@ Aliases to container ABCs in :mod:`collections.abc` :class:`collections.abc.ItemsView` now supports subscripting (``[]``). See :pep:`585` and :ref:`types-genericalias`. -.. class:: KeysView(MappingView, AbstractSet[KT_co]) +.. class:: KeysView[KT_co](MappingView, AbstractSet[KT_co]) Deprecated alias to :class:`collections.abc.KeysView`. @@ -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`. @@ -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`. @@ -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`. @@ -4095,7 +4094,7 @@ 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`. @@ -4103,7 +4102,7 @@ Aliases to container ABCs in :mod:`collections.abc` :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`. @@ -4111,7 +4110,7 @@ Aliases to container ABCs in :mod:`collections.abc` :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`. @@ -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`. @@ -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`. @@ -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`. @@ -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`. @@ -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`. @@ -4191,7 +4190,7 @@ 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`. @@ -4199,7 +4198,7 @@ Aliases to other ABCs in :mod:`collections.abc` :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`. @@ -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`. @@ -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`. @@ -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`. @@ -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`. @@ -4340,3 +4339,23 @@ convenience. This is subject to change, and not all deprecations are listed. - 3.13 - 3.18 - :gh:`105578` + * - :class:`typing.Optional` + - 3.16 + - Undecided + - :gh:`132941` + * - :class:`typing.NoReturn` + - 3.16 + - Undecided + - :gh:`132941` + * - :class:`typing.ForwardRef` + - 3.16 + - Undecided + - :gh:`132941` + * - ``Union[X, Y]`` + - 3.16 + - Undecided + - :gh:`132941` + * - Inheriting from :class:`typing.Generic` + - 3.16 + - Undecided + - :gh:`132941` diff --git a/Misc/NEWS.d/next/Documentation/2026-07-22-14-01-52.gh-issue-132941.XyPgse.rst b/Misc/NEWS.d/next/Documentation/2026-07-22-14-01-52.gh-issue-132941.XyPgse.rst new file mode 100644 index 00000000000000..6410e0f2d00d40 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2026-07-22-14-01-52.gh-issue-132941.XyPgse.rst @@ -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`.