From 9012c55af8877eedc0a35955b01281958703c6e2 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 14 Jun 2023 23:12:42 -0700 Subject: [PATCH] [3.12] More reorganisation of the typing docs (GH-105787) (#105810) More reorganisation of the typing docs (GH-105787) (cherry picked from commit da911a6b226ca47cc15088d800b575e19a731f1c) Co-authored-by: Alex Waygood --- Doc/library/typing.rst | 218 ++++++++++++++++++++++------------------- 1 file changed, 117 insertions(+), 101 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 67e4a27a291bc7..5c7ddc7e5a29b0 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -2420,6 +2420,18 @@ These protocols are decorated with :func:`runtime_checkable`. An ABC with one abstract method ``__round__`` that is covariant in its return type. +ABCs for working with IO +------------------------ + +.. class:: IO + TextIO + BinaryIO + + Generic type ``IO[AnyStr]`` and its subclasses ``TextIO(IO[str])`` + and ``BinaryIO(IO[bytes])`` + represent the types of I/O streams such as returned by + :func:`open`. + Functions and decorators ------------------------ @@ -3007,11 +3019,15 @@ Constant .. versionadded:: 3.5.2 -Generic concrete collections ----------------------------- +.. _generic-concrete-collections: -Corresponding to built-in types -""""""""""""""""""""""""""""""" +Deprecated aliases +------------------ + +.. _corresponding-to-built-in-types: + +Aliases to built-in types +""""""""""""""""""""""""" .. class:: Dict(dict, MutableMapping[KT, VT]) @@ -3073,8 +3089,10 @@ Corresponding to built-in types .. note:: :data:`Tuple` is a special form. -Corresponding to types in :mod:`collections` -"""""""""""""""""""""""""""""""""""""""""""" +.. _corresponding-to-types-in-collections: + +Aliases to types in :mod:`collections` +"""""""""""""""""""""""""""""""""""""" .. class:: DefaultDict(collections.defaultdict, MutableMapping[KT, VT]) @@ -3129,17 +3147,10 @@ Corresponding to types in :mod:`collections` :class:`collections.deque` now supports subscripting (``[]``). See :pep:`585` and :ref:`types-genericalias`. -Other concrete types -"""""""""""""""""""" +.. _other-concrete-types: -.. class:: IO - TextIO - BinaryIO - - Generic type ``IO[AnyStr]`` and its subclasses ``TextIO(IO[str])`` - and ``BinaryIO(IO[bytes])`` - represent the types of I/O streams such as returned by - :func:`open`. +Aliases to other concrete types +""""""""""""""""""""""""""""""" .. deprecated-removed:: 3.8 3.13 The ``typing.io`` namespace is deprecated and will be removed. @@ -3186,11 +3197,11 @@ Other concrete types currently planned, but users are encouraged to use :class:`str` instead of ``Text``. -Abstract Base Classes ---------------------- +.. _abstract-base-classes: +.. _corresponding-to-collections-in-collections-abc: -Corresponding to collections in :mod:`collections.abc` -"""""""""""""""""""""""""""""""""""""""""""""""""""""" +Aliases to container ABCs in :mod:`collections.abc` +""""""""""""""""""""""""""""""""""""""""""""""""""" .. class:: AbstractSet(Collection[T_co]) @@ -3305,86 +3316,10 @@ Corresponding to collections in :mod:`collections.abc` :class:`collections.abc.ValuesView` now supports subscripting (``[]``). See :pep:`585` and :ref:`types-genericalias`. -Corresponding to other types in :mod:`collections.abc` -"""""""""""""""""""""""""""""""""""""""""""""""""""""" - -.. class:: Iterable(Generic[T_co]) - - Deprecated alias to :class:`collections.abc.Iterable`. - - .. deprecated:: 3.9 - :class:`collections.abc.Iterable` now supports subscripting (``[]``). - See :pep:`585` and :ref:`types-genericalias`. - -.. class:: Iterator(Iterable[T_co]) - - 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[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:: - - def echo_round() -> Generator[int, float, str]: - sent = yield 0 - while sent >= 0: - sent = yield round(sent) - return 'Done' - - Note that unlike many other generics in the typing module, the ``SendType`` - of :class:`Generator` behaves contravariantly, not covariantly or - invariantly. - - If your generator will only yield values, set the ``SendType`` and - ``ReturnType`` to ``None``:: - - def infinite_stream(start: int) -> Generator[int, None, None]: - while True: - yield start - start += 1 - - Alternatively, annotate your generator as having a return type of - either ``Iterable[YieldType]`` or ``Iterator[YieldType]``:: - - def infinite_stream(start: int) -> Iterator[int]: - while True: - yield start - start += 1 - - .. deprecated:: 3.9 - :class:`collections.abc.Generator` now supports subscripting (``[]``). - See :pep:`585` and :ref:`types-genericalias`. - -.. class:: Hashable - - Deprecated alias to :class:`collections.abc.Hashable`. - - .. deprecated:: 3.12 - Use :class:`collections.abc.Hashable` directly instead. - -.. class:: Reversible(Iterable[T_co]) - - Deprecated alias to :class:`collections.abc.Reversible`. +.. _asynchronous-programming: - .. deprecated:: 3.9 - :class:`collections.abc.Reversible` now supports subscripting (``[]``). - See :pep:`585` and :ref:`types-genericalias`. - -.. class:: Sized - - Deprecated alias to :class:`collections.abc.Sized`. - - .. deprecated:: 3.12 - Use :class:`collections.abc.Sized` directly instead. - -Asynchronous programming -"""""""""""""""""""""""" +Aliases to asynchronous ABCs in :mod:`collections.abc` +"""""""""""""""""""""""""""""""""""""""""""""""""""""" .. class:: Coroutine(Awaitable[ReturnType], Generic[YieldType, SendType, ReturnType]) @@ -3475,9 +3410,90 @@ Asynchronous programming :class:`collections.abc.Awaitable` now supports subscripting (``[]``). See :pep:`585` and :ref:`types-genericalias`. +.. _corresponding-to-other-types-in-collections-abc: + +Aliases to other ABCs in :mod:`collections.abc` +""""""""""""""""""""""""""""""""""""""""""""""" + +.. class:: Iterable(Generic[T_co]) + + Deprecated alias to :class:`collections.abc.Iterable`. + + .. deprecated:: 3.9 + :class:`collections.abc.Iterable` now supports subscripting (``[]``). + See :pep:`585` and :ref:`types-genericalias`. + +.. class:: Iterator(Iterable[T_co]) + + 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[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:: + + def echo_round() -> Generator[int, float, str]: + sent = yield 0 + while sent >= 0: + sent = yield round(sent) + return 'Done' + + Note that unlike many other generics in the typing module, the ``SendType`` + of :class:`Generator` behaves contravariantly, not covariantly or + invariantly. + + If your generator will only yield values, set the ``SendType`` and + ``ReturnType`` to ``None``:: + + def infinite_stream(start: int) -> Generator[int, None, None]: + while True: + yield start + start += 1 + + Alternatively, annotate your generator as having a return type of + either ``Iterable[YieldType]`` or ``Iterator[YieldType]``:: + + def infinite_stream(start: int) -> Iterator[int]: + while True: + yield start + start += 1 + + .. deprecated:: 3.9 + :class:`collections.abc.Generator` now supports subscripting (``[]``). + See :pep:`585` and :ref:`types-genericalias`. + +.. class:: Hashable + + Deprecated alias to :class:`collections.abc.Hashable`. + + .. deprecated:: 3.12 + Use :class:`collections.abc.Hashable` directly instead. + +.. class:: Reversible(Iterable[T_co]) + + Deprecated alias to :class:`collections.abc.Reversible`. + + .. deprecated:: 3.9 + :class:`collections.abc.Reversible` now supports subscripting (``[]``). + See :pep:`585` and :ref:`types-genericalias`. + +.. class:: Sized + + Deprecated alias to :class:`collections.abc.Sized`. + + .. deprecated:: 3.12 + Use :class:`collections.abc.Sized` directly instead. + +.. _context-manager-types: -Context manager types -""""""""""""""""""""" +Aliases to :mod:`contextlib` ABCs +""""""""""""""""""""""""""""""""" .. class:: ContextManager(Generic[T_co])