[Python-checkins] [3.12] typing: Improve documentation of generic classes and aliases (GH-105369) (#105453)
AlexWaygood
webhook-mailer at python.org
Wed Jun 7 11:04:28 EDT 2023
https://github.com/python/cpython/commit/9a7c4a5f39ec795f1ea77e1dfc557514f8f8a04a
commit: 9a7c4a5f39ec795f1ea77e1dfc557514f8f8a04a
branch: 3.12
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: AlexWaygood <Alex.Waygood at Gmail.com>
date: 2023-06-07T15:04:14Z
summary:
[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 at Gmail.com>
files:
M Doc/library/typing.rst
M Lib/typing.py
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 5f559cf3f493..3fa0651546ab 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 0983f20f9b27..0ff29fa43558 100644
--- a/Lib/typing.py
+++ b/Lib/typing.py
@@ -2549,11 +2549,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.
More information about the Python-checkins
mailing list