mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-07-24 11:44:31 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

[3.11] typing: Improve documentation of generic classes and aliases (#105369) (#105454)

Browse source
This commit is contained in:
Alex Waygood 2023-06-07 22:27:15 +01:00 • committed by GitHub
parent 571ec56b65
commit ccc971714e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 87 additions and 62 deletions
Download patch file Download diff file Expand all files Collapse all files

141
Doc/library/typing.rst
View file

@ -297,13 +297,19 @@ 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: ...
@ -315,9 +321,9 @@ called :class:`TypeVar`.
from collections.abc import Sequence
from typing import TypeVar
T = TypeVar('T') # Declare type variable
T = TypeVar('T') # Declare type variable "T"
def first(l: Sequence[T]) -> T: # Generic function
def first(l: Sequence[T]) -> T: # Function is generic over the TypeVar "T"
return l[0]
.. _user-defined-generics:
@ -468,7 +474,7 @@ to the former, so the following are equivalent::
>>> X[[int, str]]
__main__.X[(<class 'int'>, <class '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.
@ -607,14 +613,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.
@ -824,7 +830,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[()]``.
@ -833,8 +841,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 (``[]``).
@ -902,12 +910,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.
@ -993,8 +1004,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::
@ -2062,9 +2075,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::
@ -2077,10 +2092,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::
@ -2098,9 +2114,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 (``[]``).
@ -2108,7 +2126,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>`
@ -2122,7 +2140,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
@ -2132,7 +2150,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
@ -2142,7 +2160,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
@ -2153,7 +2171,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
@ -2164,7 +2182,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
@ -2235,7 +2253,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 (``[]``).
@ -2251,7 +2269,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
@ -2261,7 +2279,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 (``[]``).
@ -2269,7 +2287,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 (``[]``).
@ -2277,7 +2295,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 (``[]``).
@ -2285,7 +2303,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:
@ -2297,7 +2315,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 (``[]``).
@ -2305,7 +2323,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`
@ -2314,7 +2332,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`
@ -2323,7 +2341,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 (``[]``).
@ -2331,7 +2349,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 (``[]``).
@ -2339,7 +2357,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 (``[]``).
@ -2350,7 +2368,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 (``[]``).
@ -2358,13 +2376,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::
@ -2401,11 +2421,11 @@ Corresponding to other types in :mod:`collections.abc`
.. class:: Hashable
An alias to :class:`collections.abc.Hashable`.
Deprecated alias to :class:`collections.abc.Hashable`.
.. 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 (``[]``).
@ -2413,14 +2433,15 @@ Corresponding to other types in :mod:`collections.abc`
.. class:: Sized
An alias to :class:`collections.abc.Sized`.
Deprecated alias to :class:`collections.abc.Sized`.
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::
@ -2436,7 +2457,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::
@ -2476,7 +2499,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
@ -2486,7 +2509,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
@ -2496,7 +2519,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
@ -2510,7 +2533,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
@ -2522,7 +2545,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