Thank you Victor for your reactivity, it's ok for me. Ludovic Gasc (GMLudo) On 12 Feb 2015 23:00, "Victor Stinner" <[email protected]> wrote:
> Hi, > > I added :py:coroutinefunction: and :py:coroutinemethod: commands in > the pyspecifics.py extensions of CPython documentation. I modified the > asyncio documentation to annotate all coroutines. > > Changeset: > https://hg.python.org/cpython/rev/430a2b541709 > > The HTML doc will be regenerated in one hour: > > https://docs.python.org/dev/library/asyncio-eventloop.html#creating-connections > > Tell me if it's better. > > I checked all asyncio functions/methods using "yield from" have the > @coroutine method. I found some missing decorators, see the issue: > http://bugs.python.org/issue23456 > > Then I checked that all public functions/methods with the @coroutine > decorator are correctly annotated in the documentation. > > Victor > > 2015-02-12 12:51 GMT+01:00 Luciano Ramalho <[email protected]>: > > 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 >
