classification
Title: document return statement in finally blocks
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Yury.Selivanov, asvetlov, docs@python, eric.araujo, georg.brandl, mark.dickinson, python-dev, rhettinger, yselivanov
Priority: normal Keywords: easy, patch

Created on 2012-03-01 15:07 by Yury.Selivanov, last changed 2012-09-24 19:26 by mark.dickinson. This issue is now closed.

Files
File name Uploaded Description Edit
finally_doc.patch Yury.Selivanov, 2012-03-02 16:23 review
finally_doc_patch.patch yselivanov, 2012-09-24 19:01 review
Messages (17)
msg154697 - (view) Author: Yury Selivanov (Yury.Selivanov) * Date: 2012-03-01 15:07
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.
msg154727 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-03-02 04:38
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?
msg154777 - (view) Author: Yury Selivanov (Yury.Selivanov) * Date: 2012-03-02 16:23
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.
msg168195 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-08-14 12:45
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
msg168196 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-08-14 12:46
Fixed. Thanks.
msg171170 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2012-09-24 18:45
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.
msg171171 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2012-09-24 18:45
See also issue 16021.  Re-opening this issue for reconsideration.
msg171172 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2012-09-24 18:46
Bah.  Issue 16028;  sorry.
msg171173 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2012-09-24 18:47
Can you close this one?  It's already merged.
msg171174 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2012-09-24 18:50
I'll open another issue and will attach a patch.
msg171175 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2012-09-24 18:53
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.)
msg171177 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2012-09-24 19:01
OK.

Attaching the patch.  Please review.
msg171180 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-09-24 19:17
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
msg171181 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2012-09-24 19:19
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.
msg171182 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2012-09-24 19:19
thanks!
msg171183 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-09-24 19:25
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
msg171184 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2012-09-24 19:26
Reclosing.
History
Date User Action Args
2012-09-24 19:26:51mark.dickinsonsetstatus: open -> closed
resolution: fixed
messages: + msg171184
2012-09-24 19:25:45python-devsetmessages: + msg171183
2012-09-24 19:19:48yselivanovsetmessages: + msg171182
2012-09-24 19:19:17mark.dickinsonsetmessages: + msg171181
2012-09-24 19:17:33python-devsetmessages: + msg171180
2012-09-24 19:01:34yselivanovsetfiles: + finally_doc_patch.patch

messages: + msg171177
2012-09-24 18:53:00mark.dickinsonsetmessages: + msg171175
2012-09-24 18:50:59yselivanovsetmessages: + msg171174
2012-09-24 18:47:53yselivanovsetnosy: + yselivanov
messages: + msg171173
2012-09-24 18:46:17mark.dickinsonsetmessages: + msg171172
2012-09-24 18:45:52mark.dickinsonsetstatus: closed -> open
resolution: fixed -> (no value)
messages: + msg171171
2012-09-24 18:45:22mark.dickinsonsetnosy: + mark.dickinson
messages: + msg171170
2012-08-14 12:46:27asvetlovsetstatus: open -> closed
resolution: fixed
messages: + msg168196

stage: needs patch -> resolved
2012-08-14 12:45:33python-devsetnosy: + python-dev
messages: + msg168195
2012-08-13 19:33:53asvetlovsetnosy: + asvetlov
2012-03-02 16:23:35Yury.Selivanovsetfiles: + finally_doc.patch
keywords: + patch
messages: + msg154777
2012-03-02 04:38:57eric.araujosetversions: + Python 3.3
nosy: + eric.araujo

messages: + msg154727

keywords: + easy
stage: needs patch
2012-03-01 15:07:08Yury.Selivanovcreate