Clarify specification of object.__await__

[plammens]

BPO	41813
Nosy	@asvetlov, @1st1, @plammens
PRs	GH-85979: Clarify the vague specification of object.__await__ #22320

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2020-09-19.13:57:34.848>
labels = ['docs', 'expert-asyncio']
title = 'Clarify specification of object.__await__'
updated_at = <Date 2020-09-25.23:06:30.547>
user = 'https://github.com/plammens'

bugs.python.org fields:

activity = <Date 2020-09-25.23:06:30.547>
actor = 'terry.reedy'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'asyncio']
creation = <Date 2020-09-19.13:57:34.848>
creator = 'plammens'
dependencies = []
files = []
hgrepos = []
issue_num = 41813
keywords = ['patch']
message_count = 2.0
messages = ['377166', '377168']
nosy_count = 4.0
nosy_names = ['asvetlov', 'docs@python', 'yselivanov', 'plammens']
pr_nums = ['22320']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue41813'
versions = []

Linked PRs

• [3.11] GH-85979: Clarify specification of object.__await__ (GH-22320) #100635
• [3.10] GH-85979: Clarify specification of object.__await__ (GH-22320) #100636

[plammens]

The current specification of object.__await__ is just:

object.__await__(self)

Must return an iterator. Should be used to implement awaitable objects. For instance, asyncio.Future implements this method to be compatible with the await expression.

This is pretty vague leaves the doubt of *what* objects is the iterator expected to yield (and how the value of the yielded object affects the management of the awaitable object).

Although the vagueness is probably on purpose (since this isn't tied to any particular event loop implementation, so it can be an arbitrary iterable), I think it's worthwhile adding a note clarifying this aspect.

I originally posed this question on StackOverflow: https://stackoverflow.com/q/63964011/6117426

[plammens]

The proposed addition (see attached PR) is the following note:

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