[issue19184] dis module has incorrect docs for RAISE_VARARGS
New submission from Ned Batchelder: The order of values on the stack is backwards for RAISE_VARARGS. The docs say: "Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 3. The handler will find the traceback as TOS2, the parameter as TOS1, and the exception as TOS." But in fact, the order is reverse of that. In the one-parameter case, the exception is TOS, in the two-parameter case, the value is TOS, and in the three-parameter case, the traceback is TOS. Not sure how to write that concisely, thought. :) ---------- assignee: docs@python components: Documentation keywords: easy messages: 199096 nosy: docs@python, nedbat priority: normal severity: normal status: open title: dis module has incorrect docs for RAISE_VARARGS versions: Python 2.7, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue19184> _______________________________________
Tyler B added the comment: Looked at the code and found differences between 3.4 and 2.7. 2.7 has 3 exceptions that can be raised while 3.4 has 4 exceptions. I propose removing the "list of parameters" from the documenation to keep things simple and not repeat the code. # 2.7 "Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 3. The parameters consist of the traceback as TOS1, the value as TOS2, the exception as TOS3, and None as TOS4." # 3.4 "Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 2. The parameters consist of the cause as TOS1, the exception as TOS2, and None as TOS3." How does this sound? ---------- nosy: +Tyler.B _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue19184> _______________________________________
Tyler B added the comment: I wanted to make an edit so here's my revised comment: Looked at the code and found differences between 3.4 and 2.7. 2.7 has 4 exceptions that can be raised while 3.4 has 3 exceptions. I propose removing the "list of parameters" from the documenation to keep things simple and not repeat the code. # 2.7 "Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 3. The parameters consist of the traceback as TOS1, the value as TOS2, the exception as TOS3, and None as TOS4." # 3.4 "Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 2. The parameters consist of the cause as TOS1, the exception as TOS2, and None as TOS3." How does this sound? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue19184> _______________________________________
Tyler B added the comment: One last edit: Looked at the code and found differences between 3.4 and 2.7. 2.7 has 4 exceptions that can be raised while 3.4 has 3 exceptions. I propose including the full list of parameters but describing the exceptions in a way that's less specific about the TOS order to keep the documentation as simple as possible. # 2.7 "Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 3. The parameters can consist of the traceback as TOS1, the value as TOS2, the exception as TOS3, and None as TOS4." # 3.4 "Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 2. The parameters can consist of the cause as TOS1, the exception as TOS2, and None as TOS3." How does this sound? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue19184> _______________________________________
Georg Brandl added the comment: Tyler, thanks for the suggestion. However it doesn't really solve the issue: the parameter order is the opposite of the current doc text (and your suggested text). ---------- nosy: +georg.brandl _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue19184> _______________________________________
Tyler B added the comment: Here's a revised suggestion that has the order changed. I have additional concerns but please provide comment on this revision. Thanks # 2.7 "Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 3. The parameters can consist of None as TOS1, the exception as TOS2, the value as TOS3, and the traceback as TOS4." # 3.4 "Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 2. The parameters can consist of None as TOS1, the exception as TOS2, and the cause as TOS3." ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue19184> _______________________________________
Changes by Serhiy Storchaka <storchaka+cpython@gmail.com>: ---------- stage: -> needs patch versions: +Python 3.5, Python 3.6, Python 3.7 -Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue19184> _______________________________________
Changes by Louie Lu <me@louie.lu>: ---------- pull_requests: +1288 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue19184> _______________________________________
Serhiy Storchaka added the comment: May be just provide Python statements that correspond different numbers of parameters? 0 -- ``raise``, 1 -- ``raise TOS``, 2 -- ``raise TOS1 from TOS``. ---------- nosy: +serhiy.storchaka _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue19184> _______________________________________
Louie Lu added the comment: I've made a PR, could serhiy or georg help for review? Thanks! ---------- nosy: +louielu _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue19184> _______________________________________
Cheryl Sabella <cheryl.sabella@gmail.com> added the comment: The original PR appears to have been abandoned, so this issue available for someone to submit a new PR. ---------- nosy: +cheryl.sabella versions: +Python 3.8 -Python 2.7, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue19184> _______________________________________
Michele Angrisano <michele.angrisano@gmail.com> added the comment: I'm working on it. ---------- nosy: +mangrisano _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue19184> _______________________________________
Change by Michele Angrisano <michele.angrisano@gmail.com>: ---------- keywords: +patch pull_requests: +13544 stage: needs patch -> patch review pull_request: https://github.com/python/cpython/pull/13652 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue19184> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: New changeset e1179a5096fb12297ececd7a1c79969aa5747e28 by Ezio Melotti (Michele Angrisano) in branch 'master': bpo-19184: Update the documentation of dis module. (GH-13652) https://github.com/python/cpython/commit/e1179a5096fb12297ececd7a1c79969aa57... ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue19184> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +13636 pull_request: https://github.com/python/cpython/pull/13755 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue19184> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: New changeset 9390e98c3ed9eb9fa414030a2feec1926193af94 by Ezio Melotti (Miss Islington (bot)) in branch '3.7': bpo-19184: Update the documentation of dis module. (GH-13652) (GH-13755) https://github.com/python/cpython/commit/9390e98c3ed9eb9fa414030a2feec192619... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue19184> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: Fixed, thanks for the report and the PRs! ---------- assignee: docs@python -> ezio.melotti resolution: -> fixed stage: patch review -> resolved status: open -> closed type: -> enhancement versions: +Python 3.7 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue19184> _______________________________________
participants (9)
-
Cheryl Sabella -
Ezio Melotti
-
Georg Brandl
-
Louie Lu
-
Michele Angrisano
-
miss-islington
-
Ned Batchelder
-
Serhiy Storchaka
-
Tyler B