Issue 27719: Misleading note about "args" attribute in "User-defined Exceptions" section of tutorial (original) (raw)
Created on 2016-08-09 16:08 by benhoyt, last changed 2022-04-11 14:58 by admin. This issue is now closed.
Messages (7)
Author: Ben Hoyt (benhoyt) *
Date: 2016-08-09 16:08
In the official tutorial in the "User-defined Exceptions" section (https://docs.python.org/3.5/tutorial/errors.html#user-defined-exceptions) there's a note about a user-defined Exception subclass as follows:
"In this example, the default init() of Exception has been overridden. The new behavior simply creates the value attribute. This replaces the default behavior of creating the args attribute."
That last sentence is wrong: it used to be that way (it is in Python 2.x and I believe in Python pre 3.2), but now the implementation of BaseException.new now sets args, so even when you override init and don't call super() args is set. I think that's what you want, so I'm putting this down to a documentation bug. I think the sentence "This replaces the default behavior of creating the args attribute." should simply be removed (BaseException.init basically does nothing now).
This change happened for Python 3.3 and was backported to Python 3.2. See also:
- The relevant part of BaseException.new in the CPython codebase: https://github.com/python/cpython/blob/601ee5fab5df81a25611da0667030de531c1cda9/Objects/exceptions.c#L44-L48
- The issue where this behaviour was changed: http://bugs.python.org/issue1692335
- The commit where it was changed: https://hg.python.org/cpython/rev/68e2690a471d (on GitHub at https://github.com/python/cpython/commit/a71a87e695b05a67bd22c6ac74311b1f56f3932e)
- You can repro this and confirm that "args" is definitely set with the attached script:
$ python exception_args_test.py sys.version_info(major=3, minor=5, micro=2, releaselevel='final', serial=0) Error args: ('error!',)
Author: Ben Hoyt (benhoyt) *
Date: 2016-08-09 16:10
Note that I added the committers from issue 1692335 to the Nosy List -- probably overzealous and probably not the folks who maintain the docs, but oh well. :-)
Author: Berker Peksag (berker.peksag) * 
Date: 2016-08-10 00:09
Thank you for your detailed report! Would you like to propose a patch?
This behavior is already tested in testAttributes in Lib/test/test_exceptions.py so we just need a documentation patch.
Author: Ben Hoyt (benhoyt) *
Date: 2016-08-11 01:54
Okay, patch attached -- I think it's best to simply remove that sentence.
Side note: this is why GitHub is so good -- click edit, remove the sentence, click create pull request (approx time 30 seconds). I've got a new machine since I last did Python development, so to create an actual patch I needed to: download Mercurial, clone the repo, install Sphinx, edit the file, build the docs, create the patch (approx time 30 minutes). On the positive side, each of those steps was painless and trouble-free. :-)
Author: Raymond Hettinger (rhettinger) *
Date: 2016-08-11 07:22
Thanks for noticing this. It looks like this particular example is now pointless and should be removed. The subsequent examples do a much better job of showing typical practices.
Author: Ben Hoyt (benhoyt) *
Date: 2016-08-11 17:25
Removing that whole example sounds good to me, thanks.
Author: Roundup Robot (python-dev) 
Date: 2016-08-12 16:44
New changeset 6fdd29a9d5d4 by Raymond Hettinger in branch '3.5': Issue 27719: Remove a doc example that is not applicable in Python 3 https://hg.python.org/cpython/rev/6fdd29a9d5d4
History
Date
User
Action
Args
2022-04-11 14:58:34
admin
set
github: 71906
2016-08-12 16:44:40
rhettinger
set
status: open -> closed
resolution: fixed
2016-08-12 16:44:27
python-dev
set
nosy: + python-dev
messages: +
2016-08-11 17:25:49
benhoyt
set
messages: +
2016-08-11 07:23:02
rhettinger
set
assignee: docs@python -> rhettinger
2016-08-11 07:22:48
rhettinger
set
files: + exc_doc.diff
nosy: + rhettinger
messages: +
2016-08-11 01:54:25
benhoyt
set
files: + issue27719-1.patch
keywords: + patch
messages: +
2016-08-10 00:09:15
berker.peksag
set
type: behavior
versions: - Python 3.2, Python 3.3, Python 3.4
keywords: + easy
nosy: + berker.peksag
messages: +
stage: needs patch
2016-08-09 16:10:56
benhoyt
set
messages: +
2016-08-09 16:08:46
benhoyt
create