[docs] Feedback for awaitable coroutine documentation (issue 24439)

yselivanov at gmail.com yselivanov at gmail.com
Tue Jun 23 18:51:10 CEST 2015


Martin,

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.


http://bugs.python.org/review/24439/diff/15143/Doc/glossary.rst
File Doc/glossary.rst (right):

http://bugs.python.org/review/24439/diff/15143/Doc/glossary.rst#newcode181
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
"native" terminology.

http://bugs.python.org/review/24439/diff/15143/Doc/library/asyncio-task.rst
File Doc/library/asyncio-task.rst (right):

http://bugs.python.org/review/24439/diff/15143/Doc/library/asyncio-task.rst#newcode16
Doc/library/asyncio-task.rst:16: :func:`@asyncio.coroutine
<asyncio.coroutine>`.  This is mainly
"Documentation purposes" is one thing.

Another is compatibility with native coroutines.  If you have a
coroutine:

  def foo():
    yield from o

and a native coroutine bar:

   async def bar():
     await foo()

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.

http://bugs.python.org/review/24439/diff/15143/Doc/library/asyncio-task.rst#newcode70
Doc/library/asyncio-task.rst:70: the generator to call native
coroutines.
Let's also explicitly state that there is no need to decorate 'async
def' functions.

http://bugs.python.org/review/24439/diff/15143/Doc/library/asyncio-task.rst#newcode94
Doc/library/asyncio-task.rst:94: async def hello_world():
I think we should leave one example of generator based coroutines...

http://bugs.python.org/review/24439/diff/15143/Doc/library/collections.abc.rst
File Doc/library/collections.abc.rst (right):

http://bugs.python.org/review/24439/diff/15143/Doc/library/collections.abc.rst#newcode169
Doc/library/collections.abc.rst:169: the generator methods defined in
:pep:`342`, namely:
Since we now have a dedicated section for coroutines in datamodel.rst we
need to update these refs to "coroutine.send" etc.

http://bugs.python.org/review/24439/diff/15143/Doc/library/dis.rst
File Doc/library/dis.rst (right):

http://bugs.python.org/review/24439/diff/15143/Doc/library/dis.rst#newcode525
Doc/library/dis.rst:525: one derived from :func:`types.coroutine`, or
resolves
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 [...]

http://bugs.python.org/review/24439/diff/15143/Doc/library/types.rst
File Doc/library/types.rst (right):

http://bugs.python.org/review/24439/diff/15143/Doc/library/types.rst#newcode293
Doc/library/types.rst:293: it may not necessarily implement the
:meth:`__await__` method.
Please take a look at my other patch:
http://bugs.python.org/review/24325/patch/15133/57450

Ideally we should combine the two

http://bugs.python.org/review/24439/diff/15143/Doc/reference/datamodel.rst
File Doc/reference/datamodel.rst (right):

http://bugs.python.org/review/24439/diff/15143/Doc/reference/datamodel.rst#newcode2278
Doc/reference/datamodel.rst:2278: Native :term:`coroutine` objects are
awaitable.  The :term:`generator
Let's wrap "The :term:`generator [..]" in a ".. note::" section?

http://bugs.python.org/review/24439/diff/15143/Doc/reference/datamodel.rst#newcode2296
Doc/reference/datamodel.rst:2296: Native Coroutine Objects
Again, I'd prefer to drop "Native"

http://bugs.python.org/review/24439/diff/15143/Objects/genobject.c
File Objects/genobject.c (right):

http://bugs.python.org/review/24439/diff/15143/Objects/genobject.c#newcode913
Objects/genobject.c:913: {"close",(PyCFunction)coro_wrapper_close,
METH_NOARGS, coro_close_doc},
Please rebase your patch -- this code was updated in 24400.

http://bugs.python.org/review/24439/


More information about the docs mailing list