ABSTRACT
I propose that every asyncio function that is a coroutine gets a
highly visible marker at the top of its entry in the documentation.
For example the entry for StreamWriter.drain() [1] should read:
drain() -> {{coroutine}}
Let the write buffer of the underlying transport ...
This is more visible than a sentence like "This method is a
coroutine." buried somewhere in its description.
The notation "-> {{coroutine}}" is just a stand-in for now. The main
point is having some visible indicator that can be found without
scanning the entire entry. The notation should be used in addition to
the mention "This method is a coroutine." in the body of the function
documentation.
[1]
https://docs.python.org/3/library/asyncio-stream.html#asyncio.StreamWriter.drain
PROPOSAL RATIONALE
A big gotcha for users of asyncio is knowing which API functions are
coroutines and which aren't. For example, StreamWriter.write isn't,
but StreamWriter.drain is.
If you are one of the designers or implementers of asyncio this may be
obvious, but for the rest of us it's not.
Apparently David Beazley got bitten by this. Take a look at slide 102
titled "Be on the lookout!" in his tutorial "Generators, the Final
Frontier" presented at PyCon 2014 [2]
[2] http://www.dabeaz.com/finalgenerator/FinalGenerator.pdf
The asyncio docs provide this information, usually with the phrase
"This method is a coroutine." near the end of the description of the
function. Other phrases are used, and they don't appear always at the
end of the entry. But they never appear right at the beginning.
When the description is long, that's easy to look over. See
BaseEventLoop.create_connection [3]. BaseEventLoop.create_server [4].
[3]
https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.BaseEventLoop.create_connection
[4]
https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.BaseEventLoop.create_server
It would be very helpful to asyncio users if the crucial distinction
between coroutines and regular functions was made right at the start
of each entry in the API docs.
PROPOSAL IMPLEMENTATION
The easiest thing to do right away would be to add a formula like
{{coroutine}} as the first word in the first paragraph of the
description for each function. The actual formula must be decided. The
sentence "This method is a coroutine." could be used for this. The
main point is to make it the first thing in the description of the
method.
Ideally the notation should not be embedded in the text, but appear
besides the function name, for example:
drain() -> {{coroutine}}
Let the write buffer of the underlying transport ...
If some abbreviated notation like {{coroutine}} is adopted, the phrase
"This method is a coroutine." should be kept in the description for
clarity.
What do you think? I am willing to file a bug and provide a patch if
you think this is worthwhile.
Best,
Luciano
--
Luciano Ramalho
Twitter: @ramalhoorg
Professor em: http://python.pro.br
Twitter: @pythonprobr
