GH-85979: Clarify the vague specification of object.await #22320

plammens · 2020-09-19T14:00:30Z

Issue: Clarify specification of object.__await__ #85979

the-knights-who-say-ni · 2020-09-19T14:00:33Z

Hello, and thanks for your contribution!

I'm a bot set up to make sure that the project can legally accept this contribution by verifying everyone involved has signed the PSF contributor agreement (CLA).

CLA Missing

Our records indicate the following people have not signed the CLA:

@plammens

For legal reasons we need all the people listed to sign the CLA before we can look at your contribution. Please follow the steps outlined in the CPython devguide to rectify this issue.

If you have recently signed the CLA, please wait at least one business day
before our records are updated.

You can check yourself to see if the CLA has been received.

Thanks again for the contribution, we look forward to reviewing it!

plammens · 2020-11-03T14:47:50Z

The CI is failing on the Misc/NEWS.d check, is there any way I can add the skip news label myself?

asvetlov · 2020-11-04T16:11:56Z

@aeros could you please check the text?
It looks correct for me but I'm not a native speaker...

aeros

Thanks for the PR @plammens!

You're definitely right that the __await__ docs could use significant clarification, and I think the general direction of the content is correct. That being said, I have some suggestions (mix of technical, grammar, and reST).

Feedback on my technical suggestions from @asvetlov and @1st1 would be appreciated (even if it's just +1/-1); I think it's especially important to get this part of the documentation correct given the large scope that it applies to.

Doc/reference/datamodel.rst

bedevere-bot · 2020-11-09T04:25:02Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

Co-authored-by: Kyle Stanley <aeros167@gmail.com>

Doc/reference/datamodel.rst

plammens · 2020-11-10T17:01:17Z

I have made the requested changes; please review again.

bedevere-bot · 2020-11-10T17:01:21Z

Thanks for making the requested changes!

@aeros, @asvetlov: please review the changes made to this pull request.

graingert · 2022-09-24T14:19:36Z

Doc/reference/datamodel.rst

+      :term:`coroutines <coroutine>`, 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.


You're not supposed to use yield from fut anymore either - you should use await fut

graingert · 2022-09-24T14:24:21Z

Doc/reference/datamodel.rst

+      :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``)


I don't think the special case of await asyncio.sleep(0) via yield None should be documented here

graingert · 2022-09-24T14:30:19Z

I think here it makes most sense to have a very minimal comparative discussion of how other async frameworks handle this eg twisted and asyncio are very similar using a Future/Deferred callback/ trampoline pattern. curio and trio use an approach similar to kernel "traps" using

@types.coroutine
def _async_yield(v):
    return (yield v)

gvanrossum

@graingert Could you submit a comment with suggested text that would make you happy about this note and that I can just commit and land?

gvanrossum · 2022-09-27T23:29:33Z

Doc/reference/datamodel.rst

+      :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``)


gvanrossum · 2022-09-27T23:29:55Z

Doc/reference/datamodel.rst

+      :term:`coroutines <coroutine>`, 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.


gvanrossum · 2022-09-27T23:35:50Z

Doc/reference/datamodel.rst

+      In the case of :mod:`asyncio`, user code should generally be using
+      :term:`coroutines <coroutine>`, instances of :class:`asyncio.Task`,
+      :class:`asyncio.Future`, and other :mod:`asyncio` objects to implement


dask/distributed uses:

def __await__(self): async def _(): ... return _().__await__()

To implement Awaitable classes, it's not clear to me if that's an intended use case.

I think it is fine. It would seem reasonable that a given function's implementation can either return the desired result, or call another function that returns the desired result. And if async function are specified to have an __await__() method, that's what we are doing here.

Just like when you're implementing an iterator, you can either have a method __iter__() that creates and returns a custom object with a __next__() method, or you can have __iter__() be a generator function. Or you can construct some other thing and call its __iter__() method.

gvanrossum · 2022-09-27T23:44:36Z

