classification
Title: Error in documentation of point 9.8 'Exceptions are classes too'
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Peibolvig, akuchling, berker.peksag, docs@python, josh.r, python-dev, terry.reedy
Priority: normal Keywords: patch

Created on 2014-06-24 23:41 by Peibolvig, last changed 2016-11-06 18:02 by berker.peksag. This issue is now closed.

Files
File name Uploaded Description Edit
issue21864.diff berker.peksag, 2016-06-02 21:29 review
Messages (9)
msg221511 - (view) Author: Peibolvig (Peibolvig) Date: 2014-06-24 23:41
At point 9.8 of the 3.4.1 version documentation, ( https://docs.python.org/3/tutorial/classes.html#exceptions-are-classes-too ), there is an example of two ways to use the 'raise' statement:
raise Class
raise Instance

The next two lines, state: 
"In the first form, Class must be an instance of type or of a class derived from it. The first form is a shorthand for: raise Class()"

That only says something about the first form twice.
I think that the correct way would be:
"In the first form, Class must be an instance of type or of a class derived from it. The SECOND form is a shorthand for: raise Class()"
msg221513 - (view) Author: Josh Rosenberg (josh.r) * (Python triager) Date: 2014-06-25 00:09
No. The first form, raise Class, is in fact a shorthand for raise Class(). That's the point. You only actually raise instances, but if you pass it a class directly, it instantiates it by calling its constructor with no arguments. The second form is not described explicitly, but the example shows it in use. An instance of an Exception class is explicitly created.
msg221514 - (view) Author: Peibolvig (Peibolvig) Date: 2014-06-25 00:25
Oh, I see. Thanks for the clarification.

May I suggest to include that clarification into the documentation somehow? I think it would be easier to understand the point of the raises doing that.

Maybe this suggestion could fit:
In the first form, Class must be an instance of type or of a class derived from it. The first form is a shorthand for:
raise Class()
"'raise' will always use an instance. If a class is passed instead of an instance, it will instantiate it first using the constructor with no arguments."


Again, thanks for the clarification.
msg221517 - (view) Author: Josh Rosenberg (josh.r) * (Python triager) Date: 2014-06-25 01:19
I think the section could use some additional rewording actually. The wording about deriving from type dates back to the Python 2 days; nowadays, all exceptions are actually required to derive from BaseException. The section definitely needs rewording.
msg221714 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-06-27 19:29
The preceding sentence "There are two new valid (semantic) forms for the raise statement" is obsolete also as there is no other form (other than 'raise', which should not be in the tutorial previously). To rewrite this section for 3.x would require looking at what has already been said about exceptions and raise. It seems to have been written for ancient python where raise 'somestring' was the norm.
msg266958 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-06-02 21:29
I think the "Exceptions Are Classes Too" section can be removed now. Users already learned that exceptions are classes in the previous chapter: https://docs.python.org/3/tutorial/errors.html

I'm attaching a patch that removes the "Exceptions Are Classes Too" section and merges some of its content into https://docs.python.org/3/tutorial/errors.html
msg280156 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2016-11-06 17:32
The patch looks good to me; I think it should just be applied.
msg280159 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-11-06 18:01
New changeset db6d556365d7 by Berker Peksag in branch '3.5':
Issue #21864: Remove outdated section about exceptions from the tutorial
https://hg.python.org/cpython/rev/db6d556365d7

New changeset f82e348946e3 by Berker Peksag in branch '3.6':
Issue #21864: Merge from 3.5
https://hg.python.org/cpython/rev/f82e348946e3

New changeset 6ec669efeea5 by Berker Peksag in branch 'default':
Issue #21864: Merge from 3.6
https://hg.python.org/cpython/rev/6ec669efeea5
msg280160 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-11-06 18:02
Thank you for the review, Andrew!
History
Date User Action Args
2016-11-06 18:02:37berker.peksagsetstatus: open -> closed
versions: + Python 3.7
messages: + msg280160

resolution: fixed
stage: patch review -> resolved
2016-11-06 18:01:02python-devsetnosy: + python-dev
messages: + msg280159
2016-11-06 17:32:35akuchlingsetnosy: + akuchling
messages: + msg280156
2016-06-02 21:29:10berker.peksagsetfiles: + issue21864.diff

versions: + Python 3.6, - Python 3.4
keywords: + patch
nosy: + berker.peksag

messages: + msg266958
stage: needs patch -> patch review
2014-06-27 19:29:54terry.reedysetnosy: + terry.reedy
messages: + msg221714
2014-06-26 14:33:10berker.peksagsetstage: needs patch
type: enhancement
versions: + Python 3.5
2014-06-25 01:19:07josh.rsetmessages: + msg221517
2014-06-25 00:25:29Peibolvigsetmessages: + msg221514
2014-06-25 00:09:24josh.rsetnosy: + josh.r
messages: + msg221513
2014-06-24 23:41:00Peibolvigcreate