From 32b068314dbc5cde85445a292cf7ebbaab14cfda Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Wed, 7 Jun 2023 15:02:40 +0100 Subject: [PATCH] [3.11] typing: Improve documentation of generic classes and aliases (#105369) --- Doc/library/typing.rst | 141 ++++++++++++++++++++++++----------------- Lib/typing.py | 8 ++- 2 files changed, 87 insertions(+), 62 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index ca2a2173df6958..05b2180c2d1962 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -296,13 +296,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: ... @@ -314,9 +320,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: @@ -467,7 +473,7 @@ to the former, so the following are equivalent:: >>> X[[int, str]] __main__.X[(, )] -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. @@ -606,14 +612,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. @@ -802,7 +808,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[()]``. @@ -811,8 +819,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 ` now supports subscripting (``[]``). @@ -880,12 +888,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. @@ -971,8 +982,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:: @@ -2007,9 +2020,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:: @@ -2022,10 +2037,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:: @@ -2043,9 +2059,11 @@ Corresponding to built-in types .. class:: Set(set, MutableSet[T]) - A generic version of :class:`builtins.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 `. + + 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 ` now supports subscripting (``[]``). @@ -2053,7 +2071,7 @@ Corresponding to built-in types .. class:: FrozenSet(frozenset, AbstractSet[T_co]) - A generic version of :class:`builtins.frozenset `. + Deprecated alias to :class:`builtins.frozenset `. .. deprecated:: 3.9 :class:`builtins.frozenset ` @@ -2067,7 +2085,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 @@ -2077,7 +2095,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 @@ -2087,7 +2105,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 @@ -2098,7 +2116,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 @@ -2109,7 +2127,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 @@ -2180,7 +2198,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 (``[]``). @@ -2196,7 +2214,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 @@ -2206,7 +2224,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 (``[]``). @@ -2214,7 +2232,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 (``[]``). @@ -2222,7 +2240,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 (``[]``). @@ -2230,7 +2248,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: @@ -2242,7 +2260,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 (``[]``). @@ -2250,7 +2268,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` @@ -2259,7 +2277,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` @@ -2268,7 +2286,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 (``[]``). @@ -2276,7 +2294,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 (``[]``). @@ -2284,7 +2302,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 (``[]``). @@ -2295,7 +2313,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 (``[]``). @@ -2303,13 +2321,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:: @@ -2346,11 +2366,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 (``[]``). @@ -2358,14 +2378,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:: @@ -2381,7 +2402,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:: @@ -2421,7 +2444,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 @@ -2431,7 +2454,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 @@ -2441,7 +2464,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 @@ -2455,7 +2478,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 @@ -2467,7 +2490,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 diff --git a/Lib/typing.py b/Lib/typing.py index e6ef344ef43a2b..3b2ab9a0614528 100644 --- a/Lib/typing.py +++ b/Lib/typing.py @@ -2685,11 +2685,13 @@ class Other(Leaf): # Error reported by type checker 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.