classification
Title: Documentation doesn't explain the term "coroutine" (PEP 342)
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: cheryl.sabella, docs@python, gvanrossum, martin.panter, paul.moore
Priority: normal Keywords: needs review, patch

Created on 2015-04-30 20:25 by paul.moore, last changed 2019-02-08 13:54 by paul.moore. This issue is now closed.

Files
File name Uploaded Description Edit
coroutine_docs.patch paul.moore, 2015-04-30 20:25 review
coroutine_docs.v2.patch martin.panter, 2015-06-14 12:46 review
Messages (7)
msg242286 - (view) Author: Paul Moore (paul.moore) * (Python committer) Date: 2015-04-30 20:25
Although the new generator methods introduced in PEP 342 are documented, the term "coroutine" is not defined anywhere. In particular, the fact that Python coroutines work in conjunction with an event loop rather than transferring control directly between each other is not mentioned.
msg245254 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-06-12 14:04
I suspect the patch is out of date due to PEP 492 and Issue 24180 (“await” syntax for coroutines). But maybe the current glossary entry could be refined to also mention generators.
msg245342 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-06-14 12:46
Here is a new patch:

* Clarified some recent instances of “coroutine” as “native coroutine” (term taken from PEP 492)
* Put “coroutine” before “coroutine function” in the glossary.
* Merge “Use as coroutines” section into new coroutine compound statement documentation
* Add links to glossary entry
* Added one mention of the new “async” coroutines to “asyncio”. I understand this is meant to be supported in 3.5, but still needs more documentation work.
msg245378 - (view) Author: Paul Moore (paul.moore) * (Python committer) Date: 2015-06-15 14:47
Personally, I'm OK with the wording in the 3.5.0b2 docs, as far as basic terminology and glossary-style information goes.

I think coroutines, async, and event loops are badly under-documented in the broader context, though - there is very little in the docs explaining the concepts and constraints[1] of Python's async features. Unfortunately, the people with the knowledge of the subject are likely to be too close to the details to be able to write beginner-level documentation, and beginners don't know enough (by definition) to do so. I'm trying to do some playing round with creating my own async framework to get a better understanding of how things should work, but it's slow going and honestly I don't feel I've got anything much I could write up at this point.

[1] For example, how Python's implementation differs from other languages or "theoretical" discussions of coroutines in the literature.
msg245413 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-06-15 23:39
Okay. The biggest thing that concerns me at the moment to do with the term is that there are too many related but different, specific meanings, that I suspect could be confusing, including:

1. Generators (and presumably also the new “async” native coroutines), compatible with “asyncio”: <https://docs.python.org/3.5/library/asyncio-task.html#coroutines>

2. PEP 492 “native” coroutines: <https://docs.python.org/3.5/glossary.html#term-coroutine-function>

Okay maybe some of the new wording is not needed any more. I plan to try documenting some basic stuff about the new PEP 492 coroutines in Issue 24439. Maybe I will incorporate the “native coroutine” clarifications from my patch here at the same time.
msg335079 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2019-02-08 13:22
While some of the proposed changes in this issue have been applied to the documentation under other issues, other changes have not been applied.  Is it still desirable to incorporate the other changes (such as native coroutine) or have the existing doc changes been enough to make this issue obsolete?

Thank you.
msg335082 - (view) Author: Paul Moore (paul.moore) * (Python committer) Date: 2019-02-08 13:54
I'm OK that the basic glossary item is now covered. I don't know about any of the other issues Martin mentioned.

I've closed the issue as my original comment is addressed, but if Martin wants to reopen it to address his concerns, I'm OK with him doing that.
History
Date User Action Args
2019-02-08 13:54:26paul.mooresetstatus: open -> closed
resolution: fixed
messages: + msg335082

stage: patch review -> resolved
2019-02-08 13:22:05cheryl.sabellasetnosy: + cheryl.sabella
messages: + msg335079
2015-06-15 23:39:48martin.pantersetmessages: + msg245413
2015-06-15 14:47:29paul.mooresetmessages: + msg245378
2015-06-14 12:46:39martin.pantersetfiles: + coroutine_docs.v2.patch

messages: + msg245342
versions: + Python 3.6
2015-06-12 14:04:26martin.pantersetnosy: + martin.panter
messages: + msg245254
2015-04-30 20:25:52paul.moorecreate