classification
Title: Re-phrase best way of using exceptions in doanddont.rst
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.1, Python 3.2, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eric.araujo, flub, moshez, r.david.murray, terry.reedy
Priority: normal Keywords: patch

Created on 2010-08-15 12:23 by flub, last changed 2010-09-12 00:28 by eric.araujo. This issue is now closed.

Files
File name Uploaded Description Edit
doandont.diff flub, 2010-08-15 12:23
doanddont-except.patch r.david.murray, 2010-09-07 23:15
doanddont-except.patch r.david.murray, 2010-09-11 02:43
Messages (9)
msg113949 - (view) Author: Floris Bruynooghe (flub) Date: 2010-08-15 12:23
The description of how to best use exceptions is slightly confusing and led me to believe there was an issue when using open() as a context manager.  The main issue is that the wording seems to suggest the example above it is the best and not the very last.

Attached is a patch which uses a slightly different wording which IMHO makes it clearer that the with-statement is the preferred method and does not introduce subtle bugs.
msg114433 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-08-20 17:38
Doc/howto/doanddont.rst is the source for
Python HOWTOs: Idioms and Anti-Idioms in Python
Moshe Zadka original author (added as nosy)

The gist of the patch is to clarify that using 'with' is best, not the non-with version that is currently called  both 'best' and 'not very good'. I agreed that the current version is confusing and the patch or something like it should be applied.

Floris: 2.6 is closed to non-critical patches. 3.3 is for patches that cannot be applied sooner.
msg115819 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-09-07 23:15
Here is a more extensive rewrite that I think makes things clearer and (I hope) makes the text read better.  I also updated the preceding section per the confusion expressed in issue 8518.

Note that this patch is somewhat Python3 specific, since it assumes that all non-BaseException exceptions inherit from Exception.  If someone wants to backport it to 2.7 a paragraph or footnote should be added about that problem.

Opinions welcome.
msg115834 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-09-08 00:49
Your rewrite makes the text much clearer in my opinion. Here are some nits for you to grind, cheers :)

1) I’d say “using a bare ``except:``” and maybe add an index entry for “bare except” referring to that section, to make indexing and maybe googling find this.

2) To make the bad examples clearer, I would remove the second inline comment (“will be changed as soon as we run it”). The wording is confusing: Does that mean the code will be changed by Python at runtime? The text after this code example is clear enough, this comment doesn’t help.

3) “except catches all errors, including GeneratorExit which is not even an error”: Isn’t this confusing for beginners?
msg115839 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-09-08 01:16
(1) and (2) are good ideas.  For (3), would it be clear enough if it read "``except:`` catches *all* exceptions, [...] and GeneratorExit (which is not an error and should not normally be caught by user code)."
msg115841 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-09-08 01:58
It would.
msg116073 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-09-11 02:43
Here is another edit pass, incorporating Éric's suggestions and adding some additional tweaks.  In particular, I eliminated the anti-pattern of catching (IOError, OSError) in one of the earlier examples in favor of the correct EnvironmentError, and also improved the error message generated in that case :)
msg116114 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-09-11 18:59
Committed in r84719 and r84720, backported to 2.7 in r84721 with the addition of a sentence admitting that sometimes you need a bare except to catch third-party exceptions that don't inherit from Exception.
msg116140 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-09-12 00:27
Nice, thanks!
History
Date User Action Args
2010-09-12 00:28:01eric.araujosetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2010-09-12 00:27:32eric.araujosetstatus: closed -> open
resolution: fixed -> (no value)
messages: + msg116140

stage: resolved -> patch review
2010-09-11 18:59:11r.david.murraysetstatus: open -> closed
resolution: fixed
messages: + msg116114

stage: patch review -> resolved
2010-09-11 02:43:56r.david.murraysetfiles: + doanddont-except.patch

messages: + msg116073
2010-09-08 01:58:29eric.araujosetmessages: + msg115841
2010-09-08 01:16:40r.david.murraysetmessages: + msg115839
2010-09-08 00:49:54eric.araujosetnosy: + eric.araujo
messages: + msg115834
2010-09-07 23:15:05r.david.murraysetfiles: + doanddont-except.patch
nosy: + r.david.murray
messages: + msg115819

2010-09-07 23:06:19r.david.murraylinkissue8518 superseder
2010-08-20 17:39:00terry.reedysetversions: - Python 2.6, Python 3.3
nosy: + moshez, terry.reedy

messages: + msg114433

type: enhancement -> behavior
stage: patch review
2010-08-15 12:23:44flubcreate