[docs] Feedback for awaitable coroutine documentation (issue 24439)
yselivanov at gmail.com
yselivanov at gmail.com
Tue Jun 23 18:51:10 CEST 2015
Thanks for the update!
My main concern with this version is about introducing the "native
coroutine" terminology. While it was a necessary thing to do in PEP
492, I really doubt that we should use it in Python docs.
File Doc/glossary.rst (right):
Doc/glossary.rst:181: coroutine function` is defined with the
:keyword:`async def` statement,
Martin, I'm not sure we should use the "native coroutine" term. I'd
really prefer to just use "coroutine" for "async def"/"await" objects,
and "generator-based coroutine" for "yield & yield from" ones.
99% of people don't use generators as coroutines (at least directly).
Some Python users know that generators can be coroutines, but that's
mostly those who use asyncio/twisted/tornado frameworks. In asyncio we
have a "coroutine" decorator, that in a sense, "converts" a generator
into a coroutine.
Hopefully, in the near future, Python users won't use generators as
coroutines, and I don't want them to be confused why we have the
File Doc/library/asyncio-task.rst (right):
<asyncio.coroutine>`. This is mainly
"Documentation purposes" is one thing.
Another is compatibility with native coroutines. If you have a
yield from o
and a native coroutine bar:
async def bar():
Then you have to decorate 'foo' with "asyncio.coroutine". Otherwise it's
not going to work.
I'd say that it's encouraged to use the decorator on generator-based
coroutine functions for documentation purposes *and* for compatibility
with PEP 492 coroutines.
Doc/library/asyncio-task.rst:70: the generator to call native
Let's also explicitly state that there is no need to decorate 'async
Doc/library/asyncio-task.rst:94: async def hello_world():
I think we should leave one example of generator based coroutines...
File Doc/library/collections.abc.rst (right):
Doc/library/collections.abc.rst:169: the generator methods defined in
Since we now have a dedicated section for coroutines in datamodel.rst we
need to update these refs to "coroutine.send" etc.
File Doc/library/dis.rst (right):
Doc/library/dis.rst:525: one derived from :func:`types.coroutine`, or
This isn't right too. types.coroutine either patches the generator
function's code object, or wraps it in a special object with __await__.
Since this is a pretty low level documentation, let's just rephrase it
to something like this:
[...] returns ``o`` if ``o`` is a native coroutine object or a generator
object with CO_ITERABLE_COROUTINE flag, or resolves [...]
File Doc/library/types.rst (right):
Doc/library/types.rst:293: it may not necessarily implement the
Please take a look at my other patch:
Ideally we should combine the two
File Doc/reference/datamodel.rst (right):
Doc/reference/datamodel.rst:2278: Native :term:`coroutine` objects are
awaitable. The :term:`generator
Let's wrap "The :term:`generator [..]" in a ".. note::" section?
Doc/reference/datamodel.rst:2296: Native Coroutine Objects
Again, I'd prefer to drop "Native"
File Objects/genobject.c (right):
Please rebase your patch -- this code was updated in 24400.
More information about the docs