I think that the documentation should put more emphasis on the `return` statement in a `finally` block.

Example:

  def test():
      try:
          1/0
      finally:
          return 10

  >>> test()
  10

I think we need to add a warning, or at least a note, that 'return' masks exceptions, if any occurred.

This behavior surprised me for a second, but it makes sense.  An example in the docs is certainly appropriate.  Would you like to suggest a place and phrasing for it?

Well, I guess the best place to put it would be http://docs.python.org/py3k/reference/compound_stmts.html#finally

I've attached the patch, please take a look.  If it's possible to make it more clear, feel free to rephrase it.  But please include the example, this behaviour needs to be emphasized.

New changeset e0e8e70e4035 by Andrew Svetlov in branch '3.2':
Issue #14167: Document return statement in finally blocks.
http://hg.python.org/cpython/rev/e0e8e70e4035

New changeset 05714e9811fa by Andrew Svetlov in branch 'default':
Issue #14167: Document return statement in finally blocks.
http://hg.python.org/cpython/rev/05714e9811fa

New changeset bef098bd3fa5 by Andrew Svetlov in branch '2.7':
Issue #14167: Document return statement in finally blocks.
http://hg.python.org/cpython/rev/bef098bd3fa5

Fixed. Thanks.

I think something went wrong with this doc change.  The docs used to say:

"""
If the :keyword:`finally` clause raises another exception or executes a :keyword:`return` or :keyword:`break` statement, the saved exception is lost.
"""

Now we have:

"""
If there is a saved exception or :keyword:`break` statement, it is re-raised at the end of the :keyword:`finally` clause.
"""

which doesn't make much sense (what does 'it' refer to in the case of a 'break' statement), and we seem to have lost the explicit statement that a 'break' in a finally cause swallows exceptions.

See also issue 16021.  Re-opening this issue for reconsideration.

Bah.  Issue 16028;  sorry.

Can you close this one?  It's already merged.

I'll open another issue and will attach a patch.

Yury:  I don't think there's any need for yet another issue;  this one will do (or if you prefer, attach the patch to issue 16028.)

OK.

Attaching the patch.  Please review.

New changeset 485902ecf0ee by Mark Dickinson in branch '3.2':
Issue #14167: restore statement about breaks in finally clauses.
http://hg.python.org/cpython/rev/485902ecf0ee

New changeset f5ed3a5440b2 by Mark Dickinson in branch 'default':
Issue #14167: merge fix from 3.2 branch.
http://hg.python.org/cpython/rev/f5ed3a5440b2

Thanks for the quick fix!  Patch applied to 3.2 and 3.3

The 2.7 commit also introduced an incorrect statement about exception chaining;  I'll look at fixing that.

thanks!

New changeset f51d11405f1d by Mark Dickinson in branch '2.7':
Issue #14167: restore statement about breaks in finally clauses; remove statement about exception chaining.
http://hg.python.org/cpython/rev/f51d11405f1d

Reclosing.