Title: Clarify specification of object.__await__
Type: Stage: patch review
Components: asyncio, Documentation Versions:
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: asvetlov, docs@python, plammens, yselivanov
Priority: normal Keywords: patch

Created on 2020-09-19 13:57 by plammens, last changed 2020-09-25 23:06 by terry.reedy.

Pull Requests
URL Status Linked Edit
PR 22320 open plammens, 2020-09-19 14:00
Messages (2)
msg377166 - (view) Author: Paolo Lammens (plammens) * Date: 2020-09-19 13:57
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:
msg377168 - (view) Author: Paolo Lammens (plammens) * Date: 2020-09-19 15:27
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`.
Date User Action Args
2020-09-25 23:06:30terry.reedysetnosy: + yselivanov, asvetlov
components: + asyncio
2020-09-19 15:27:49plammenssetmessages: + msg377168
2020-09-19 14:00:31plammenssetkeywords: + patch
stage: patch review
pull_requests: + pull_request21365
2020-09-19 13:57:34plammenscreate