From d63a7c3694d5c4484fcaa01c33590b1d4bc2559e Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Wed, 7 Jun 2023 15:02:40 +0100 Subject: [PATCH] typing: Improve documentation of generic classes and aliases (#105369) --- Doc/library/typing.rst | 148 ++++++++++++++++++++++++----------------- Lib/typing.py | 8 ++- 2 files changed, 91 insertions(+), 65 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index ffc5c58db1c..f65eec74999 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -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 `:: +Generic functions and classes can be parameterized by using +:ref:`type parameter syntax `:: 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 ` 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 `. - 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 (``[]``). @@ -2357,7 +2376,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 ` @@ -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 diff --git a/Lib/typing.py b/Lib/typing.py index 307b26f30da..27497741b24 100644 --- a/Lib/typing.py +++ b/Lib/typing.py @@ -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.