Skip to content

Commit 67644e9

Browse files
committed
[3.11] More reorganisation of the typing docs (python#105787)
1 parent e422f35 commit 67644e9

File tree

1 file changed

+111
-99
lines changed

1 file changed

+111
-99
lines changed

Doc/library/typing.rst

+111-99
Original file line numberDiff line numberDiff line change
@@ -2159,6 +2159,18 @@ These protocols are decorated with :func:`runtime_checkable`.
21592159
An ABC with one abstract method ``__round__``
21602160
that is covariant in its return type.
21612161

2162+
ABCs for working with IO
2163+
------------------------
2164+
2165+
.. class:: IO
2166+
TextIO
2167+
BinaryIO
2168+
2169+
Generic type ``IO[AnyStr]`` and its subclasses ``TextIO(IO[str])``
2170+
and ``BinaryIO(IO[bytes])``
2171+
represent the types of I/O streams such as returned by
2172+
:func:`open`.
2173+
21622174
Functions and decorators
21632175
------------------------
21642176

@@ -2670,11 +2682,15 @@ Constant
26702682

26712683
.. versionadded:: 3.5.2
26722684

2673-
Generic concrete collections
2674-
----------------------------
2685+
.. _generic-concrete-collections:
26752686

2676-
Corresponding to built-in types
2677-
"""""""""""""""""""""""""""""""
2687+
Deprecated aliases
2688+
------------------
2689+
2690+
.. _corresponding-to-built-in-types:
2691+
2692+
Aliases to built-in types
2693+
"""""""""""""""""""""""""
26782694

26792695
.. class:: Dict(dict, MutableMapping[KT, VT])
26802696

@@ -2738,8 +2754,10 @@ Corresponding to built-in types
27382754

27392755
.. note:: :data:`Tuple` is a special form.
27402756

2741-
Corresponding to types in :mod:`collections`
2742-
""""""""""""""""""""""""""""""""""""""""""""
2757+
.. _corresponding-to-types-in-collections:
2758+
2759+
Aliases to types in :mod:`collections`
2760+
""""""""""""""""""""""""""""""""""""""
27432761

27442762
.. class:: DefaultDict(collections.defaultdict, MutableMapping[KT, VT])
27452763

@@ -2794,21 +2812,10 @@ Corresponding to types in :mod:`collections`
27942812
:class:`collections.deque` now supports subscripting (``[]``).
27952813
See :pep:`585` and :ref:`types-genericalias`.
27962814

2797-
Other concrete types
2798-
""""""""""""""""""""
2815+
.. _other-concrete-types:
27992816

2800-
.. class:: IO
2801-
TextIO
2802-
BinaryIO
2803-
2804-
Generic type ``IO[AnyStr]`` and its subclasses ``TextIO(IO[str])``
2805-
and ``BinaryIO(IO[bytes])``
2806-
represent the types of I/O streams such as returned by
2807-
:func:`open`.
2808-
2809-
.. deprecated-removed:: 3.8 3.13
2810-
The ``typing.io`` namespace is deprecated and will be removed.
2811-
These types should be directly imported from ``typing`` instead.
2817+
Aliases to other concrete types
2818+
"""""""""""""""""""""""""""""""
28122819

28132820
.. class:: Pattern
28142821
Match
@@ -2851,11 +2858,11 @@ Other concrete types
28512858
currently planned, but users are encouraged to use
28522859
:class:`str` instead of ``Text``.
28532860

2854-
Abstract Base Classes
2855-
---------------------
2861+
.. _abstract-base-classes:
2862+
.. _corresponding-to-collections-in-collections-abc:
28562863

2857-
Corresponding to collections in :mod:`collections.abc`
2858-
""""""""""""""""""""""""""""""""""""""""""""""""""""""
2864+
Aliases to container ABCs in :mod:`collections.abc`
2865+
"""""""""""""""""""""""""""""""""""""""""""""""""""
28592866

28602867
.. class:: AbstractSet(Collection[T_co])
28612868

@@ -2970,80 +2977,10 @@ Corresponding to collections in :mod:`collections.abc`
29702977
:class:`collections.abc.ValuesView` now supports subscripting (``[]``).
29712978
See :pep:`585` and :ref:`types-genericalias`.
29722979

2973-
Corresponding to other types in :mod:`collections.abc`
2974-
""""""""""""""""""""""""""""""""""""""""""""""""""""""
2975-
2976-
.. class:: Iterable(Generic[T_co])
2977-
2978-
Deprecated alias to :class:`collections.abc.Iterable`.
2979-
2980-
.. deprecated:: 3.9
2981-
:class:`collections.abc.Iterable` now supports subscripting (``[]``).
2982-
See :pep:`585` and :ref:`types-genericalias`.
2983-
2984-
.. class:: Iterator(Iterable[T_co])
2985-
2986-
Deprecated alias to :class:`collections.abc.Iterator`.
2987-
2988-
.. deprecated:: 3.9
2989-
:class:`collections.abc.Iterator` now supports subscripting (``[]``).
2990-
See :pep:`585` and :ref:`types-genericalias`.
2991-
2992-
.. class:: Generator(Iterator[YieldType], Generic[YieldType, SendType, ReturnType])
2993-
2994-
Deprecated alias to :class:`collections.abc.Generator`.
2995-
2996-
A generator can be annotated by the generic type
2997-
``Generator[YieldType, SendType, ReturnType]``. For example::
2998-
2999-
def echo_round() -> Generator[int, float, str]:
3000-
sent = yield 0
3001-
while sent >= 0:
3002-
sent = yield round(sent)
3003-
return 'Done'
3004-
3005-
Note that unlike many other generics in the typing module, the ``SendType``
3006-
of :class:`Generator` behaves contravariantly, not covariantly or
3007-
invariantly.
3008-
3009-
If your generator will only yield values, set the ``SendType`` and
3010-
``ReturnType`` to ``None``::
3011-
3012-
def infinite_stream(start: int) -> Generator[int, None, None]:
3013-
while True:
3014-
yield start
3015-
start += 1
3016-
3017-
Alternatively, annotate your generator as having a return type of
3018-
either ``Iterable[YieldType]`` or ``Iterator[YieldType]``::
3019-
3020-
def infinite_stream(start: int) -> Iterator[int]:
3021-
while True:
3022-
yield start
3023-
start += 1
3024-
3025-
.. deprecated:: 3.9
3026-
:class:`collections.abc.Generator` now supports subscripting (``[]``).
3027-
See :pep:`585` and :ref:`types-genericalias`.
3028-
3029-
.. class:: Hashable
3030-
3031-
Alias to :class:`collections.abc.Hashable`.
3032-
3033-
.. class:: Reversible(Iterable[T_co])
3034-
3035-
Deprecated alias to :class:`collections.abc.Reversible`.
3036-
3037-
.. deprecated:: 3.9
3038-
:class:`collections.abc.Reversible` now supports subscripting (``[]``).
3039-
See :pep:`585` and :ref:`types-genericalias`.
3040-
3041-
.. class:: Sized
3042-
3043-
Alias to :class:`collections.abc.Sized`.
2980+
.. _asynchronous-programming:
30442981

3045-
Asynchronous programming
3046-
""""""""""""""""""""""""
2982+
Aliases to asynchronous ABCs in :mod:`collections.abc`
2983+
""""""""""""""""""""""""""""""""""""""""""""""""""""""
30472984

30482985
.. class:: Coroutine(Awaitable[ReturnType], Generic[YieldType, SendType, ReturnType])
30492986

@@ -3134,9 +3071,84 @@ Asynchronous programming
31343071
:class:`collections.abc.Awaitable` now supports subscripting (``[]``).
31353072
See :pep:`585` and :ref:`types-genericalias`.
31363073

3074+
.. _corresponding-to-other-types-in-collections-abc:
3075+
3076+
Aliases to other ABCs in :mod:`collections.abc`
3077+
"""""""""""""""""""""""""""""""""""""""""""""""
3078+
3079+
.. class:: Iterable(Generic[T_co])
3080+
3081+
Deprecated alias to :class:`collections.abc.Iterable`.
3082+
3083+
.. deprecated:: 3.9
3084+
:class:`collections.abc.Iterable` now supports subscripting (``[]``).
3085+
See :pep:`585` and :ref:`types-genericalias`.
3086+
3087+
.. class:: Iterator(Iterable[T_co])
3088+
3089+
Deprecated alias to :class:`collections.abc.Iterator`.
3090+
3091+
.. deprecated:: 3.9
3092+
:class:`collections.abc.Iterator` now supports subscripting (``[]``).
3093+
See :pep:`585` and :ref:`types-genericalias`.
3094+
3095+
.. class:: Generator(Iterator[YieldType], Generic[YieldType, SendType, ReturnType])
3096+
3097+
Deprecated alias to :class:`collections.abc.Generator`.
3098+
3099+
A generator can be annotated by the generic type
3100+
``Generator[YieldType, SendType, ReturnType]``. For example::
3101+
3102+
def echo_round() -> Generator[int, float, str]:
3103+
sent = yield 0
3104+
while sent >= 0:
3105+
sent = yield round(sent)
3106+
return 'Done'
3107+
3108+
Note that unlike many other generics in the typing module, the ``SendType``
3109+
of :class:`Generator` behaves contravariantly, not covariantly or
3110+
invariantly.
3111+
3112+
If your generator will only yield values, set the ``SendType`` and
3113+
``ReturnType`` to ``None``::
3114+
3115+
def infinite_stream(start: int) -> Generator[int, None, None]:
3116+
while True:
3117+
yield start
3118+
start += 1
3119+
3120+
Alternatively, annotate your generator as having a return type of
3121+
either ``Iterable[YieldType]`` or ``Iterator[YieldType]``::
3122+
3123+
def infinite_stream(start: int) -> Iterator[int]:
3124+
while True:
3125+
yield start
3126+
start += 1
3127+
3128+
.. deprecated:: 3.9
3129+
:class:`collections.abc.Generator` now supports subscripting (``[]``).
3130+
See :pep:`585` and :ref:`types-genericalias`.
3131+
3132+
.. class:: Hashable
3133+
3134+
Alias to :class:`collections.abc.Hashable`.
3135+
3136+
.. class:: Reversible(Iterable[T_co])
3137+
3138+
Deprecated alias to :class:`collections.abc.Reversible`.
3139+
3140+
.. deprecated:: 3.9
3141+
:class:`collections.abc.Reversible` now supports subscripting (``[]``).
3142+
See :pep:`585` and :ref:`types-genericalias`.
3143+
3144+
.. class:: Sized
3145+
3146+
Alias to :class:`collections.abc.Sized`.
3147+
3148+
.. _context-manager-types:
31373149

3138-
Context manager types
3139-
"""""""""""""""""""""
3150+
Aliases to :mod:`contextlib` ABCs
3151+
"""""""""""""""""""""""""""""""""
31403152

31413153
.. class:: ContextManager(Generic[T_co])
31423154

0 commit comments

Comments
 (0)