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

1 files changed, 82 insertions, 59 deletions

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index ba0a8d1..973445a 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -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