[issue12704] Language References does not specify exception raised by final yield()
New submission from Nikolaus Rath <Nikolaus@rath.org>:
From http://docs.python.org/reference/simple_stmts.html#the-yield-statement:
"As of Python version 2.5, the yield statement is now allowed in the try clause of a try ... finally construct. If the generator is not resumed before it is finalized (by reaching a zero reference count or by being garbage collected), the generator-iterator’s close() method will be called, allowing any pending finally clauses to execute." This strongly suggests that the last-executed yield statement will raise an exception if the generator is closed. If this is the case, it would be great if the documentation could be extended to say what exception is raised. If this is not the case, it would be great if whatever magic is happening could be documented as well. ---------- assignee: docs@python components: Documentation messages: 141724 nosy: Nikratio, docs@python priority: normal severity: normal status: open title: Language References does not specify exception raised by final yield() type: feature request versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________
Nikolaus Rath <Nikolaus@rath.org> added the comment:
From http://www.python.org/dev/peps/pep-0342/ I believe that the last yield will raise GeneratorExit. So my suggestion is to replace the above mentioned paragraph with:
""" As of Python version 2.5, yield is an expression rather than a statement and allowed in the try clause of a try ... finally construct. If the generator is not resumed before it is finalized (by reaching a zero reference count or by being garbage collected), the generator-iterator’s close() method will be called, and the yield expression in the generator function will raise GeneratorExit. If the generator function raises GeneratorExit (either directly or by not catching it), future calls to the next() method of the generator iterator will raise StopIteration. GeneratorExit exceptions raised by the generator function are catched internally and do not result in a call to sys.excepthook. """ ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________
Changes by Nikolaus Rath <Nikolaus@rath.org>: ---------- versions: +Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________
Nikolaus Rath <Nikolaus@rath.org> added the comment: Hmm. Does the total lack responses mean agreement, disagreement or lack of interest? I'm attaching a patch against Python 3.3 in the hope of moving this forward. ---------- keywords: +patch Added file: http://bugs.python.org/file23924/patch_v1.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________
Changes by Nikolaus Rath <Nikolaus@rath.org>: ---------- title: Language References does not specify exception raised by final yield() -> Language Reference: Clarify behaviour of yield when generator is not resumed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________
Nikolaus Rath added the comment: *ping* ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________
Changes by Berker Peksag <berker.peksag@gmail.com>: ---------- nosy: +pje versions: -Python 2.6, Python 3.1, Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________
Eli Bendersky added the comment: Why guess... did you try it in the code? Trying has another goal - it would be nice to have a short code sample here demonstrating what's happening. The paragraph you're quoting seems obscure to me, with or without the fix. ---------- nosy: +eli.bendersky _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________
Nikolaus Rath added the comment: On 09/04/2013 06:03 AM, Eli Bendersky wrote:
Why guess... did you try it in the code?
I don't follow... why guess what? And try what in code?
it would be nice to have a short code sample here demonstrating what's happening. The paragraph you're quoting seems obscure to me, with or without the fix.
Sounds reasonable. I'll revise the patch and add an example. Best, -Nikolaus -- »Time flies like an arrow, fruit flies like a Banana.« PGP fingerprint: 5B93 61F8 4EA2 E279 ABF6 02CF A9AD B7F8 AE4E 425C ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________
Eli Bendersky added the comment: On Wed, Sep 4, 2013 at 5:27 PM, Nikolaus Rath <report@bugs.python.org>wrote:
Nikolaus Rath added the comment:
On 09/04/2013 06:03 AM, Eli Bendersky wrote:
Why guess... did you try it in the code?
I don't follow... why guess what? And try what in code?
I was referring to this part of the original report: """ This strongly suggests that the last-executed yield statement will raise an exception if the generator is closed. If this is the case, it would be great if the documentation could be extended to say what exception is raised. If this is not the case, it would be great if whatever magic is happening could be documented as well. """ If this is the case, if this is not the case... I was just saying that you can provide some sample code in the issue that demonstrates what *actually* happens and whether it's not explained well enough in the documentation. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________
Tim Peters added the comment: I think the docs are already clear: they say "the generator-iterator’s close() method will be called". That's all that needs to be said: now go look at the docs for generator.close(). They explain _all_ that close() does, and it would be a Bad Idea to duplicate all that in this part of the docs too. (And, yes, for a start, close() "Raises a GeneratorExit at the point where the generator function was paused".) It would certainly help if the "close" (in "the generator-iterator’s close() method will be called") were an active hyperlink in the docs. ---------- nosy: +tim.peters _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________
Nikolaus Rath added the comment: I've attached an updated patch. I agree with Tim that the docs on the yield expression are already very good, so instead of extending the yield statement documentation I have shortened it to instead reduce the overlap that already exists. In the yield expression documentation, I have replaced :keyword:`yield` with an un-tagged "yield" (because the former results in a link to the yield statement) and added '.. or yield statement' to the parts that apply to both yield expressions and statements. I have also added hyperlinks to the relevant descriptions of the generator methods. ---------- Added file: http://bugs.python.org/file31688/yield-docpatch.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________
Nikolaus Rath added the comment: *ping* Any comments on the updated patch? Can it be applied? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________
Changes by Ethan Furman <ethan@stoneleaf.us>: ---------- nosy: +ethan.furman _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________
Nikolaus Rath added the comment: (adding the documentation experts from http://docs.python.org/devguide/experts.html to noisy in the hope to push this forward) ---------- nosy: +eric.araujo, ezio.melotti, georg.brandl _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________
Georg Brandl added the comment: Hmm, the yield statement is now basically the same as any expression statement -- just like a function call. The only reason it's a separate grammar symbol is that otherwise yield expressions would have to be parenthesized. Can the patch be updated to make this a bit clearer? Otherwise I like the approach of moving the info to the expressions page. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________
Nikolaus Rath added the comment: That makes sense. Attached is an updated patch. It removes most of the duplication, and clearly says that there is no semantic difference between the yield statement and the yield expression at all. I also moved the "see also" block to follow the description of the yield expression. At least for me, it was rather easy to miss in its current position (at the end of the second example subsection). The rest of the code churn in that section is just removing all the (presumably accidental) links to the yield statement when referring to a yield expression. ---------- Added file: http://bugs.python.org/file33583/yield-docpatch-rev3.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________
Roundup Robot added the comment: New changeset e02da391741f by Benjamin Peterson in branch '3.3': eliminate redundancy between yield stmt and yield expr docs (closes #12704) http://hg.python.org/cpython/rev/e02da391741f New changeset c6b4a5354c23 by Benjamin Peterson in branch 'default': merge 3.3 (closes #12704) http://hg.python.org/cpython/rev/c6b4a5354c23 ---------- nosy: +python-dev resolution: -> fixed stage: -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________
Benjamin Peterson added the comment: Thank you. In the future, please remember to wrap paragraphs to 80 chars and run "make patchcheck" to cleanup whitespace issues. ---------- nosy: +benjamin.peterson _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________
participants (8)
-
Benjamin Peterson -
Berker Peksag
-
Eli Bendersky
-
Ethan Furman
-
Georg Brandl
-
Nikolaus Rath
-
Roundup Robot
-
Tim Peters