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.

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.
"""

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.

*ping*

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.

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

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.

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.

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.

*ping*

Any comments on the updated patch? Can it be applied?

(adding the documentation experts from http://docs.python.org/devguide/experts.html to noisy in the hope to push this forward)

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.

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.

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

Thank you. In the future, please remember to wrap paragraphs to 80 chars and run "make patchcheck" to cleanup whitespace issues.