Doc/reference/datamodel.rst

+      In the case of :mod:`asyncio`, user code should generally be using
+      :term:`coroutines <coroutine>`, instances of :class:`asyncio.Task`,
+      :class:`asyncio.Future`, and other :mod:`asyncio` objects to implement


This is also slightly inaccurate as asyncio should call return yield from type(aw).__await__(aw) or return await aw but actually calls return yield from aw.__await__()

I can't disagree, but is this fine point relevant to the docs at hand? We're trying to specify __await__ without referring to asyncio.

There's also exotic objects that are Awaitables but don't have an __await__ method. I think via c extensions

Can you point to an example? I'm guessing you're referring to extension types that have an tp_as_async->am_await slot but don't have a Python-visible __await__ callable?

graingert · 2022-09-28T08:54:37Z

@graingert Could you submit a comment with suggested text that would make you happy about this note and that I can just commit and land?

I'm currently still 99% offline I'll be available in a few weeks I think

needs to be re-reviewed

…-await

kumaraditya303

I removed asyncio implementation details from the note as IMO it is unnecessary.

kumaraditya303

LGTM

gvanrossum

Go for it!

miss-islington · 2022-12-31T06:24:29Z

Thanks @plammens for the PR, and @kumaraditya303 for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10.
🐍🍒⛏🤖

miss-islington · 2022-12-31T06:24:30Z

Thanks @plammens for the PR, and @kumaraditya303 for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11.
🐍🍒⛏🤖

bedevere-bot · 2022-12-31T06:24:50Z

GH-100635 is a backport of this pull request to the 3.11 branch.

bedevere-bot · 2022-12-31T06:24:54Z

GH-100636 is a backport of this pull request to the 3.10 branch.

…-22320) (cherry picked from commit f59c7f8) Co-authored-by: Paolo Lammens <lammenspaolo@gmail.com> Co-authored-by: Kumar Aditya <59607654+kumaraditya303@users.noreply.github.com>

(cherry picked from commit f59c7f8) Co-authored-by: Paolo Lammens <lammenspaolo@gmail.com> Co-authored-by: Kumar Aditya <59607654+kumaraditya303@users.noreply.github.com>

bpo-41813: Clarify the vague specification of object.__await__

cf317ce

the-knights-who-say-ni added the CLA not signed label Sep 19, 2020

bedevere-bot added docs Documentation in the Doc dir awaiting review labels Sep 19, 2020

csabella removed the CLA not signed label Sep 21, 2020

the-knights-who-say-ni added CLA not signed and removed CLA not signed labels Sep 21, 2020

plammens changed the title ~~bpo-41813: Clarify the vague specification of object.__await__~~ bpo-41813: Clarify the vague specification of object.__await__ [skip news] Nov 3, 2020

plammens changed the title ~~bpo-41813: Clarify the vague specification of object.__await__ [skip news]~~ bpo-41813: Clarify the vague specification of object.__await__ Nov 3, 2020

asvetlov added skip news topic-asyncio labels Nov 4, 2020

asvetlov approved these changes Nov 4, 2020

View reviewed changes

bedevere-bot added awaiting merge and removed awaiting review labels Nov 4, 2020

aeros self-requested a review November 8, 2020 23:32

aeros requested changes Nov 9, 2020

View reviewed changes

Doc/reference/datamodel.rst Outdated Show resolved Hide resolved

bedevere-bot removed the awaiting merge label Nov 9, 2020

bedevere-bot added the awaiting changes label Nov 9, 2020

bpo-41813: Commit suggestions from review

8d1409b

Co-authored-by: Kyle Stanley <aeros167@gmail.com>

plammens commented Nov 10, 2020

View reviewed changes

Doc/reference/datamodel.rst Outdated Show resolved Hide resolved

plammens commented Nov 10, 2020

View reviewed changes

Doc/reference/datamodel.rst Outdated Show resolved Hide resolved

