This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: yield expression confusion
Type: enhancement Stage:
Components: asyncio, Documentation Versions:
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Jim.Jewett, docs@python, gvanrossum, python-dev, r.david.murray, vstinner, yselivanov
Priority: normal Keywords:

Created on 2015-04-30 22:03 by Jim.Jewett, last changed 2022-04-11 14:58 by admin. This issue is now closed.

Messages (7)
msg242289 - (view) Author: Jim Jewett (Jim.Jewett) * (Python triager) Date: 2015-04-30 22:03
https://docs.python.org/3/reference/expressions.html#yield-expressions

Current:
"""
When a generator function is called, it returns an iterator known as a generator. That generator then controls the execution of a generator function. The execution starts when one of the generator’s methods is called.
"""

At a minimum, that seems to be using "generator function" in two different ways, but I think there are other problems.

Proposed:
"""
When a generator function is called, it returns a special kind of iterator known as a generator. The iteration starts when one of the generator’s methods is called.
"""
msg242290 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2015-04-30 22:24
You can't just drop the middle sentence. Awkward though it is, it is attempting to describe that the generator object controls suspension and resumption of the stack frame representing execution of the generator function's body.
msg242369 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-05-02 02:15
Yes, and it is not using generator function in two different ways: it is literally the case that calling the generator function returns a generator object, which in turn controls the execution of the generator function.  The text then goes on to explain how this works.

I think it would make sense to change "controls execution of a generator function" to "controls execution of the generator function", but I can't think of any other change that would make things clearer.
msg242559 - (view) Author: Jim Jewett (Jim.Jewett) * (Python triager) Date: 2015-05-04 14:10
OK, then how about

Current:
"""
When a generator function is called, it returns an iterator known as a generator. That generator then controls the execution of a generator function. The execution starts when one of the generator’s methods is called.
"""

Proposed:
"""
When a generator function is called, it does not complete its execution immediately.  Instead, it keeps its execution frame intact, and returns a special kind of iterator known as a generator. The iteration starts when one of the generator’s methods is called, and the generator executes within the existing generator frame, rather than creating a new one.
"""

This still seems to suggest that the generator uses the same frame as the generator function that created it; I was not aware that this was a guarantee.  (Reusing the same frame, yes.  Reusing that particular frame, no.)
msg242561 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-05-04 14:22
I don't think anything about frames is guaranteed as part of the language, so I'm not sure that mention of it belongs in the description.  Personally, I find your reformulation more confusing that the original with 'a' replaced by 'the'.
msg242609 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-05-05 19:03
New changeset b87d96e0708e by Guido van Rossum in branch '3.4':
Issue 24088: Clarify semantics of yield expression.
https://hg.python.org/cpython/rev/b87d96e0708e
msg242610 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-05-05 19:04
New changeset 6e59d82d3d09 by Guido van Rossum in branch 'default':
Issue 24088: Clarify semantics of yield expression (merge from 3.4).
https://hg.python.org/cpython/rev/6e59d82d3d09
History
Date User Action Args
2022-04-11 14:58:16adminsetgithub: 68276
2015-05-05 19:04:56gvanrossumsetstatus: open -> closed
resolution: fixed
2015-05-05 19:04:43python-devsetmessages: + msg242610
2015-05-05 19:03:50python-devsetnosy: + python-dev
messages: + msg242609
2015-05-04 14:22:31r.david.murraysetmessages: + msg242561
2015-05-04 14:10:50Jim.Jewettsetmessages: + msg242559
2015-05-02 02:15:04r.david.murraysetnosy: + r.david.murray
messages: + msg242369
2015-04-30 22:24:28gvanrossumsetmessages: + msg242290
2015-04-30 22:03:21Jim.Jewettcreate