========
Since type information about objects kept in containers cannot be statically
-inferred in a generic way, abstract base classes have been extended to support
-subscription to denote expected types for container elements.
+inferred in a generic way, many container classes in the standard library support
+subscription to denote the expected types of container elements.
-::
+.. testcode::
from collections.abc import Mapping, Sequence
+ class Employee: ...
+
+ # Sequence[Employee] indicates that all elements in the sequence
+ # must be instances of "Employee".
+ # Mapping[str, str] indicates that all keys and all values in the mapping
+ # must be strings.
def notify_by_email(employees: Sequence[Employee],
overrides: Mapping[str, str]) -> None: ...
-Generics can be parameterized by using :ref:`type parameter syntax <type-params>`::
+Generic functions and classes can be parameterized by using
+:ref:`type parameter syntax <type-params>`::
from collections.abc import Sequence
- def first[T](l: Sequence[T]) -> T: # Generic function
+ def first[T](l: Sequence[T]) -> T: # Function is generic over the TypeVar "T"
return l[0]
Or by using the :class:`TypeVar` factory directly::
from collections.abc import Sequence
from typing import TypeVar
- U = TypeVar('U') # Declare type variable
+ U = TypeVar('U') # Declare type variable "U"
- def first(l: Sequence[U]) -> U: # Generic function
- return l[0]
+ def second(l: Sequence[U]) -> U: # Function is generic over the TypeVar "U"
+ return l[1]
.. versionchanged:: 3.12
Syntactic support for generics is new in Python 3.12.
>>> X[[int, str]]
__main__.X[[int, str]]
-Do note that generics with :class:`ParamSpec` may not have correct
+Note that generics with :class:`ParamSpec` may not have correct
``__parameters__`` after substitution in some cases because they
are intended primarily for static type checking.
.. note::
- This module defines several types that are subclasses of pre-existing
- standard library classes which also extend :class:`Generic`
- to support type variables inside ``[]``.
- These types became redundant in Python 3.9 when the
+ 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 ``[]``.
The redundant types are deprecated as of Python 3.9 but no
- deprecation warnings will be issued by the interpreter.
+ 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.
.. data:: Tuple
- Tuple type; ``Tuple[X, Y]`` is the type of a tuple of two items
+ Deprecated alias for :class:`tuple`.
+
+ ``Tuple[X, Y]`` is the type of a tuple of two items
with the first item of type X and the second of type Y. The type of
the empty tuple can be written as ``Tuple[()]``.
of an int, a float and a string.
To specify a variable-length tuple of homogeneous type,
- use literal ellipsis, e.g. ``Tuple[int, ...]``. A plain :data:`Tuple`
- is equivalent to ``Tuple[Any, ...]``, and in turn to :class:`tuple`.
+ use literal ellipsis, e.g. ``Tuple[int, ...]``. A plain ``Tuple`` annotation
+ is equivalent to ``tuple``, ``Tuple[Any, ...]``, or ``tuple[Any, ...]``.
.. deprecated:: 3.9
:class:`builtins.tuple <tuple>` now supports subscripting (``[]``).
.. data:: Callable
- Callable type; ``Callable[[int], str]`` is a function of (int) -> str.
+ Deprecated alias to :class:`collections.abc.Callable`.
+
+ ``Callable[[int], str]`` signifies a function that takes a single parameter
+ of type :class:`int` and returns a :class:`str`.
The subscription syntax must always be used with exactly two
values: the argument list and the return type. The argument list
- must be a list of types or an ellipsis; the return type must be
- a single type.
+ must be a list of types, a :class:`ParamSpec`, :data:`Concatenate`,
+ or an ellipsis. The return type must be a single type.
There is no syntax to indicate optional or keyword arguments;
such function types are rarely used as callback types.
.. class:: Type(Generic[CT_co])
+ Deprecated alias to :class:`type`.
+
A variable annotated with ``C`` may accept a value of type ``C``. In
- contrast, a variable annotated with ``Type[C]`` may accept values that are
+ contrast, a variable annotated with ``type[C]`` or ``Type[C]`` may accept values that are
classes themselves -- specifically, it will accept the *class object* of
``C``. For example::
.. class:: Dict(dict, MutableMapping[KT, VT])
- A generic version of :class:`dict`.
- Useful for annotating return types. To annotate arguments it is preferred
- to use an abstract collection type such as :class:`Mapping`.
+ Deprecated alias to :class:`dict`.
+
+ Note that to annotate arguments, it is preferred
+ to use an abstract collection type such as :class:`Mapping`
+ rather than to use :class:`dict` or :class:`!typing.Dict`.
This type can be used as follows::
.. class:: List(list, MutableSequence[T])
- Generic version of :class:`list`.
- Useful for annotating return types. To annotate arguments it is preferred
+ Deprecated alias to :class:`list`.
+
+ Note that to annotate arguments, it is preferred
to use an abstract collection type such as :class:`Sequence` or
- :class:`Iterable`.
+ :class:`Iterable` rather than to use :class:`list` or :class:`!typing.List`.
This type may be used as follows::
.. class:: Set(set, MutableSet[T])
- A generic version of :class:`builtins.set <set>`.
- Useful for annotating return types. To annotate arguments it is preferred
- to use an abstract collection type such as :class:`AbstractSet`.
+ Deprecated alias to :class:`builtins.set <set>`.
+
+ Note that to annotate arguments, it is preferred
+ to use an abstract collection type such as :class:`AbstractSet`
+ rather than to use :class:`set` or :class:`!typing.Set`.
.. deprecated:: 3.9
:class:`builtins.set <set>` now supports subscripting (``[]``).
.. class:: FrozenSet(frozenset, AbstractSet[T_co])
- A generic version of :class:`builtins.frozenset <frozenset>`.
+ Deprecated alias to :class:`builtins.frozenset <frozenset>`.
.. deprecated:: 3.9
:class:`builtins.frozenset <frozenset>`
.. class:: DefaultDict(collections.defaultdict, MutableMapping[KT, VT])
- A generic version of :class:`collections.defaultdict`.
+ Deprecated alias to :class:`collections.defaultdict`.
.. versionadded:: 3.5.2
.. class:: OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])
- A generic version of :class:`collections.OrderedDict`.
+ Deprecated alias to :class:`collections.OrderedDict`.
.. versionadded:: 3.7.2
.. class:: ChainMap(collections.ChainMap, MutableMapping[KT, VT])
- A generic version of :class:`collections.ChainMap`.
+ Deprecated alias to :class:`collections.ChainMap`.
.. versionadded:: 3.5.4
.. versionadded:: 3.6.1
.. class:: Counter(collections.Counter, Dict[T, int])
- A generic version of :class:`collections.Counter`.
+ Deprecated alias to :class:`collections.Counter`.
.. versionadded:: 3.5.4
.. versionadded:: 3.6.1
.. class:: Deque(deque, MutableSequence[T])
- A generic version of :class:`collections.deque`.
+ Deprecated alias to :class:`collections.deque`.
.. versionadded:: 3.5.4
.. versionadded:: 3.6.1
.. class:: AbstractSet(Collection[T_co])
- A generic version of :class:`collections.abc.Set`.
+ Deprecated alias to :class:`collections.abc.Set`.
.. deprecated:: 3.9
:class:`collections.abc.Set` now supports subscripting (``[]``).
.. class:: Collection(Sized, Iterable[T_co], Container[T_co])
- A generic version of :class:`collections.abc.Collection`
+ Deprecated alias to :class:`collections.abc.Collection`.
.. versionadded:: 3.6.0
.. class:: Container(Generic[T_co])
- A generic version of :class:`collections.abc.Container`.
+ Deprecated alias to :class:`collections.abc.Container`.
.. deprecated:: 3.9
:class:`collections.abc.Container` now supports subscripting (``[]``).
.. class:: ItemsView(MappingView, AbstractSet[tuple[KT_co, VT_co]])
- A generic version of :class:`collections.abc.ItemsView`.
+ Deprecated alias to :class:`collections.abc.ItemsView`.
.. deprecated:: 3.9
:class:`collections.abc.ItemsView` now supports subscripting (``[]``).
.. class:: KeysView(MappingView, AbstractSet[KT_co])
- A generic version of :class:`collections.abc.KeysView`.
+ Deprecated alias to :class:`collections.abc.KeysView`.
.. deprecated:: 3.9
:class:`collections.abc.KeysView` now supports subscripting (``[]``).
.. class:: Mapping(Collection[KT], Generic[KT, VT_co])
- A generic version of :class:`collections.abc.Mapping`.
+ Deprecated alias to :class:`collections.abc.Mapping`.
This type can be used as follows::
def get_position_in_index(word_list: Mapping[str, int], word: str) -> int:
.. class:: MappingView(Sized)
- A generic version of :class:`collections.abc.MappingView`.
+ Deprecated alias to :class:`collections.abc.MappingView`.
.. deprecated:: 3.9
:class:`collections.abc.MappingView` now supports subscripting (``[]``).
.. class:: MutableMapping(Mapping[KT, VT])
- A generic version of :class:`collections.abc.MutableMapping`.
+ Deprecated alias to :class:`collections.abc.MutableMapping`.
.. deprecated:: 3.9
:class:`collections.abc.MutableMapping`
.. class:: MutableSequence(Sequence[T])
- A generic version of :class:`collections.abc.MutableSequence`.
+ Deprecated alias to :class:`collections.abc.MutableSequence`.
.. deprecated:: 3.9
:class:`collections.abc.MutableSequence`
.. class:: MutableSet(AbstractSet[T])
- A generic version of :class:`collections.abc.MutableSet`.
+ Deprecated alias to :class:`collections.abc.MutableSet`.
.. deprecated:: 3.9
:class:`collections.abc.MutableSet` now supports subscripting (``[]``).
.. class:: Sequence(Reversible[T_co], Collection[T_co])
- A generic version of :class:`collections.abc.Sequence`.
+ Deprecated alias to :class:`collections.abc.Sequence`.
.. deprecated:: 3.9
:class:`collections.abc.Sequence` now supports subscripting (``[]``).
.. class:: ValuesView(MappingView, Collection[_VT_co])
- A generic version of :class:`collections.abc.ValuesView`.
+ Deprecated alias to :class:`collections.abc.ValuesView`.
.. deprecated:: 3.9
:class:`collections.abc.ValuesView` now supports subscripting (``[]``).
.. class:: Iterable(Generic[T_co])
- A generic version of :class:`collections.abc.Iterable`.
+ Deprecated alias to :class:`collections.abc.Iterable`.
.. deprecated:: 3.9
:class:`collections.abc.Iterable` now supports subscripting (``[]``).
.. class:: Iterator(Iterable[T_co])
- A generic version of :class:`collections.abc.Iterator`.
+ Deprecated alias to :class:`collections.abc.Iterator`.
.. deprecated:: 3.9
:class:`collections.abc.Iterator` now supports subscripting (``[]``).
See :pep:`585` and :ref:`types-genericalias`.
-.. class:: Generator(Iterator[T_co], Generic[T_co, T_contra, V_co])
+.. class:: Generator(Iterator[YieldType], Generic[YieldType, SendType, ReturnType])
+
+ Deprecated alias to :class:`collections.abc.Generator`.
A generator can be annotated by the generic type
``Generator[YieldType, SendType, ReturnType]``. For example::
.. class:: Hashable
- An alias to :class:`collections.abc.Hashable`.
+ Deprecated alias to :class:`collections.abc.Hashable`.
.. deprecated:: 3.12
Use :class:`collections.abc.Hashable` directly instead.
.. class:: Reversible(Iterable[T_co])
- A generic version of :class:`collections.abc.Reversible`.
+ Deprecated alias to :class:`collections.abc.Reversible`.
.. deprecated:: 3.9
:class:`collections.abc.Reversible` now supports subscripting (``[]``).
.. class:: Sized
- An alias to :class:`collections.abc.Sized`.
+ Deprecated alias to :class:`collections.abc.Sized`.
.. deprecated:: 3.12
Use :class:`collections.abc.Sized` directly instead.
Asynchronous programming
""""""""""""""""""""""""
-.. class:: Coroutine(Awaitable[V_co], Generic[T_co, T_contra, V_co])
+.. class:: Coroutine(Awaitable[ReturnType], Generic[YieldType, SendType, ReturnType])
+
+ Deprecated alias to :class:`collections.abc.Coroutine`.
- A generic version of :class:`collections.abc.Coroutine`.
The variance and order of type variables
correspond to those of :class:`Generator`, for example::
:class:`collections.abc.Coroutine` now supports subscripting (``[]``).
See :pep:`585` and :ref:`types-genericalias`.
-.. class:: AsyncGenerator(AsyncIterator[T_co], Generic[T_co, T_contra])
+.. class:: AsyncGenerator(AsyncIterator[YieldType], Generic[YieldType, SendType])
+
+ Deprecated alias to :class:`collections.abc.AsyncGenerator`.
An async generator can be annotated by the generic type
``AsyncGenerator[YieldType, SendType]``. For example::
.. class:: AsyncIterable(Generic[T_co])
- A generic version of :class:`collections.abc.AsyncIterable`.
+ Deprecated alias to :class:`collections.abc.AsyncIterable`.
.. versionadded:: 3.5.2
.. class:: AsyncIterator(AsyncIterable[T_co])
- A generic version of :class:`collections.abc.AsyncIterator`.
+ Deprecated alias to :class:`collections.abc.AsyncIterator`.
.. versionadded:: 3.5.2
.. class:: Awaitable(Generic[T_co])
- A generic version of :class:`collections.abc.Awaitable`.
+ Deprecated alias to :class:`collections.abc.Awaitable`.
.. versionadded:: 3.5.2
.. class:: ContextManager(Generic[T_co])
- A generic version of :class:`contextlib.AbstractContextManager`.
+ Deprecated alias to :class:`contextlib.AbstractContextManager`.
.. versionadded:: 3.5.4
.. versionadded:: 3.6.0
.. class:: AsyncContextManager(Generic[T_co])
- A generic version of :class:`contextlib.AbstractAsyncContextManager`.
+ Deprecated alias to :class:`contextlib.AbstractAsyncContextManager`.
.. versionadded:: 3.5.4
.. versionadded:: 3.6.2
projects / thirdparty / Python / cpython.git / commitdiff
