classification
Title: Documentation for coroutine objects
Type: Stage:
Components: Documentation Versions: Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, hniksic, xtreak, yselivanov
Priority: normal Keywords:

Created on 2018-08-27 08:44 by hniksic, last changed 2018-09-18 10:37 by xtreak.

Messages (4)
msg324157 - (view) Author: Hrvoje Nikšić (hniksic) * Date: 2018-08-27 08:44
Coroutine objects have public methods such as send, close, and throw, which do not appear to be documented. For example, at https://stackoverflow.com/q/51975658/1600898 a StackOverflow user asks how to abort an already created (but not submitted) coroutine without a RuntimeWarning, with the answer being to use the close() method. The user asked where does one find the close method.

Currently methods only appear to be documented in PEP 492, referring to generator documentation for details. The glossary entry for coroutine (object) links to PEP 492 and to the async def statement. Various places in the documentation, e.g. the index, link to https://docs.python.org/3/library/asyncio-task.html#coroutine but that page is mostly concerned with the usage of coroutines within asyncio, where the methods on individual coroutine objects should not be used.

I would expect to find documentation on coroutine objects under built-in types, https://docs.python.org/3/library/stdtypes.html .

In comparison, generator-iterator methods are documented in the language reference:

https://docs.python.org/3/reference/expressions.html#generator-iterator-methods
msg324171 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python triager) Date: 2018-08-27 13:06
Is this what you are referring to that has docs for send, close and throw in coroutine objects ? 
Coroutine object docs : https://docs.python.org/3/reference/datamodel.html#coroutine-objects

If the above is the one then I think we can improve on the visibility by linking it from other pages since it doesn't show up with Google for 'coroutine close'. I had to use Docs folder in source code and sphinx search in docs.python.org with 'coroutine close' to get there.

Thanks
msg324173 - (view) Author: Hrvoje Nikšić (hniksic) * Date: 2018-08-27 13:22
That's exactly it, thanks! I have no idea how I missed it, despite looking (I thought) carefully.

But yes, they should be linked from https://docs.python.org/3/library/stdtypes.html . Just as currently there is https://docs.python.org/3/library/stdtypes.html#generator-types that links to https://docs.python.org/3/reference/expressions.html#yieldexpr , there could be a #coroutine-types that links to https://docs.python.org/3/reference/datamodel.html#coroutine-objects

Another place to link is https://docs.python.org/3/glossary.html#term-coroutine - it currently does link to the reference, but only to the "async def" syntax.

Since https://docs.python.org/3/reference/compound_stmts.html#async-def is linked from many places, it might make sense to mention that *calling* a coroutine immediately returns a coroutine object, with a link to https://docs.python.org/3/reference/datamodel.html#coroutine-objects
msg325627 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python triager) Date: 2018-09-18 10:37
Since there is work on asyncio docs overhaul I just want to bring this to your attention since I don't know if this has already been resolved with the merged PRs to master and your thoughts on this.

Thanks
History
Date User Action Args
2018-09-18 10:37:01xtreaksetnosy: + yselivanov
messages: + msg325627
2018-08-27 13:22:24hniksicsetmessages: + msg324173
2018-08-27 13:06:53xtreaksetmessages: + msg324171
2018-08-27 12:58:06xtreaksetnosy: + xtreak
2018-08-27 08:44:48hniksiccreate