bedevere-bot added awaiting change review and removed awaiting changes labels Nov 10, 2020

graingert reviewed Sep 24, 2022

View reviewed changes

gvanrossum reviewed Sep 27, 2022

View reviewed changes

gvanrossum changed the title ~~bpo-41813: Clarify the vague specification of object.__await__~~ GH-85979: Clarify the vague specification of object.__await__ Nov 28, 2022

kumaraditya303 unassigned asvetlov Dec 16, 2022

kumaraditya303 added 2 commits December 30, 2022 16:29

Merge branch 'main' of https://github.com/python/cpython into clarify…

eee83f7

…-await

remove asyncio details

9179381

kumaraditya303 reviewed Dec 30, 2022

View reviewed changes

kumaraditya303 requested review from gvanrossum and kumaraditya303 December 30, 2022 11:07

kumaraditya303 approved these changes Dec 30, 2022

View reviewed changes

gvanrossum approved these changes Dec 30, 2022

View reviewed changes

kumaraditya303 merged commit f59c7f8 into python:main Dec 31, 2022
15 checks passed

bedevere-bot removed the awaiting merge label Dec 31, 2022

kumaraditya303 added needs backport to 3.10 only security fixes needs backport to 3.11 bug and security fixes labels Dec 31, 2022

bedevere-bot removed the needs backport to 3.11 bug and security fixes label Dec 31, 2022

bedevere-bot removed the needs backport to 3.10 only security fixes label Dec 31, 2022

GH-85979: Clarify the vague specification of object.await #22320

GH-85979: Clarify the vague specification of object.await #22320

plammens commented Sep 19, 2020 •

edited by gvanrossum

the-knights-who-say-ni commented Sep 19, 2020

plammens commented Nov 3, 2020

asvetlov commented Nov 4, 2020

aeros left a comment

bedevere-bot commented Nov 9, 2020

plammens commented Nov 10, 2020

bedevere-bot commented Nov 10, 2020

graingert Sep 24, 2022

gvanrossum Sep 27, 2022

graingert Sep 24, 2022

gvanrossum Sep 27, 2022

graingert commented Sep 24, 2022

gvanrossum left a comment

gvanrossum Sep 27, 2022

gvanrossum Sep 27, 2022

gvanrossum Sep 27, 2022

gvanrossum Sep 27, 2022

graingert commented Sep 28, 2022

kumaraditya303 left a comment •

edited

kumaraditya303 left a comment

gvanrossum left a comment

miss-islington commented Dec 31, 2022

miss-islington commented Dec 31, 2022

bedevere-bot commented Dec 31, 2022

bedevere-bot commented Dec 31, 2022

GH-85979: Clarify the vague specification of object.__await__ #22320

GH-85979: Clarify the vague specification of object.__await__ #22320

Conversation

plammens commented Sep 19, 2020 • edited by gvanrossum

the-knights-who-say-ni commented Sep 19, 2020

CLA Missing

plammens commented Nov 3, 2020

asvetlov commented Nov 4, 2020

aeros left a comment

Choose a reason for hiding this comment

bedevere-bot commented Nov 9, 2020

plammens commented Nov 10, 2020

bedevere-bot commented Nov 10, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

graingert commented Sep 24, 2022

gvanrossum left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

graingert commented Sep 28, 2022

kumaraditya303 left a comment • edited

Choose a reason for hiding this comment

kumaraditya303 left a comment

Choose a reason for hiding this comment

gvanrossum left a comment

Choose a reason for hiding this comment

miss-islington commented Dec 31, 2022

miss-islington commented Dec 31, 2022

bedevere-bot commented Dec 31, 2022

bedevere-bot commented Dec 31, 2022

GH-85979: Clarify the vague specification of object.await #22320

GH-85979: Clarify the vague specification of object.await #22320

plammens commented Sep 19, 2020 •

edited by gvanrossum

kumaraditya303 left a comment •

edited