mirror of https://github.com/python/cpython
typing: Improve documentation of generic classes and aliases (#105369)
This commit is contained in:
Alex Waygood
GitHub
parent
76883af6bf
commit
d63a7c3694
|
|
@ -311,21 +311,28 @@ Generics
|
|||
========
|
||||
|
||||
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::
|
||||
|
|
@ -333,10 +340,10 @@ 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.
|
||||
|
|
@ -515,7 +522,7 @@ to the former, so the following are equivalent::
|
|||
>>> 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.
|
||||
|
||||
|
|
@ -654,14 +661,14 @@ The module defines the following classes, functions and decorators.
|
|||
|
||||
.. 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.
|
||||
|
||||
|
|
@ -881,7 +888,9 @@ These can be used as types in annotations using ``[]``, each having a unique syn
|
|||
|
||||
.. 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[()]``.
|
||||
|
||||
|
|
@ -890,8 +899,8 @@ These can be used as types in annotations using ``[]``, each having a unique syn
|
|||
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 (``[]``).
|
||||
|
|
@ -959,12 +968,15 @@ These can be used as types in annotations using ``[]``, each having a unique syn
|
|||
|
||||
.. 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.
|
||||
|
|
@ -1050,8 +1062,10 @@ These can be used as types in annotations using ``[]``, each having a unique syn
|
|||
|
||||
.. 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::
|
||||
|
||||
|
|
@ -2313,9 +2327,11 @@ Corresponding to built-in types
|
|||
|
||||
.. 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::
|
||||
|
||||
|
|
@ -2328,10 +2344,11 @@ Corresponding to built-in types
|
|||
|
||||
.. 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::
|
||||
|
||||
|
|
@ -2347,9 +2364,11 @@ Corresponding to built-in types
|
|||
|
||||
.. 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 (``[]``).
|
||||
|
|
@ -2357,7 +2376,7 @@ Corresponding to built-in types
|
|||
|
||||
.. 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>`
|
||||
|
|
@ -2371,7 +2390,7 @@ Corresponding to types in :mod:`collections`
|
|||
|
||||
.. class:: DefaultDict(collections.defaultdict, MutableMapping[KT, VT])
|
||||
|
||||
A generic version of :class:`collections.defaultdict`.
|
||||
Deprecated alias to :class:`collections.defaultdict`.
|
||||
|
||||
.. versionadded:: 3.5.2
|
||||
|
||||
|
|
@ -2381,7 +2400,7 @@ Corresponding to types in :mod:`collections`
|
|||
|
||||
.. class:: OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])
|
||||
|
||||
A generic version of :class:`collections.OrderedDict`.
|
||||
Deprecated alias to :class:`collections.OrderedDict`.
|
||||
|
||||
.. versionadded:: 3.7.2
|
||||
|
||||
|
|
@ -2391,7 +2410,7 @@ Corresponding to types in :mod:`collections`
|
|||
|
||||
.. 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
|
||||
|
|
@ -2402,7 +2421,7 @@ Corresponding to types in :mod:`collections`
|
|||
|
||||
.. 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
|
||||
|
|
@ -2413,7 +2432,7 @@ Corresponding to types in :mod:`collections`
|
|||
|
||||
.. 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
|
||||
|
|
@ -2476,7 +2495,7 @@ Corresponding to collections in :mod:`collections.abc`
|
|||
|
||||
.. 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 (``[]``).
|
||||
|
|
@ -2492,7 +2511,7 @@ Corresponding to collections in :mod:`collections.abc`
|
|||
|
||||
.. 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
|
||||
|
||||
|
|
@ -2502,7 +2521,7 @@ Corresponding to collections in :mod:`collections.abc`
|
|||
|
||||
.. 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 (``[]``).
|
||||
|
|
@ -2510,7 +2529,7 @@ Corresponding to collections in :mod:`collections.abc`
|
|||
|
||||
.. 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 (``[]``).
|
||||
|
|
@ -2518,7 +2537,7 @@ Corresponding to collections in :mod:`collections.abc`
|
|||
|
||||
.. 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 (``[]``).
|
||||
|
|
@ -2526,7 +2545,7 @@ Corresponding to collections in :mod:`collections.abc`
|
|||
|
||||
.. 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:
|
||||
|
|
@ -2538,7 +2557,7 @@ Corresponding to collections in :mod:`collections.abc`
|
|||
|
||||
.. 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 (``[]``).
|
||||
|
|
@ -2546,7 +2565,7 @@ Corresponding to collections in :mod:`collections.abc`
|
|||
|
||||
.. 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`
|
||||
|
|
@ -2555,7 +2574,7 @@ Corresponding to collections in :mod:`collections.abc`
|
|||
|
||||
.. 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`
|
||||
|
|
@ -2564,7 +2583,7 @@ Corresponding to collections in :mod:`collections.abc`
|
|||
|
||||
.. 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 (``[]``).
|
||||
|
|
@ -2572,7 +2591,7 @@ Corresponding to collections in :mod:`collections.abc`
|
|||
|
||||
.. 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 (``[]``).
|
||||
|
|
@ -2580,7 +2599,7 @@ Corresponding to collections in :mod:`collections.abc`
|
|||
|
||||
.. 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 (``[]``).
|
||||
|
|
@ -2591,7 +2610,7 @@ Corresponding to other types in :mod:`collections.abc`
|
|||
|
||||
.. 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 (``[]``).
|
||||
|
|
@ -2599,13 +2618,15 @@ Corresponding to other types in :mod:`collections.abc`
|
|||
|
||||
.. 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::
|
||||
|
|
@ -2642,14 +2663,14 @@ Corresponding to other types in :mod:`collections.abc`
|
|||
|
||||
.. 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 (``[]``).
|
||||
|
|
@ -2657,7 +2678,7 @@ Corresponding to other types in :mod:`collections.abc`
|
|||
|
||||
.. 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.
|
||||
|
|
@ -2665,9 +2686,10 @@ Corresponding to other types in :mod:`collections.abc`
|
|||
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::
|
||||
|
||||
|
|
@ -2683,7 +2705,9 @@ Asynchronous programming
|
|||
: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::
|
||||
|
|
@ -2723,7 +2747,7 @@ Asynchronous programming
|
|||
|
||||
.. class:: AsyncIterable(Generic[T_co])
|
||||
|
||||
A generic version of :class:`collections.abc.AsyncIterable`.
|
||||
Deprecated alias to :class:`collections.abc.AsyncIterable`.
|
||||
|
||||
.. versionadded:: 3.5.2
|
||||
|
||||
|
|
@ -2733,7 +2757,7 @@ Asynchronous programming
|
|||
|
||||
.. class:: AsyncIterator(AsyncIterable[T_co])
|
||||
|
||||
A generic version of :class:`collections.abc.AsyncIterator`.
|
||||
Deprecated alias to :class:`collections.abc.AsyncIterator`.
|
||||
|
||||
.. versionadded:: 3.5.2
|
||||
|
||||
|
|
@ -2743,7 +2767,7 @@ Asynchronous programming
|
|||
|
||||
.. class:: Awaitable(Generic[T_co])
|
||||
|
||||
A generic version of :class:`collections.abc.Awaitable`.
|
||||
Deprecated alias to :class:`collections.abc.Awaitable`.
|
||||
|
||||
.. versionadded:: 3.5.2
|
||||
|
||||
|
|
@ -2757,7 +2781,7 @@ Context manager types
|
|||
|
||||
.. 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
|
||||
|
|
@ -2769,7 +2793,7 @@ Context manager types
|
|||
|
||||
.. 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
|
||||
|
|
|
|||
|
|
@ -2543,11 +2543,13 @@ Callable = _CallableType(collections.abc.Callable, 2)
|
|||
Callable.__doc__ = \
|
||||
"""Deprecated alias to collections.abc.Callable.
|
||||
|
||||
Callable[[int], str] signifies a function of (int) -> str.
|
||||
Callable[[int], str] signifies a function that takes a single
|
||||
parameter of type int and returns a 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, a ParamSpec or ellipsis.
|
||||
The return type must be a single type.
|
||||
The argument list must be a list of types, a ParamSpec,
|
||||
Concatenate or 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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue