[3.12] typing: Improve documentation of generic classes and aliases (GH-105369) (#105453)

typing: Improve documentation of generic classes and aliases (GH-105369)
(cherry picked from commit d63a7c3694d5c4484fcaa01c33590b1d4bc2559e)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

2 files changed, 91 insertions, 65 deletions

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 5f559cf..3fa0651 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 <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::
 
@@ -2321,9 +2335,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::
 
@@ -2336,10 +2352,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::
 
@@ -2355,9 +2372,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 (``[]``).
@@ -2365,7 +2384,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>`
@@ -2379,7 +2398,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
 
@@ -2389,7 +2408,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
 
@@ -2399,7 +2418,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
@@ -2410,7 +2429,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
@@ -2421,7 +2440,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
@@ -2492,7 +2511,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 (``[]``).
@@ -2508,7 +2527,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
 
@@ -2518,7 +2537,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 (``[]``).
@@ -2526,7 +2545,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 (``[]``).
@@ -2534,7 +2553,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 (``[]``).
@@ -2542,7 +2561,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:
@@ -2554,7 +2573,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 (``[]``).
@@ -2562,7 +2581,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`
@@ -2571,7 +2590,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`
@@ -2580,7 +2599,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 (``[]``).
@@ -2588,7 +2607,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 (``[]``).
@@ -2596,7 +2615,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 (``[]``).
@@ -2607,7 +2626,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 (``[]``).
@@ -2615,13 +2634,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::
@@ -2658,14 +2679,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 (``[]``).
@@ -2673,7 +2694,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.
@@ -2681,9 +2702,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::
 
@@ -2699,7 +2721,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::
@@ -2739,7 +2763,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
 
@@ -2749,7 +2773,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
 
@@ -2759,7 +2783,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
 
@@ -2773,7 +2797,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
@@ -2785,7 +2809,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 0983f20..0ff29fa 100644
--- a/Lib/typing.py
+++ b/Lib/typing.py
@@ -2549,11 +2549,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.