From cf317ce545397fa424bf4ecda8db513f8d2e2c73 Mon Sep 17 00:00:00 2001 From: Paolo Lammens Date: Sat, 19 Sep 2020 14:59:25 +0100 Subject: [PATCH 1/8] bpo-41813: Clarify the vague specification of object.__await__ --- Doc/reference/datamodel.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index a817408c3b1ef5..20be29e758d30e 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2616,6 +2616,17 @@ are awaitable. :term:`awaitable` objects. For instance, :class:`asyncio.Future` implements this method to be compatible with the :keyword:`await` expression. + .. note:: + + The language doesn't place any restriction on the type or value of the objects + yielded by the iterator returned by :meth:`__await__`, as this is specific to + the implementation of the event loop that will be managing the :term:`awaitable` + object. In the case of :mod:`asyncio`, user code should always be using other + :term:`coroutines `, :mod:`asyncio` Tasks, Futures, and other + :mod:`asyncio` objects to implement :meth:`__await__`, yielding objects from + these, and never yielding objects directly—as the kind of objects that the event + loop expects are considered a private implementation detail of :mod:`asyncio`. + .. versionadded:: 3.5 .. seealso:: :pep:`492` for additional information about awaitable objects. From 8d1409b4e86469eb4a8d5d44846702438af87f97 Mon Sep 17 00:00:00 2001 From: Paolo Lammens Date: Tue, 10 Nov 2020 16:42:26 +0000 Subject: [PATCH 2/8] bpo-41813: Commit suggestions from review Co-authored-by: Kyle Stanley --- Doc/reference/datamodel.rst | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 20be29e758d30e..e4ba33810ddd8e 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2618,14 +2618,20 @@ are awaitable. .. note:: - The language doesn't place any restriction on the type or value of the objects - yielded by the iterator returned by :meth:`__await__`, as this is specific to - the implementation of the event loop that will be managing the :term:`awaitable` - object. In the case of :mod:`asyncio`, user code should always be using other - :term:`coroutines `, :mod:`asyncio` Tasks, Futures, and other - :mod:`asyncio` objects to implement :meth:`__await__`, yielding objects from - these, and never yielding objects directly—as the kind of objects that the event - loop expects are considered a private implementation detail of :mod:`asyncio`. + The language doesn't place any restrictions on the type or value of the + objects yielded by the iterator returned by `__await__`, as this is + specific to the implementation of the async framework that will be + managing the :term:`awaitable` object. + + In the case of :mod:`asyncio`, user code should generally be using + :term:`coroutines `, instances of :class:`asyncio.Task`, + :class:`asyncio.Future`, and other :mod:`asyncio` objects to implement + `__await__`; yielding objects from these (e.g. + `return (yield from future)`), rather than yielding objects directly. + An exception to this is a bare `yield` within an `__await__`, which can + be used to suspend execution until the next iteration of the event loop. + The type of objects that the event loop expects are considered a + private implementation detail of :mod:`asyncio`. .. versionadded:: 3.5 From 15e1c3f126430b76d0f9cb88547a7c41615c4452 Mon Sep 17 00:00:00 2001 From: Andrew Svetlov Date: Wed, 11 Nov 2020 12:51:36 +0200 Subject: [PATCH 3/8] Update Doc/reference/datamodel.rst Co-authored-by: Paolo Lammens --- Doc/reference/datamodel.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index e4ba33810ddd8e..e3f6003f97d393 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2620,8 +2620,8 @@ are awaitable. The language doesn't place any restrictions on the type or value of the objects yielded by the iterator returned by `__await__`, as this is - specific to the implementation of the async framework that will be - managing the :term:`awaitable` object. + specific to the implementation of the asynchronous execution framework + (e.g. :mod:`asyncio`) that will be managing the :term:`awaitable` object. In the case of :mod:`asyncio`, user code should generally be using :term:`coroutines `, instances of :class:`asyncio.Task`, From 680aa18e95c90d0419b5198ea6fcae9568366f60 Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Sat, 14 Nov 2020 23:26:52 -0500 Subject: [PATCH 4/8] Update Doc/reference/datamodel.rst * Restructure "bare yield" sentence --- Doc/reference/datamodel.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index e3f6003f97d393..e65d55ff1bdc60 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2628,8 +2628,9 @@ are awaitable. :class:`asyncio.Future`, and other :mod:`asyncio` objects to implement `__await__`; yielding objects from these (e.g. `return (yield from future)`), rather than yielding objects directly. - An exception to this is a bare `yield` within an `__await__`, which can - be used to suspend execution until the next iteration of the event loop. + An exception to this is a `yield None` (or equivalent bare `yield`) + within an `__await__`, which can be used to suspend execution until the + next iteration of the event loop. The type of objects that the event loop expects are considered a private implementation detail of :mod:`asyncio`. From 55fa24e730b06fdcdb64ecd2115541fcca8ae9cc Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Sat, 14 Nov 2020 23:30:04 -0500 Subject: [PATCH 5/8] Update Doc/reference/datamodel.rst * Fix line width --- Doc/reference/datamodel.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index e65d55ff1bdc60..964687204cdf42 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2630,9 +2630,8 @@ are awaitable. `return (yield from future)`), rather than yielding objects directly. An exception to this is a `yield None` (or equivalent bare `yield`) within an `__await__`, which can be used to suspend execution until the - next iteration of the event loop. - The type of objects that the event loop expects are considered a - private implementation detail of :mod:`asyncio`. + next iteration of the event loop. The type of objects that the event loop + expects are considered a private implementation detail of :mod:`asyncio`. .. versionadded:: 3.5 From be218ad8fb93115e1b2b98a7bbdc1f37cf024ff8 Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Sat, 14 Nov 2020 23:40:41 -0500 Subject: [PATCH 6/8] Remove trailing whitespace --- Doc/reference/datamodel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 964687204cdf42..c02871bbe30e11 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2622,7 +2622,7 @@ are awaitable. objects yielded by the iterator returned by `__await__`, as this is specific to the implementation of the asynchronous execution framework (e.g. :mod:`asyncio`) that will be managing the :term:`awaitable` object. - + In the case of :mod:`asyncio`, user code should generally be using :term:`coroutines `, instances of :class:`asyncio.Task`, :class:`asyncio.Future`, and other :mod:`asyncio` objects to implement From cb7c9dbf56f4867c55e39a9a27a611a3289953c1 Mon Sep 17 00:00:00 2001 From: Paolo Lammens Date: Wed, 18 Nov 2020 20:09:15 +0100 Subject: [PATCH 7/8] fix: Use correct reST syntax for inline code --- Doc/reference/datamodel.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index c02871bbe30e11..b0c1be670ddcee 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2619,17 +2619,17 @@ are awaitable. .. note:: The language doesn't place any restrictions on the type or value of the - objects yielded by the iterator returned by `__await__`, as this is + objects yielded by the iterator returned by ``__await__``, as this is specific to the implementation of the asynchronous execution framework (e.g. :mod:`asyncio`) that will be managing the :term:`awaitable` object. In the case of :mod:`asyncio`, user code should generally be using :term:`coroutines `, instances of :class:`asyncio.Task`, :class:`asyncio.Future`, and other :mod:`asyncio` objects to implement - `__await__`; yielding objects from these (e.g. - `return (yield from future)`), rather than yielding objects directly. - An exception to this is a `yield None` (or equivalent bare `yield`) - within an `__await__`, which can be used to suspend execution until the + ``__await__``; yielding objects from these (e.g. + ``return (yield from future)``), rather than yielding objects directly. + An exception to this is a ``yield None`` (or equivalent bare ``yield``) + within an ``__await__``, which can be used to suspend execution until the next iteration of the event loop. The type of objects that the event loop expects are considered a private implementation detail of :mod:`asyncio`. From 9179381d7ce8ee0b9fa9441ff6f4975759198552 Mon Sep 17 00:00:00 2001 From: Kumar Aditya <59607654+kumaraditya303@users.noreply.github.com> Date: Fri, 30 Dec 2022 16:31:33 +0530 Subject: [PATCH 8/8] remove asyncio details --- Doc/reference/datamodel.rst | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index e769af4530e996..1d2ddf3507aee1 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2952,20 +2952,11 @@ are awaitable. .. note:: - The language doesn't place any restrictions on the type or value of the + The language doesn't place any restriction on the type or value of the objects yielded by the iterator returned by ``__await__``, as this is specific to the implementation of the asynchronous execution framework (e.g. :mod:`asyncio`) that will be managing the :term:`awaitable` object. - In the case of :mod:`asyncio`, user code should generally be using - :term:`coroutines `, instances of :class:`asyncio.Task`, - :class:`asyncio.Future`, and other :mod:`asyncio` objects to implement - ``__await__``; yielding objects from these (e.g. - ``return (yield from future)``), rather than yielding objects directly. - An exception to this is a ``yield None`` (or equivalent bare ``yield``) - within an ``__await__``, which can be used to suspend execution until the - next iteration of the event loop. The type of objects that the event loop - expects are considered a private implementation detail of :mod:`asyncio`. .. versionadded:: 3.5