[issue8652] Minor improvements to the "Handling Exceptions" part of the tutorial

[Éric Araujo]

Éric Araujo  added the comment:

> Removes the two instances I noticed of treating exception instances as 
> sequences.
Looks good.

> Adds a warning explaining ``except FooException, BarException:`` does not do 
> what you might think.
Ditto.

> There are two things I'm not entirely happy about:

> I initially wrote ``print "I/O error({0.errno}): {0.strerror}".format(e)``,
> but then noticed this string formatting trick is not mentioned in the 
> previous chapter
> of the tutorial. Dict access (``"{0[foo]}".format(d)``) is, but attribute 
> access
> is not. Is this worth adding to that chapter, so it can be used here?
It’s not at all a trick :)  Given that item access is already covered, I don’t 
think your use of attribute access would make the example harder for beginners, 
but I may not be the best judge.

> Binding an exception instance to a variable (using "as") is explained near 
> the bottom
> of the section on catching exceptions, well before it is used.
> Perhaps this could do with a bit of reordering?
+1.

A note about workflow: patches should usually apply to the py3k branch, the 
person who commits takes care of backporting to 3.1 and 2.7.  In this case, 
some of your editions are not relevant for 3.x, so I suggest you use one of 
those workflows:
1) Make one patch for py3k and one for 2.7
2) Make one for 2.7, with comments indicating parts that apply to py3k too
3) Make one patch with edits relevant for py3k and 2.7, and another one for 
2.7-only edits

--
nosy: +terry.reedy
stage:  -> patch review
versions: +Python 2.7, Python 3.1, Python 3.2, Python 3.3

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue8652] Minor improvements to the "Handling Exceptions" part of the tutorial

[Marien Zwart]

Marien Zwart  added the comment:

Sorry for forgetting about this for so long.

The attached patch makes the following changes:

Removes the two instances I noticed of treating exception instances as 
sequences. This no longer works in python 3 and is not very useful in python 2, 
so best avoided.

Adds a warning explaining ``except FooException, BarException:`` does not do 
what you might think. I think this is a good warning to have (because you *can* 
omit those parens in many other places) and it mentions the pre-python 2.6 
syntax for "as" by side effect.

There are two things I'm not entirely happy about:

I initially wrote ``print "I/O error({0.errno}): {0.strerror}".format(e)``, but 
then noticed this string formatting trick is not mentioned in the previous 
chapter of the tutorial. Dict access (``"{0[foo]}".format(d)``) is, but 
attribute access is not. Is this worth adding to that chapter, so it can be 
used here?

Binding an exception instance to a variable (using "as") is explained near the 
bottom of the section on catching exceptions, well before it is used. Perhaps 
this could do with a bit of reordering? I felt it better to keep my initial 
patch more minimal though.

Comments? :)

--
keywords: +patch
Added file: http://bugs.python.org/file18857/errors.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue8652] Minor improvements to the "Handling Exceptions" part of the tutorial

[Marien Zwart]

New submission from Marien Zwart :

Based on questions asked on freenode's #python by people reading the tutorial I 
would like to suggest two improvements to 
http://docs.python.org/tutorial/errors.html#handling-exceptions :

- Mention the older "except SomeException, e:" syntax too, not just "except 
SomeException as e:". I have had people ask me to help them upgrade to a newer 
python because they thought their version of python did not support catching 
exception instances (their distro python being 2.5). A big fat warning that 
they're reading the Python 2.6 tutorial (with links to older tutorials) may 
also work.

- Mention "except IOError as e" before mentioning "except IOError as (errno, 
strerror):". The latter is an advanced and relatively unusual trick, combining 
regular exception catching and unpacking. Those two concepts need to be 
explained before the combination is. I have had people ask me how to do "except 
KeyError as (key, insert_something_here):" because they thought they *always* 
needed those parens there.

(perhaps just not mentioning unpacking here at all, using "except IOError as 
e:" and then using e.errno would make more sense, especially since "except 
IOError as (errno, strerror):" is a SyntaxError in python 3 and up (because of 
the unpacking) and python 2.5.x and down (because of the "as")...)

I can try to write a patch to the documentation if you like.

--
assignee: d...@python
components: Documentation
messages: 105218
nosy: d...@python, marienz
priority: normal
severity: normal
status: open
title: Minor improvements to the "Handling Exceptions" part of the tutorial

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue8652] Minor improvements to the "Handling Exceptions" part of the tutorial

[Éric Araujo]

Éric Araujo  added the comment:

The older exception catching syntax should not be promoted but could be 
mentioned, I agree. Adding a paragraph explaining why it was changed would do 
the trick.

Regarding the non-obviousness of which Python version the docs apply to, it is 
indeed mentioned on the front page of the docs, and repeated in the top-left 
corner of each page. You could propose making it bigger. Another way of doing 
this would be to have the page redirect to a URI that includes the version. 
That way, there would be another place to look for the version, and it would 
also make it easier to find out how to find the doc for other versions.

Last, exception unpacking being deprecated (because it’s horrible) and causing 
pain to newcomers seems a good reason to shot it down. Perhaps we should leave 
a short note about it, for people that get strange errors when using it 
inadvertently (or not getting an error where they thought they would).

I suggest you wait some more days for feedback from people with more experience 
with the docs. Sorry if my English was a bit convoluted :)

--
nosy: +merwok

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue8652] Minor improvements to the "Handling Exceptions" part of the tutorial

[Éric Araujo]

Éric Araujo  added the comment:

Since there has been no feedback, you could write a patch to get the discussion 
going.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue8652] Minor improvements to the "Handling Exceptions" part of the tutorial

[Roundup Robot]

Roundup Robot  added the comment:

New changeset b873afe640e2 by R David Murray in branch '2.7':
#8652: update errors tutorial.
http://hg.python.org/cpython/rev/b873afe640e2

--
nosy: +python-dev

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue8652] Minor improvements to the "Handling Exceptions" part of the tutorial

[R. David Murray]

R. David Murray  added the comment:

The Python3 tutorial was already fixed, and the explanation of the parens is 
not needed there since the "old syntax" is not supported.

I did not do any reordering since the use of 'as' immediately follows in the 
text and seems to make fine sense as is.  Actually, it now makes more sense 
than the equivalent exposition in the Python3 docs, where the paragraph is 
absent.

Thanks for the patch, Marien.

--
nosy: +r.david.murray
resolution:  -> fixed
stage: patch review -> committed/rejected
status: open -> closed
type:  -> behavior
versions:  -Python 3.1, Python 3.2, Python 3.3

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com