Documentation for coroutine objects

[61a746e0-56f6-4f74-bbde-a98c5612db23]

BPO	34518
Nosy	@hniksic, @1st1, @tirkarthi

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields: ```python assignee = None closed_at = None created_at = labels = ['3.7', 'docs'] title = 'Documentation for coroutine objects' updated_at = user = 'https://github.com/hniksic' ``` bugs.python.org fields: ```python activity = actor = 'xtreak' assignee = 'docs@python' closed = False closed_date = None closer = None components = ['Documentation'] creation = creator = 'hniksic' dependencies = [] files = [] hgrepos = [] issue_num = 34518 keywords = [] message_count = 4.0 messages = ['324157', '324171', '324173', '325627'] nosy_count = 4.0 nosy_names = ['hniksic', 'docs@python', 'yselivanov', 'xtreak'] pr_nums = [] priority = 'normal' resolution = None stage = None status = 'open' superseder = None type = None url = 'https://bugs.python.org/issue34518' versions = ['Python 3.7'] ```

[61a746e0-56f6-4f74-bbde-a98c5612db23]

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

[tirkarthi]

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

[61a746e0-56f6-4f74-bbde-a98c5612db23]

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

[tirkarthi]

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