From 412c358a97c3d9830004e4b940214b066c0cc062 Mon Sep 17 00:00:00 2001 From: STerliakov Date: Sat, 31 Aug 2024 18:08:39 +0200 Subject: [PATCH 01/18] Move typing docs for deprecated aliases to collections.abc --- Doc/library/collections.abc.rst | 131 ++++++++++++++++++++++++++------ Doc/library/typing.rst | 87 --------------------- 2 files changed, 109 insertions(+), 109 deletions(-) diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst index a63a55caa0f66d..be84edaf636e8b 100644 --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -106,7 +106,7 @@ a :class:`Mapping`. .. versionadded:: 3.9 These abstract classes now support ``[]``. See :ref:`types-genericalias` - and :pep:`585`. + and :pep:`585`. They, however, do not inherit from :class:`~typing.Generic` explicitly. .. _collections-abstract-base-classes: @@ -197,7 +197,7 @@ Collections Abstract Base Classes -- Detailed Descriptions ---------------------------------------------------------- -.. class:: Container +.. class:: Container[T_co] ABC for classes that provide the :meth:`~object.__contains__` method. @@ -213,7 +213,10 @@ Collections Abstract Base Classes -- Detailed Descriptions ABC for classes that provide the :meth:`~object.__call__` method. -.. class:: Iterable + See :ref:`annotating-callables` for details on how to use + :class:`Callable` and :class:`~typing.Callable` in type annotations. + +.. class:: Iterable[T_co] ABC for classes that provide the :meth:`~container.__iter__` method. @@ -224,36 +227,71 @@ Collections Abstract Base Classes -- Detailed Descriptions The only reliable way to determine whether an object is :term:`iterable` is to call ``iter(obj)``. -.. class:: Collection +.. class:: Collection[T_co](Sized, Iterable[T_co], Container[T_co]) ABC for sized iterable container classes. .. versionadded:: 3.6 -.. class:: Iterator +.. class:: Iterator[T_co](Iterable[T_co]) ABC for classes that provide the :meth:`~iterator.__iter__` and :meth:`~iterator.__next__` methods. See also the definition of :term:`iterator`. -.. class:: Reversible +.. class:: Reversible[T_co](Iterable[T_co]) ABC for iterable classes that also provide the :meth:`~object.__reversed__` method. .. versionadded:: 3.6 -.. class:: Generator +.. class:: Generator[YieldType_co, SendType_contra, ReturnType_co](Iterator[YieldType_co]) ABC for :term:`generator` classes that implement the protocol defined in :pep:`342` that extends :term:`iterators ` with the :meth:`~generator.send`, :meth:`~generator.throw` and :meth:`~generator.close` methods. + 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. + + The ``SendType`` and ``ReturnType`` parameters default to :const:`!None`:: + + def infinite_stream(start: int) -> Generator[int]: + while True: + yield start + start += 1 + + It is also possible to set these types explicitly:: + + 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 + .. versionadded:: 3.5 -.. class:: Sequence - MutableSequence +.. class:: Sequence[T_co](Reversible[T_co], Collection[T_co]) + MutableSequence[T](Sequence[T]) ABCs for read-only and mutable :term:`sequences `. @@ -270,24 +308,29 @@ Collections Abstract Base Classes -- Detailed Descriptions The index() method added support for *stop* and *start* arguments. -.. class:: Set - MutableSet +.. class:: Set[T_co](Collection[T_co]) + MutableSet[T](Set[T]) ABCs for read-only and mutable :ref:`sets `. -.. class:: Mapping - MutableMapping +.. class:: Mapping[KT, VT_co](Collection[KT], Generic[KT, VT_co]) + MutableMapping[KT, VT](Mapping[KT, VT]) ABCs for read-only and mutable :term:`mappings `. -.. class:: MappingView - ItemsView - KeysView - ValuesView + Example use in type annotations:: + + def get_position_in_index(word_list: Mapping[str, int], word: str) -> int: + return word_list[word] + +.. class:: MappingView(Sized) + ItemsView[KT_co, VT_co](MappingView, Set[tuple[KT_co, VT_co]]) + KeysView[KT_co](MappingView, Set[KT_co]) + ValuesView[VT_co](MappingView, Collection[VT_co]) ABCs for mapping, items, keys, and values :term:`views `. -.. class:: Awaitable +.. class:: Awaitable[T_co] ABC for :term:`awaitable` objects, which can be used in :keyword:`await` expressions. Custom implementations must provide the @@ -305,7 +348,7 @@ Collections Abstract Base Classes -- Detailed Descriptions .. versionadded:: 3.5 -.. class:: Coroutine +.. class:: Coroutine[YieldType_co, SendType_contra, ReturnType_co](Awaitable[ReturnType_co]) ABC for :term:`coroutine` compatible classes. These implement the following methods, defined in :ref:`coroutine-objects`: @@ -321,27 +364,71 @@ Collections Abstract Base Classes -- Detailed Descriptions Using ``isinstance(gencoro, Coroutine)`` for them will return ``False``. Use :func:`inspect.isawaitable` to detect them. + The variance and order of type variables + correspond to those of :class:`Generator`, for example:: + + from collections.abc import Coroutine + c: Coroutine[list[str], str, int] # Some coroutine defined elsewhere + x = c.send('hi') # Inferred type of 'x' is list[str] + async def bar() -> None: + y = await c # Inferred type of 'y' is int + .. versionadded:: 3.5 -.. class:: AsyncIterable +.. class:: AsyncIterable[T_co] ABC for classes that provide an ``__aiter__`` method. See also the definition of :term:`asynchronous iterable`. .. versionadded:: 3.5 -.. class:: AsyncIterator +.. class:: AsyncIterator[T_co](AsyncIterable[T_co]) ABC for classes that provide ``__aiter__`` and ``__anext__`` methods. See also the definition of :term:`asynchronous iterator`. .. versionadded:: 3.5 -.. class:: AsyncGenerator +.. class:: AsyncGenerator[YieldType_co, SendType_contra](AsyncIterator[YieldType_co]) ABC for :term:`asynchronous generator` classes that implement the protocol defined in :pep:`525` and :pep:`492`. + An async generator can be annotated by the generic type + ``AsyncGenerator[YieldType, SendType]``. For example:: + + async def echo_round() -> AsyncGenerator[int, float]: + sent = yield 0 + while sent >= 0.0: + rounded = await round(sent) + sent = yield rounded + + Unlike normal generators, async generators cannot return a value, so there + is no ``ReturnType`` type parameter. As with :class:`Generator`, the + ``SendType`` behaves contravariantly. + + The ``SendType`` defaults to :const:`!None`:: + + async def infinite_stream(start: int) -> AsyncGenerator[int]: + while True: + yield start + start = await increment(start) + + It is also possible to set this type explicitly:: + + async def infinite_stream(start: int) -> AsyncGenerator[int, None]: + while True: + yield start + start = await increment(start) + + Alternatively, annotate your generator as having a return type of + either ``AsyncIterable[YieldType]`` or ``AsyncIterator[YieldType]``:: + + async def infinite_stream(start: int) -> AsyncIterator[int]: + while True: + yield start + start = await increment(start) + .. versionadded:: 3.6 .. class:: Buffer diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 7d1d317b9f8f8a..ec1bd0457ad67c 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -3544,11 +3544,6 @@ Aliases to container ABCs in :mod:`collections.abc` 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: - return word_list[word] - .. deprecated:: 3.9 :class:`collections.abc.Mapping` now supports subscripting (``[]``). See :pep:`585` and :ref:`types-genericalias`. @@ -3612,15 +3607,6 @@ Aliases to asynchronous ABCs in :mod:`collections.abc` Deprecated alias to :class:`collections.abc.Coroutine`. - The variance and order of type variables - correspond to those of :class:`Generator`, for example:: - - from collections.abc import Coroutine - c: Coroutine[list[str], str, int] # Some coroutine defined elsewhere - x = c.send('hi') # Inferred type of 'x' is list[str] - async def bar() -> None: - y = await c # Inferred type of 'y' is int - .. versionadded:: 3.5.3 .. deprecated:: 3.9 @@ -3631,41 +3617,6 @@ Aliases to asynchronous ABCs in :mod:`collections.abc` Deprecated alias to :class:`collections.abc.AsyncGenerator`. - An async generator can be annotated by the generic type - ``AsyncGenerator[YieldType, SendType]``. For example:: - - async def echo_round() -> AsyncGenerator[int, float]: - sent = yield 0 - while sent >= 0.0: - rounded = await round(sent) - sent = yield rounded - - Unlike normal generators, async generators cannot return a value, so there - is no ``ReturnType`` type parameter. As with :class:`Generator`, the - ``SendType`` behaves contravariantly. - - The ``SendType`` defaults to :const:`!None`:: - - async def infinite_stream(start: int) -> AsyncGenerator[int]: - while True: - yield start - start = await increment(start) - - It is also possible to set this type explicitly:: - - async def infinite_stream(start: int) -> AsyncGenerator[int, None]: - while True: - yield start - start = await increment(start) - - Alternatively, annotate your generator as having a return type of - either ``AsyncIterable[YieldType]`` or ``AsyncIterator[YieldType]``:: - - async def infinite_stream(start: int) -> AsyncIterator[int]: - while True: - yield start - start = await increment(start) - .. versionadded:: 3.6.1 .. deprecated:: 3.9 @@ -3731,9 +3682,6 @@ Aliases to other ABCs in :mod:`collections.abc` Deprecated alias to :class:`collections.abc.Callable`. - See :ref:`annotating-callables` for details on how to use - :class:`collections.abc.Callable` and ``typing.Callable`` in type annotations. - .. deprecated:: 3.9 :class:`collections.abc.Callable` now supports subscripting (``[]``). See :pep:`585` and :ref:`types-genericalias`. @@ -3746,41 +3694,6 @@ Aliases to other ABCs in :mod:`collections.abc` 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. - - The ``SendType`` and ``ReturnType`` parameters default to :const:`!None`:: - - def infinite_stream(start: int) -> Generator[int]: - while True: - yield start - start += 1 - - It is also possible to set these types explicitly:: - - 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`. From 3a713125fc21d825f6502122e302bc491368eb2f Mon Sep 17 00:00:00 2001 From: STerliakov Date: Sat, 31 Aug 2024 18:55:53 +0200 Subject: [PATCH 02/18] Do the same with `contextlib` references --- Doc/library/contextlib.rst | 14 ++++++++++++-- Doc/library/typing.rst | 10 ---------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index f5b349441bcfee..c17a65c5a43c09 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -18,7 +18,7 @@ Utilities Functions and classes provided: -.. class:: AbstractContextManager +.. class:: AbstractContextManager[T_co, ExitT_co] An :term:`abstract base class` for classes that implement :meth:`object.__enter__` and :meth:`object.__exit__`. A default @@ -26,10 +26,15 @@ Functions and classes provided: ``self`` while :meth:`object.__exit__` is an abstract method which by default returns ``None``. See also the definition of :ref:`typecontextmanager`. + The first type parameter, ``T_co``, represents the type returned by + the :meth:`~object.__enter__` method. The optional second type parameter, ``ExitT_co``, + which defaults to ``bool | None``, represents the type returned by the + :meth:`~object.__exit__` method. + .. versionadded:: 3.6 -.. class:: AbstractAsyncContextManager +.. class:: AbstractAsyncContextManager[T_co, AExitT_co] An :term:`abstract base class` for classes that implement :meth:`object.__aenter__` and :meth:`object.__aexit__`. A default @@ -38,6 +43,11 @@ Functions and classes provided: returns ``None``. See also the definition of :ref:`async-context-managers`. + The first type parameter, ``T_co``, represents the type returned by + the :meth:`~object.__aenter__` method. The optional second type parameter, ``AExitT_co``, + which defaults to ``bool | None``, represents the type returned by the + :meth:`~object.__aexit__` method. + .. versionadded:: 3.7 diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index ec1bd0457ad67c..d2aea983e52687 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -3732,11 +3732,6 @@ Aliases to :mod:`contextlib` ABCs Deprecated alias to :class:`contextlib.AbstractContextManager`. - The first type parameter, ``T_co``, represents the type returned by - the :meth:`~object.__enter__` method. The optional second type parameter, ``ExitT_co``, - which defaults to ``bool | None``, represents the type returned by the - :meth:`~object.__exit__` method. - .. versionadded:: 3.5.4 .. deprecated:: 3.9 @@ -3751,11 +3746,6 @@ Aliases to :mod:`contextlib` ABCs Deprecated alias to :class:`contextlib.AbstractAsyncContextManager`. - The first type parameter, ``T_co``, represents the type returned by - the :meth:`~object.__aenter__` method. The optional second type parameter, ``AExitT_co``, - which defaults to ``bool | None``, represents the type returned by the - :meth:`~object.__aexit__` method. - .. versionadded:: 3.6.2 .. deprecated:: 3.9 From c146cbd5d0fa23297a2dcbd7fc707d318d0f0b37 Mon Sep 17 00:00:00 2001 From: STerliakov Date: Sun, 1 Sep 2024 02:25:39 +0200 Subject: [PATCH 03/18] Add a generators&coroutines section --- Doc/library/collections.abc.rst | 84 ++++----------------------------- Doc/library/typing.rst | 80 +++++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+), 75 deletions(-) diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst index be84edaf636e8b..b7d0f6b2bdada2 100644 --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -253,40 +253,9 @@ Collections Abstract Base Classes -- Detailed Descriptions :meth:`~generator.send`, :meth:`~generator.throw` and :meth:`~generator.close` methods. - 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. - - The ``SendType`` and ``ReturnType`` parameters default to :const:`!None`:: - - def infinite_stream(start: int) -> Generator[int]: - while True: - yield start - start += 1 - - It is also possible to set these types explicitly:: - - 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 + Refer to + :ref:`annotating generators and coroutines ` + section for details of using this class in type annotations. .. versionadded:: 3.5 @@ -365,13 +334,9 @@ Collections Abstract Base Classes -- Detailed Descriptions Use :func:`inspect.isawaitable` to detect them. The variance and order of type variables - correspond to those of :class:`Generator`, for example:: - - from collections.abc import Coroutine - c: Coroutine[list[str], str, int] # Some coroutine defined elsewhere - x = c.send('hi') # Inferred type of 'x' is list[str] - async def bar() -> None: - y = await c # Inferred type of 'y' is int + correspond to those of :class:`Generator`. Refer to + :ref:`annotating generators and coroutines ` + section for details of using this class in type annotations. .. versionadded:: 3.5 @@ -394,40 +359,9 @@ Collections Abstract Base Classes -- Detailed Descriptions ABC for :term:`asynchronous generator` classes that implement the protocol defined in :pep:`525` and :pep:`492`. - An async generator can be annotated by the generic type - ``AsyncGenerator[YieldType, SendType]``. For example:: - - async def echo_round() -> AsyncGenerator[int, float]: - sent = yield 0 - while sent >= 0.0: - rounded = await round(sent) - sent = yield rounded - - Unlike normal generators, async generators cannot return a value, so there - is no ``ReturnType`` type parameter. As with :class:`Generator`, the - ``SendType`` behaves contravariantly. - - The ``SendType`` defaults to :const:`!None`:: - - async def infinite_stream(start: int) -> AsyncGenerator[int]: - while True: - yield start - start = await increment(start) - - It is also possible to set this type explicitly:: - - async def infinite_stream(start: int) -> AsyncGenerator[int, None]: - while True: - yield start - start = await increment(start) - - Alternatively, annotate your generator as having a return type of - either ``AsyncIterable[YieldType]`` or ``AsyncIterator[YieldType]``:: - - async def infinite_stream(start: int) -> AsyncIterator[int]: - while True: - yield start - start = await increment(start) + Refer to + :ref:`annotating generators and coroutines ` + section for details of using this class in type annotations. .. versionadded:: 3.6 diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index d2aea983e52687..6a38d91608ff75 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -441,6 +441,86 @@ For example:: ``type[Any]`` is equivalent to :class:`type`, which is the root of Python's :ref:`metaclass hierarchy `. + +.. _annotating-generators-and-coroutines: + +Annotating generators and coroutines +==================================== + +A generator can be annotated by the generic type +:class:`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:`~collections.abc.Generator` behaves contravariantly, not covariantly or +invariantly. + +The ``SendType`` and ``ReturnType`` parameters default to :const:`!None`:: + + def infinite_stream(start: int) -> Generator[int]: + while True: + yield start + start += 1 + +It is also possible to set these types explicitly:: + + 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 :class:`Iterable[YieldType] ` +or :class:`Iterator[YieldType] `:: + + def infinite_stream(start: int) -> Iterator[int]: + while True: + yield start + start += 1 + +Async generators are handled in a similar fashion, but don't +expect a `ReturnType` type argument +(:class:`AsyncGenerator[YieldType, SendType] `). +The `SendType` argument defaults to :const:`!None`, so the following definitions +are equivalent:: + + async def infinite_stream(start: int) -> AsyncGenerator[int]: + while True: + yield start + start = await increment(start) + + async def infinite_stream(start: int) -> AsyncGenerator[int, None]: + while True: + yield start + start = await increment(start) + +As in synchronous case, +:class:`AsyncIterable[YieldType] ` +and :class:`AsyncIterator[YieldType] ` are +available as well:: + + async def infinite_stream(start: int) -> AsyncIterator[int]: + while True: + yield start + start = await increment(start) + +Coroutines can be annotated using +:class:`Coroutine[YieldType, SendType, ReturnType] `. +Generic arguments correspond to those of :class:`~collections.abc.Generator`, +for example:: + + from collections.abc import Coroutine + c: Coroutine[list[str], str, int] # Some coroutine defined elsewhere + x = c.send('hi') # Inferred type of 'x' is list[str] + async def bar() -> None: + y = await c # Inferred type of 'y' is int + .. _user-defined-generics: User-defined generic types From 8b6f65c06a4ca7cebd55c9fff71d7fde11e6643d Mon Sep 17 00:00:00 2001 From: STerliakov Date: Sun, 1 Sep 2024 02:25:57 +0200 Subject: [PATCH 04/18] Replace PEP695 parameters with Generic inheritance --- Doc/library/collections.abc.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst index b7d0f6b2bdada2..e6fb5f1f64a7e9 100644 --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -197,7 +197,7 @@ Collections Abstract Base Classes -- Detailed Descriptions ---------------------------------------------------------- -.. class:: Container[T_co] +.. class:: Container(Generic[T_co]) ABC for classes that provide the :meth:`~object.__contains__` method. @@ -216,7 +216,7 @@ Collections Abstract Base Classes -- Detailed Descriptions See :ref:`annotating-callables` for details on how to use :class:`Callable` and :class:`~typing.Callable` in type annotations. -.. class:: Iterable[T_co] +.. class:: Iterable(Generic[T_co]) ABC for classes that provide the :meth:`~container.__iter__` method. @@ -227,26 +227,26 @@ Collections Abstract Base Classes -- Detailed Descriptions The only reliable way to determine whether an object is :term:`iterable` is to call ``iter(obj)``. -.. class:: Collection[T_co](Sized, Iterable[T_co], Container[T_co]) +.. class:: Collection(Sized, Iterable[T_co], Container[T_co]) ABC for sized iterable container classes. .. versionadded:: 3.6 -.. class:: Iterator[T_co](Iterable[T_co]) +.. class:: Iterator(Iterable[T_co]) ABC for classes that provide the :meth:`~iterator.__iter__` and :meth:`~iterator.__next__` methods. See also the definition of :term:`iterator`. -.. class:: Reversible[T_co](Iterable[T_co]) +.. class:: Reversible(Iterable[T_co]) ABC for iterable classes that also provide the :meth:`~object.__reversed__` method. .. versionadded:: 3.6 -.. class:: Generator[YieldType_co, SendType_contra, ReturnType_co](Iterator[YieldType_co]) +.. class:: Generator(Iterator[YieldType_co], Generic[YieldType_co, SendType_contra, ReturnType_co]) ABC for :term:`generator` classes that implement the protocol defined in :pep:`342` that extends :term:`iterators ` with the @@ -259,7 +259,7 @@ Collections Abstract Base Classes -- Detailed Descriptions .. versionadded:: 3.5 -.. class:: Sequence[T_co](Reversible[T_co], Collection[T_co]) +.. class:: Sequence(Reversible[T_co], Collection[T_co]) MutableSequence[T](Sequence[T]) ABCs for read-only and mutable :term:`sequences `. @@ -277,12 +277,12 @@ Collections Abstract Base Classes -- Detailed Descriptions The index() method added support for *stop* and *start* arguments. -.. class:: Set[T_co](Collection[T_co]) +.. class:: Set(Collection[T_co]) MutableSet[T](Set[T]) ABCs for read-only and mutable :ref:`sets `. -.. class:: Mapping[KT, VT_co](Collection[KT], Generic[KT, VT_co]) +.. class:: Mapping(Collection[KT], Generic[KT, VT_co]) MutableMapping[KT, VT](Mapping[KT, VT]) ABCs for read-only and mutable :term:`mappings `. @@ -299,7 +299,7 @@ Collections Abstract Base Classes -- Detailed Descriptions ABCs for mapping, items, keys, and values :term:`views `. -.. class:: Awaitable[T_co] +.. class:: Awaitable(Generic[T_co]) ABC for :term:`awaitable` objects, which can be used in :keyword:`await` expressions. Custom implementations must provide the @@ -317,7 +317,7 @@ Collections Abstract Base Classes -- Detailed Descriptions .. versionadded:: 3.5 -.. class:: Coroutine[YieldType_co, SendType_contra, ReturnType_co](Awaitable[ReturnType_co]) +.. class:: Coroutine(Awaitable[ReturnType_co], Generic(YieldType_co, SendType_contra, ReturnType_co)) ABC for :term:`coroutine` compatible classes. These implement the following methods, defined in :ref:`coroutine-objects`: @@ -340,21 +340,21 @@ Collections Abstract Base Classes -- Detailed Descriptions .. versionadded:: 3.5 -.. class:: AsyncIterable[T_co] +.. class:: AsyncIterable(Generic[T_co]) ABC for classes that provide an ``__aiter__`` method. See also the definition of :term:`asynchronous iterable`. .. versionadded:: 3.5 -.. class:: AsyncIterator[T_co](AsyncIterable[T_co]) +.. class:: AsyncIterator(AsyncIterable[T_co]) ABC for classes that provide ``__aiter__`` and ``__anext__`` methods. See also the definition of :term:`asynchronous iterator`. .. versionadded:: 3.5 -.. class:: AsyncGenerator[YieldType_co, SendType_contra](AsyncIterator[YieldType_co]) +.. class:: AsyncGenerator(AsyncIterator[YieldType_co], Generic[YieldType_co, SendType_contra]) ABC for :term:`asynchronous generator` classes that implement the protocol defined in :pep:`525` and :pep:`492`. From 5aa430c843ed003fd3c11513538878d455ee0d2f Mon Sep 17 00:00:00 2001 From: STerliakov Date: Sun, 1 Sep 2024 02:38:29 +0200 Subject: [PATCH 05/18] Remove type arguments for now --- Doc/library/collections.abc.rst | 42 ++++++++++++++++----------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst index e6fb5f1f64a7e9..ae43c4ff9c7aab 100644 --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -197,7 +197,7 @@ Collections Abstract Base Classes -- Detailed Descriptions ---------------------------------------------------------- -.. class:: Container(Generic[T_co]) +.. class:: Container ABC for classes that provide the :meth:`~object.__contains__` method. @@ -216,7 +216,7 @@ Collections Abstract Base Classes -- Detailed Descriptions See :ref:`annotating-callables` for details on how to use :class:`Callable` and :class:`~typing.Callable` in type annotations. -.. class:: Iterable(Generic[T_co]) +.. class:: Iterable ABC for classes that provide the :meth:`~container.__iter__` method. @@ -227,26 +227,26 @@ Collections Abstract Base Classes -- Detailed Descriptions The only reliable way to determine whether an object is :term:`iterable` is to call ``iter(obj)``. -.. class:: Collection(Sized, Iterable[T_co], Container[T_co]) +.. class:: Collection ABC for sized iterable container classes. .. versionadded:: 3.6 -.. class:: Iterator(Iterable[T_co]) +.. class:: Iterator ABC for classes that provide the :meth:`~iterator.__iter__` and :meth:`~iterator.__next__` methods. See also the definition of :term:`iterator`. -.. class:: Reversible(Iterable[T_co]) +.. class:: Reversible ABC for iterable classes that also provide the :meth:`~object.__reversed__` method. .. versionadded:: 3.6 -.. class:: Generator(Iterator[YieldType_co], Generic[YieldType_co, SendType_contra, ReturnType_co]) +.. class:: Generator ABC for :term:`generator` classes that implement the protocol defined in :pep:`342` that extends :term:`iterators ` with the @@ -259,8 +259,8 @@ Collections Abstract Base Classes -- Detailed Descriptions .. versionadded:: 3.5 -.. class:: Sequence(Reversible[T_co], Collection[T_co]) - MutableSequence[T](Sequence[T]) +.. class:: Sequence + MutableSequence ABCs for read-only and mutable :term:`sequences `. @@ -277,13 +277,13 @@ Collections Abstract Base Classes -- Detailed Descriptions The index() method added support for *stop* and *start* arguments. -.. class:: Set(Collection[T_co]) - MutableSet[T](Set[T]) +.. class:: Set + MutableSet ABCs for read-only and mutable :ref:`sets `. -.. class:: Mapping(Collection[KT], Generic[KT, VT_co]) - MutableMapping[KT, VT](Mapping[KT, VT]) +.. class:: Mapping + MutableMapping ABCs for read-only and mutable :term:`mappings `. @@ -292,14 +292,14 @@ Collections Abstract Base Classes -- Detailed Descriptions def get_position_in_index(word_list: Mapping[str, int], word: str) -> int: return word_list[word] -.. class:: MappingView(Sized) - ItemsView[KT_co, VT_co](MappingView, Set[tuple[KT_co, VT_co]]) - KeysView[KT_co](MappingView, Set[KT_co]) - ValuesView[VT_co](MappingView, Collection[VT_co]) +.. class:: MappingView + ItemsView + KeysView + ValuesView ABCs for mapping, items, keys, and values :term:`views `. -.. class:: Awaitable(Generic[T_co]) +.. class:: Awaitable ABC for :term:`awaitable` objects, which can be used in :keyword:`await` expressions. Custom implementations must provide the @@ -317,7 +317,7 @@ Collections Abstract Base Classes -- Detailed Descriptions .. versionadded:: 3.5 -.. class:: Coroutine(Awaitable[ReturnType_co], Generic(YieldType_co, SendType_contra, ReturnType_co)) +.. class:: Coroutine ABC for :term:`coroutine` compatible classes. These implement the following methods, defined in :ref:`coroutine-objects`: @@ -340,21 +340,21 @@ Collections Abstract Base Classes -- Detailed Descriptions .. versionadded:: 3.5 -.. class:: AsyncIterable(Generic[T_co]) +.. class:: AsyncIterable ABC for classes that provide an ``__aiter__`` method. See also the definition of :term:`asynchronous iterable`. .. versionadded:: 3.5 -.. class:: AsyncIterator(AsyncIterable[T_co]) +.. class:: AsyncIterator ABC for classes that provide ``__aiter__`` and ``__anext__`` methods. See also the definition of :term:`asynchronous iterator`. .. versionadded:: 3.5 -.. class:: AsyncGenerator(AsyncIterator[YieldType_co], Generic[YieldType_co, SendType_contra]) +.. class:: AsyncGenerator ABC for :term:`asynchronous generator` classes that implement the protocol defined in :pep:`525` and :pep:`492`. From fb137364e9dc255547b63a4782b06089ee11b555 Mon Sep 17 00:00:00 2001 From: STerliakov Date: Sun, 1 Sep 2024 02:38:50 +0200 Subject: [PATCH 06/18] Revert "Do the same with `contextlib` references" Similarly to `collections.abc` changes, this is not acceptable for now. --- Doc/library/contextlib.rst | 14 ++------------ Doc/library/typing.rst | 10 ++++++++++ 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index c17a65c5a43c09..f5b349441bcfee 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -18,7 +18,7 @@ Utilities Functions and classes provided: -.. class:: AbstractContextManager[T_co, ExitT_co] +.. class:: AbstractContextManager An :term:`abstract base class` for classes that implement :meth:`object.__enter__` and :meth:`object.__exit__`. A default @@ -26,15 +26,10 @@ Functions and classes provided: ``self`` while :meth:`object.__exit__` is an abstract method which by default returns ``None``. See also the definition of :ref:`typecontextmanager`. - The first type parameter, ``T_co``, represents the type returned by - the :meth:`~object.__enter__` method. The optional second type parameter, ``ExitT_co``, - which defaults to ``bool | None``, represents the type returned by the - :meth:`~object.__exit__` method. - .. versionadded:: 3.6 -.. class:: AbstractAsyncContextManager[T_co, AExitT_co] +.. class:: AbstractAsyncContextManager An :term:`abstract base class` for classes that implement :meth:`object.__aenter__` and :meth:`object.__aexit__`. A default @@ -43,11 +38,6 @@ Functions and classes provided: returns ``None``. See also the definition of :ref:`async-context-managers`. - The first type parameter, ``T_co``, represents the type returned by - the :meth:`~object.__aenter__` method. The optional second type parameter, ``AExitT_co``, - which defaults to ``bool | None``, represents the type returned by the - :meth:`~object.__aexit__` method. - .. versionadded:: 3.7 diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 6a38d91608ff75..acc24ba9a33335 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -3812,6 +3812,11 @@ Aliases to :mod:`contextlib` ABCs Deprecated alias to :class:`contextlib.AbstractContextManager`. + The first type parameter, ``T_co``, represents the type returned by + the :meth:`~object.__enter__` method. The optional second type parameter, ``ExitT_co``, + which defaults to ``bool | None``, represents the type returned by the + :meth:`~object.__exit__` method. + .. versionadded:: 3.5.4 .. deprecated:: 3.9 @@ -3826,6 +3831,11 @@ Aliases to :mod:`contextlib` ABCs Deprecated alias to :class:`contextlib.AbstractAsyncContextManager`. + The first type parameter, ``T_co``, represents the type returned by + the :meth:`~object.__aenter__` method. The optional second type parameter, ``AExitT_co``, + which defaults to ``bool | None``, represents the type returned by the + :meth:`~object.__aexit__` method. + .. versionadded:: 3.6.2 .. deprecated:: 3.9 From e7bd7b718bd7e170408c09846571b5aae2f0fc16 Mon Sep 17 00:00:00 2001 From: STerliakov Date: Sun, 1 Sep 2024 02:46:44 +0200 Subject: [PATCH 07/18] Use double backticks --- Doc/library/typing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index acc24ba9a33335..f2496fc56d40c9 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -485,9 +485,9 @@ or :class:`Iterator[YieldType] `:: start += 1 Async generators are handled in a similar fashion, but don't -expect a `ReturnType` type argument +expect a ``ReturnType`` type argument (:class:`AsyncGenerator[YieldType, SendType] `). -The `SendType` argument defaults to :const:`!None`, so the following definitions +The ``SendType`` argument defaults to :const:`!None`, so the following definitions are equivalent:: async def infinite_stream(start: int) -> AsyncGenerator[int]: From 5c513aa2a65bfc4b2e7aae64f90e4131c3cf0374 Mon Sep 17 00:00:00 2001 From: STerliakov Date: Sun, 1 Sep 2024 04:25:52 +0200 Subject: [PATCH 08/18] Address review comments --- Doc/library/collections.abc.rst | 11 ++++++----- Doc/library/typing.rst | 27 +++++++++++++++++++++++---- 2 files changed, 29 insertions(+), 9 deletions(-) diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst index ae43c4ff9c7aab..1108b00d6f0979 100644 --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -255,7 +255,7 @@ Collections Abstract Base Classes -- Detailed Descriptions Refer to :ref:`annotating generators and coroutines ` - section for details of using this class in type annotations. + for details of using this class in type annotations. .. versionadded:: 3.5 @@ -333,10 +333,11 @@ Collections Abstract Base Classes -- Detailed Descriptions Using ``isinstance(gencoro, Coroutine)`` for them will return ``False``. Use :func:`inspect.isawaitable` to detect them. - The variance and order of type variables - correspond to those of :class:`Generator`. Refer to + Refer to :ref:`annotating generators and coroutines ` - section for details of using this class in type annotations. + for details of using this class in type annotations. + The variance and order of type variables correspond to those of + :class:`Generator`. .. versionadded:: 3.5 @@ -361,7 +362,7 @@ Collections Abstract Base Classes -- Detailed Descriptions Refer to :ref:`annotating generators and coroutines ` - section for details of using this class in type annotations. + for details of using this class in type annotations. .. versionadded:: 3.6 diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index f2496fc56d40c9..f601de26d0098f 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -447,7 +447,7 @@ For example:: Annotating generators and coroutines ==================================== -A generator can be annotated by the generic type +A generator can be annotated using the generic type :class:`Generator[YieldType, SendType, ReturnType] `. For example:: @@ -475,8 +475,9 @@ It is also possible to set these types explicitly:: yield start start += 1 -Alternatively, annotate your generator as having a return type of -either :class:`Iterable[YieldType] ` +Simple generators that only ever yield values can also be annotated +as having a return type of either +:class:`Iterable[YieldType] ` or :class:`Iterator[YieldType] `:: def infinite_stream(start: int) -> Iterator[int]: @@ -500,7 +501,7 @@ are equivalent:: yield start start = await increment(start) -As in synchronous case, +As in the synchronous case, :class:`AsyncIterable[YieldType] ` and :class:`AsyncIterator[YieldType] ` are available as well:: @@ -3687,6 +3688,11 @@ Aliases to asynchronous ABCs in :mod:`collections.abc` Deprecated alias to :class:`collections.abc.Coroutine`. + See + :ref:`annotating generators and coroutines ` + for details of using :class:`collections.abc.Coroutine` and this class + in type annotations. + .. versionadded:: 3.5.3 .. deprecated:: 3.9 @@ -3697,6 +3703,11 @@ Aliases to asynchronous ABCs in :mod:`collections.abc` Deprecated alias to :class:`collections.abc.AsyncGenerator`. + See + :ref:`annotating generators and coroutines ` + for details of using :class:`collections.abc.AsyncGenerator` and this class + in type annotations. + .. versionadded:: 3.6.1 .. deprecated:: 3.9 @@ -3762,6 +3773,9 @@ Aliases to other ABCs in :mod:`collections.abc` Deprecated alias to :class:`collections.abc.Callable`. + See :ref:`annotating-callables` for details on how to use + :class:`collections.abc.Callable` and ``typing.Callable`` in type annotations. + .. deprecated:: 3.9 :class:`collections.abc.Callable` now supports subscripting (``[]``). See :pep:`585` and :ref:`types-genericalias`. @@ -3774,6 +3788,11 @@ Aliases to other ABCs in :mod:`collections.abc` Deprecated alias to :class:`collections.abc.Generator`. + See + :ref:`annotating generators and coroutines ` + for details of using :class:`collections.abc.Generator` and this class + in type annotations. + .. deprecated:: 3.9 :class:`collections.abc.Generator` now supports subscripting (``[]``). See :pep:`585` and :ref:`types-genericalias`. From c827599d5fd5ee02e1ca27ad3ed65a8935ba76fa Mon Sep 17 00:00:00 2001 From: STerliakov Date: Sun, 1 Sep 2024 15:54:27 +0200 Subject: [PATCH 09/18] s/details of/details on/g --- Doc/library/collections.abc.rst | 6 +++--- Doc/library/typing.rst | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst index 1108b00d6f0979..d727cbcb0b8b7e 100644 --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -255,7 +255,7 @@ Collections Abstract Base Classes -- Detailed Descriptions Refer to :ref:`annotating generators and coroutines ` - for details of using this class in type annotations. + for details on using this class in type annotations. .. versionadded:: 3.5 @@ -335,7 +335,7 @@ Collections Abstract Base Classes -- Detailed Descriptions Refer to :ref:`annotating generators and coroutines ` - for details of using this class in type annotations. + for details on using this class in type annotations. The variance and order of type variables correspond to those of :class:`Generator`. @@ -362,7 +362,7 @@ Collections Abstract Base Classes -- Detailed Descriptions Refer to :ref:`annotating generators and coroutines ` - for details of using this class in type annotations. + for details on using this class in type annotations. .. versionadded:: 3.6 diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index f601de26d0098f..4bb32aae3ce939 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -3690,7 +3690,7 @@ Aliases to asynchronous ABCs in :mod:`collections.abc` See :ref:`annotating generators and coroutines ` - for details of using :class:`collections.abc.Coroutine` and this class + for details on using :class:`collections.abc.Coroutine` and this class in type annotations. .. versionadded:: 3.5.3 @@ -3705,7 +3705,7 @@ Aliases to asynchronous ABCs in :mod:`collections.abc` See :ref:`annotating generators and coroutines ` - for details of using :class:`collections.abc.AsyncGenerator` and this class + for details on using :class:`collections.abc.AsyncGenerator` and this class in type annotations. .. versionadded:: 3.6.1 @@ -3790,7 +3790,7 @@ Aliases to other ABCs in :mod:`collections.abc` See :ref:`annotating generators and coroutines ` - for details of using :class:`collections.abc.Generator` and this class + for details on using :class:`collections.abc.Generator` and this class in type annotations. .. deprecated:: 3.9 From 8bac826b0611ddc4d7694bea10d1aaee44541f75 Mon Sep 17 00:00:00 2001 From: STerliakov Date: Sun, 1 Sep 2024 15:58:06 +0200 Subject: [PATCH 10/18] Address other review comments --- Doc/library/collections.abc.rst | 4 ++-- Doc/library/typing.rst | 18 +++++++++--------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst index d727cbcb0b8b7e..1adf12c4faa1a7 100644 --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -106,7 +106,7 @@ a :class:`Mapping`. .. versionadded:: 3.9 These abstract classes now support ``[]``. See :ref:`types-genericalias` - and :pep:`585`. They, however, do not inherit from :class:`~typing.Generic` explicitly. + and :pep:`585`. .. _collections-abstract-base-classes: @@ -336,7 +336,7 @@ Collections Abstract Base Classes -- Detailed Descriptions Refer to :ref:`annotating generators and coroutines ` for details on using this class in type annotations. - The variance and order of type variables correspond to those of + The variance and order of type parameters correspond to those of :class:`Generator`. .. versionadded:: 3.5 diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 4bb32aae3ce939..f25a4ab37c7a20 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -457,9 +457,9 @@ For example:: sent = yield round(sent) return 'Done' -Note that unlike many other generics in the typing module, the ``SendType`` -of :class:`~collections.abc.Generator` behaves contravariantly, not covariantly or -invariantly. +Note that unlike many other generic classes in the standard library, +the ``SendType`` of :class:`~collections.abc.Generator` behaves +contravariantly, not covariantly or invariantly. The ``SendType`` and ``ReturnType`` parameters default to :const:`!None`:: @@ -3690,8 +3690,8 @@ Aliases to asynchronous ABCs in :mod:`collections.abc` See :ref:`annotating generators and coroutines ` - for details on using :class:`collections.abc.Coroutine` and this class - in type annotations. + for details on using :class:`collections.abc.Coroutine` + and ``typing.Coroutine`` in type annotations. .. versionadded:: 3.5.3 @@ -3705,8 +3705,8 @@ Aliases to asynchronous ABCs in :mod:`collections.abc` See :ref:`annotating generators and coroutines ` - for details on using :class:`collections.abc.AsyncGenerator` and this class - in type annotations. + for details on using :class:`collections.abc.AsyncGenerator` + and ``typing.AsyncGenerator`` in type annotations. .. versionadded:: 3.6.1 @@ -3790,8 +3790,8 @@ Aliases to other ABCs in :mod:`collections.abc` See :ref:`annotating generators and coroutines ` - for details on using :class:`collections.abc.Generator` and this class - in type annotations. + for details on using :class:`collections.abc.Generator` + and ``typing.Generator`` in type annotations. .. deprecated:: 3.9 :class:`collections.abc.Generator` now supports subscripting (``[]``). From a65f256a2f8ba8966e89bb791a546526dd2947d0 Mon Sep 17 00:00:00 2001 From: STerliakov Date: Sun, 1 Sep 2024 17:12:45 +0200 Subject: [PATCH 11/18] Remove "This type may be used as follows" notes from List, Dict and Mapping --- Doc/library/collections.abc.rst | 5 ----- Doc/library/typing.rst | 13 ------------- 2 files changed, 18 deletions(-) diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst index 1adf12c4faa1a7..80e41c258df6cd 100644 --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -287,11 +287,6 @@ Collections Abstract Base Classes -- Detailed Descriptions ABCs for read-only and mutable :term:`mappings `. - Example use in type annotations:: - - def get_position_in_index(word_list: Mapping[str, int], word: str) -> int: - return word_list[word] - .. class:: MappingView ItemsView KeysView diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index f25a4ab37c7a20..22ef228ecb547c 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -3402,11 +3402,6 @@ Aliases to built-in types 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:: - - def count_words(text: str) -> Dict[str, int]: - ... - .. deprecated:: 3.9 :class:`builtins.dict ` now supports subscripting (``[]``). See :pep:`585` and :ref:`types-genericalias`. @@ -3419,14 +3414,6 @@ Aliases to built-in types to use an abstract collection type such as :class:`Sequence` or :class:`Iterable` rather than to use :class:`list` or :class:`!typing.List`. - This type may be used as follows:: - - def vec2[T: (int, float)](x: T, y: T) -> List[T]: - return [x, y] - - def keep_positives[T: (int, float)](vector: Sequence[T]) -> List[T]: - return [item for item in vector if item > 0] - .. deprecated:: 3.9 :class:`builtins.list ` now supports subscripting (``[]``). See :pep:`585` and :ref:`types-genericalias`. From dfa85647a06bca4fe9b717343f0ad0d2ca7d9a12 Mon Sep 17 00:00:00 2001 From: STerliakov Date: Sun, 1 Sep 2024 17:18:35 +0200 Subject: [PATCH 12/18] Remove deprecated alias to `typing.Callable` from `collections.abc` reference --- Doc/library/collections.abc.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst index 80e41c258df6cd..35579c0c7d3811 100644 --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -214,7 +214,7 @@ Collections Abstract Base Classes -- Detailed Descriptions ABC for classes that provide the :meth:`~object.__call__` method. See :ref:`annotating-callables` for details on how to use - :class:`Callable` and :class:`~typing.Callable` in type annotations. + :class:`!Callable` in type annotations. .. class:: Iterable @@ -255,7 +255,7 @@ Collections Abstract Base Classes -- Detailed Descriptions Refer to :ref:`annotating generators and coroutines ` - for details on using this class in type annotations. + for details on using :class:`!Generator` in type annotations. .. versionadded:: 3.5 @@ -330,7 +330,7 @@ Collections Abstract Base Classes -- Detailed Descriptions Refer to :ref:`annotating generators and coroutines ` - for details on using this class in type annotations. + for details on using :class:`!Coroutine` in type annotations. The variance and order of type parameters correspond to those of :class:`Generator`. @@ -357,7 +357,7 @@ Collections Abstract Base Classes -- Detailed Descriptions Refer to :ref:`annotating generators and coroutines ` - for details on using this class in type annotations. + for details on using :class:`!AsyncGenerator` in type annotations. .. versionadded:: 3.6 From 7de2e024bf75fc893015c4d306c35985367e5ba9 Mon Sep 17 00:00:00 2001 From: STerliakov Date: Sun, 1 Sep 2024 17:22:11 +0200 Subject: [PATCH 13/18] Add deprecation notice to `typing.Callable` and `typing.Type` recommendations --- Doc/library/typing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 22ef228ecb547c..eb00e95be88d18 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -208,7 +208,7 @@ Annotating callable objects =========================== Functions -- or other :term:`callable` objects -- can be annotated using -:class:`collections.abc.Callable` or :data:`typing.Callable`. +:class:`collections.abc.Callable` or deprecated :data:`typing.Callable`. ``Callable[[int], str]`` signifies a function that takes a single parameter of type :class:`int` and returns a :class:`str`. @@ -401,7 +401,7 @@ The type of class objects ========================= A variable annotated with ``C`` may accept a value of type ``C``. In -contrast, a variable annotated with ``type[C]`` (or +contrast, a variable annotated with ``type[C]`` (or deprecated :class:`typing.Type[C] `) may accept values that are classes themselves -- specifically, it will accept the *class object* of ``C``. For example:: From 587d24094aea8b6f3ae428f1bf5b4b93ae051dfa Mon Sep 17 00:00:00 2001 From: STerliakov Date: Sun, 1 Sep 2024 21:55:54 +0200 Subject: [PATCH 14/18] Use simple link --- Doc/library/collections.abc.rst | 9 +++------ Doc/library/typing.rst | 9 +++------ 2 files changed, 6 insertions(+), 12 deletions(-) diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst index 35579c0c7d3811..dd2691832eb74a 100644 --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -253,8 +253,7 @@ Collections Abstract Base Classes -- Detailed Descriptions :meth:`~generator.send`, :meth:`~generator.throw` and :meth:`~generator.close` methods. - Refer to - :ref:`annotating generators and coroutines ` + Refer to :ref:`annotating-generators-and-coroutines` for details on using :class:`!Generator` in type annotations. .. versionadded:: 3.5 @@ -328,8 +327,7 @@ Collections Abstract Base Classes -- Detailed Descriptions Using ``isinstance(gencoro, Coroutine)`` for them will return ``False``. Use :func:`inspect.isawaitable` to detect them. - Refer to - :ref:`annotating generators and coroutines ` + Refer to :ref:`annotating-generators-and-coroutines` for details on using :class:`!Coroutine` in type annotations. The variance and order of type parameters correspond to those of :class:`Generator`. @@ -355,8 +353,7 @@ Collections Abstract Base Classes -- Detailed Descriptions ABC for :term:`asynchronous generator` classes that implement the protocol defined in :pep:`525` and :pep:`492`. - Refer to - :ref:`annotating generators and coroutines ` + Refer to :ref:`annotating-generators-and-coroutines` for details on using :class:`!AsyncGenerator` in type annotations. .. versionadded:: 3.6 diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index eb00e95be88d18..7892991f08cc7d 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -3675,8 +3675,7 @@ Aliases to asynchronous ABCs in :mod:`collections.abc` Deprecated alias to :class:`collections.abc.Coroutine`. - See - :ref:`annotating generators and coroutines ` + See :ref:`annotating-generators-and-coroutines` for details on using :class:`collections.abc.Coroutine` and ``typing.Coroutine`` in type annotations. @@ -3690,8 +3689,7 @@ Aliases to asynchronous ABCs in :mod:`collections.abc` Deprecated alias to :class:`collections.abc.AsyncGenerator`. - See - :ref:`annotating generators and coroutines ` + See :ref:`annotating-generators-and-coroutines` for details on using :class:`collections.abc.AsyncGenerator` and ``typing.AsyncGenerator`` in type annotations. @@ -3775,8 +3773,7 @@ Aliases to other ABCs in :mod:`collections.abc` Deprecated alias to :class:`collections.abc.Generator`. - See - :ref:`annotating generators and coroutines ` + See :ref:`annotating-generators-and-coroutines` for details on using :class:`collections.abc.Generator` and ``typing.Generator`` in type annotations. From e35d682b494ee5682db2c65116e14084b2b40d37 Mon Sep 17 00:00:00 2001 From: STerliakov Date: Sun, 1 Sep 2024 22:14:56 +0200 Subject: [PATCH 15/18] Reference modern `collections.abc` aliases --- Doc/library/typing.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 7892991f08cc7d..5ac32d0c1aaa3e 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -3399,7 +3399,7 @@ Aliases to built-in types Deprecated alias to :class:`dict`. Note that to annotate arguments, it is preferred - to use an abstract collection type such as :class:`Mapping` + to use an abstract collection type such as :class:`~collections.abc.Mapping` rather than to use :class:`dict` or :class:`!typing.Dict`. .. deprecated:: 3.9 @@ -3411,8 +3411,9 @@ Aliases to built-in types 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` rather than to use :class:`list` or :class:`!typing.List`. + to use an abstract collection type such as + :class:`~collections.abc.Sequence` or :class:`~collections.abc.Iterable` + rather than to use :class:`list` or :class:`!typing.List`. .. deprecated:: 3.9 :class:`builtins.list ` now supports subscripting (``[]``). @@ -3423,7 +3424,7 @@ Aliases to built-in types Deprecated alias to :class:`builtins.set `. Note that to annotate arguments, it is preferred - to use an abstract collection type such as :class:`AbstractSet` + to use an abstract collection type such as :class:`~collections.abc.Set` rather than to use :class:`set` or :class:`!typing.Set`. .. deprecated:: 3.9 From fc16d76b8c63c8e3c9b7d7d3fbc2c826e8c7ca7e Mon Sep 17 00:00:00 2001 From: STerliakov Date: Sun, 1 Sep 2024 22:36:27 +0200 Subject: [PATCH 16/18] Use fully qualified name for `collections.abc.Set` to avoid confusion with `typing.Set` --- Doc/library/typing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 5ac32d0c1aaa3e..347fd7b564b458 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -3424,7 +3424,7 @@ Aliases to built-in types Deprecated alias to :class:`builtins.set `. Note that to annotate arguments, it is preferred - to use an abstract collection type such as :class:`~collections.abc.Set` + to use an abstract collection type such as :class:`collections.abc.Set` rather than to use :class:`set` or :class:`!typing.Set`. .. deprecated:: 3.9 From 24ff30e86f4591a4c2000e45a50f14acc2729088 Mon Sep 17 00:00:00 2001 From: STerliakov Date: Tue, 3 Sep 2024 17:47:44 +0200 Subject: [PATCH 17/18] s/Refer to/See --- Doc/library/collections.abc.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst index dd2691832eb74a..b77a36393b2769 100644 --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -253,7 +253,7 @@ Collections Abstract Base Classes -- Detailed Descriptions :meth:`~generator.send`, :meth:`~generator.throw` and :meth:`~generator.close` methods. - Refer to :ref:`annotating-generators-and-coroutines` + See :ref:`annotating-generators-and-coroutines` for details on using :class:`!Generator` in type annotations. .. versionadded:: 3.5 @@ -327,7 +327,7 @@ Collections Abstract Base Classes -- Detailed Descriptions Using ``isinstance(gencoro, Coroutine)`` for them will return ``False``. Use :func:`inspect.isawaitable` to detect them. - Refer to :ref:`annotating-generators-and-coroutines` + See :ref:`annotating-generators-and-coroutines` for details on using :class:`!Coroutine` in type annotations. The variance and order of type parameters correspond to those of :class:`Generator`. @@ -353,7 +353,7 @@ Collections Abstract Base Classes -- Detailed Descriptions ABC for :term:`asynchronous generator` classes that implement the protocol defined in :pep:`525` and :pep:`492`. - Refer to :ref:`annotating-generators-and-coroutines` + See :ref:`annotating-generators-and-coroutines` for details on using :class:`!AsyncGenerator` in type annotations. .. versionadded:: 3.6 From e63c976a72cced7a5b00b47cf250b417e473ba28 Mon Sep 17 00:00:00 2001 From: STerliakov Date: Tue, 3 Sep 2024 22:35:24 +0200 Subject: [PATCH 18/18] Disambiguate `typing.Set` and `collections.abc.Set` --- Doc/library/typing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 347fd7b564b458..f8b533a5fc87aa 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -3425,7 +3425,7 @@ Aliases to built-in types Note that to annotate arguments, it is preferred to use an abstract collection type such as :class:`collections.abc.Set` - rather than to use :class:`set` or :class:`!typing.Set`. + rather than to use :class:`set` or :class:`typing.Set`. .. deprecated:: 3.9 :class:`builtins.set ` now supports subscripting (``[]``).