Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

More reorganisation of the typing docs #105787

Merged
merged 1 commit into from
Jun 15, 2023
Merged

More reorganisation of the typing docs #105787

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
218 changes: 117 additions & 101 deletions Doc/library/typing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2425,6 +2425,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
------------------------

Expand Down Expand Up @@ -3012,11 +3024,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])

Expand Down Expand Up @@ -3078,8 +3094,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])

Expand Down Expand Up @@ -3134,17 +3152,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
"""""""""""""""""""""""""""""""

.. class:: Pattern
Match
Expand Down Expand Up @@ -3183,11 +3194,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])

Expand Down Expand Up @@ -3302,86 +3313,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])

Expand Down Expand Up @@ -3472,9 +3407,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])

Expand Down