[issue21864] Error in documentation of point 9.8 'Exceptions are classes too'
New submission from Peibolvig: 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()" ---------- assignee: docs@python components: Documentation messages: 221511 nosy: Peibolvig, docs@python priority: normal severity: normal status: open title: Error in documentation of point 9.8 'Exceptions are classes too' versions: Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21864> _______________________________________
Josh Rosenberg added the comment: 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. ---------- nosy: +josh.rosenberg _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21864> _______________________________________
Peibolvig added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21864> _______________________________________
Josh Rosenberg added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21864> _______________________________________
Changes by Berker Peksag <berker.peksag@gmail.com>: ---------- stage: -> needs patch type: -> enhancement versions: +Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21864> _______________________________________
Terry J. Reedy added the comment: 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. ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21864> _______________________________________
Berker Peksag added the comment: 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 ---------- keywords: +patch nosy: +berker.peksag stage: needs patch -> patch review versions: +Python 3.6 -Python 3.4 Added file: http://bugs.python.org/file43117/issue21864.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21864> _______________________________________
A.M. Kuchling added the comment: The patch looks good to me; I think it should just be applied. ---------- nosy: +akuchling _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21864> _______________________________________
Roundup Robot added the comment: 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 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21864> _______________________________________
Berker Peksag added the comment: Thank you for the review, Andrew! ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed versions: +Python 3.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21864> _______________________________________
participants (6)
-
A.M. Kuchling -
Berker Peksag
-
Josh Rosenberg
-
Peibolvig
-
Roundup Robot
-
Terry J. Reedy