[New-bugs-announce] [issue24439] Feedback for awaitable coroutine documentation

[Martin Panter]

New submission from Martin Panter:

Today I tried playing with the new “async def” functionality in the interactive interpreter, based on reading the documentation. Here are some bits that surprised me, so could be the focus of further documentation. (Initial documentation added in Issue 24180.)

1. Confusion between coroutine and generator terms

<coroutine object f at 0x7f9a5ae45200>
AttributeError: 'generator' object has no attribute '__await__'
<class 'generator'>
TypeError: coroutine-objects do not support iteration
TypeError: can't send non-None value to a just-started generator

Is it a coroutine object, or a generator object? The error messages etc seem to be split between the two terms. I guess the underlying implementation is closely shared between the two types, so old error messages still say “generator”, while new ones say “coroutine”. So there may not be an easy fix, but it was initially disconcerting. Perhaps a statement somewhere explaining coroutine instances are (based on / modified / a kind of / evolved from) generator instance objects, as appropriate.

2. Properties of a coroutine instance object

<https://docs.python.org/dev/reference/datamodel.html#awaitable-objects> suggests that a coroutine instance should implement __await__(), but it apparently does not.

How to drive through the coroutine’s await points? This should be documented, and linked from relevant places in the documentation; perhaps the “coroutine” glossary entry, “async” statement, and “await” expression. The best clue that I found in the current documentation was <https://docs.python.org/dev/library/collections.abc.html#collections.abc.Coroutine>, suggesting to use send().

Without having studied the PEP recently, I was expecting __await__() to be implemented, and invoking it would be similar to calling next() on an old-skool generator-iterator. Instead I see that calling __await__() is semantically more like __iter__(): it is only invoked once per “await” expression, and the return value is iterated over.

3. Allergic reaction to “await” on the same line as “async def”

>>> async def f(): await A(())
SyntaxError: invalid syntax

I see this is mentioned in the PEP that this is necessary so that “await” doesn’t have to be made a strict language keyword. But it should also be in the documentation.

4. Coroutine instances don’t implement the Coroutine ABC

>>> isinstance(c, Coroutine)
True
>>> hasattr(Coroutine, "__await__")
True
>>> hasattr(c, "__await__")
False

Reading closely, the documentation says “coroutine compatible classes”, but given the liberal use of “coroutine” everywhere, I think there should be a more obvious warning of how much a coroutine is a Coroutine.

----------
assignee: docs at python
components: Documentation
messages: 245256
nosy: docs at python, vadmium, yselivanov
priority: normal
severity: normal
status: open
title: Feedback for awaitable coroutine documentation
type: enhancement
versions: Python 3.5, Python 3.6

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue24439>
_______________________________________