classification
Title: dis module has incorrect docs for RAISE_VARARGS
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: Tyler.B, cheryl.sabella, docs@python, ezio.melotti, georg.brandl, louielu, mangrisano, nedbat, serhiy.storchaka
Priority: normal Keywords: easy, patch

Created on 2013-10-06 16:46 by nedbat, last changed 2019-06-02 23:19 by ezio.melotti. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 1159 closed louielu, 2017-04-16 04:29
PR 13652 merged mangrisano, 2019-05-29 11:42
PR 13755 merged miss-islington, 2019-06-02 21:35
Messages (13)
msg199096 - (view) Author: Ned Batchelder (nedbat) * (Python triager) Date: 2013-10-06 16:46
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.  :)
msg199970 - (view) Author: Tyler B (Tyler.B) Date: 2013-10-15 00:44
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?
msg199989 - (view) Author: Tyler B (Tyler.B) Date: 2013-10-15 10:24
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?
msg199992 - (view) Author: Tyler B (Tyler.B) Date: 2013-10-15 10:37
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?
msg199994 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-10-15 11:32
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).
msg200031 - (view) Author: Tyler B (Tyler.B) Date: 2013-10-16 00:50
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."
msg291758 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-04-16 16:57
May be just provide Python statements that correspond different numbers of parameters? 0 -- ``raise``, 1 -- ``raise TOS``, 2 -- ``raise TOS1 from TOS``.
msg292309 - (view) Author: Louie Lu (louielu) * Date: 2017-04-26 06:51
I've made a PR, could serhiy or georg help for review?
Thanks!
msg343839 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2019-05-29 00:07
The original PR appears to have been abandoned, so this issue available for someone to submit a new PR.
msg343878 - (view) Author: Michele Angrisano (mangrisano) * Date: 2019-05-29 10:18
I'm working on it.
msg344324 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2019-06-02 21:34
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/e1179a5096fb12297ececd7a1c79969aa5747e28
msg344335 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2019-06-02 23:18
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/9390e98c3ed9eb9fa414030a2feec1926193af94
msg344336 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2019-06-02 23:19
Fixed, thanks for the report and the PRs!
History
Date User Action Args
2019-06-02 23:19:46ezio.melottisetstatus: open -> closed

assignee: docs@python -> ezio.melotti
versions: + Python 3.7
messages: + msg344336
type: enhancement
resolution: fixed
stage: patch review -> resolved
2019-06-02 23:18:53ezio.melottisetmessages: + msg344335
2019-06-02 21:35:15miss-islingtonsetpull_requests: + pull_request13636
2019-06-02 21:34:15ezio.melottisetnosy: + ezio.melotti
messages: + msg344324
2019-05-29 11:42:21mangrisanosetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request13544
2019-05-29 10:18:55mangrisanosetnosy: + mangrisano
messages: + msg343878
2019-05-29 00:07:27cheryl.sabellasetnosy: + cheryl.sabella

messages: + msg343839
versions: + Python 3.8, - Python 2.7, Python 3.5, Python 3.6, Python 3.7
2017-04-26 06:51:31louielusetnosy: + louielu
messages: + msg292309
2017-04-16 16:57:52serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg291758
2017-04-16 04:29:43louielusetpull_requests: + pull_request1288
2017-04-15 07:06:10serhiy.storchakasetstage: needs patch
versions: + Python 3.5, Python 3.6, Python 3.7, - Python 3.4
2013-10-16 00:50:10Tyler.Bsetmessages: + msg200031
2013-10-15 11:32:38georg.brandlsetnosy: + georg.brandl
messages: + msg199994
2013-10-15 10:37:13Tyler.Bsetmessages: + msg199992
2013-10-15 10:24:53Tyler.Bsetmessages: + msg199989
2013-10-15 00:44:16Tyler.Bsetnosy: + Tyler.B
messages: + msg199970
2013-10-06 16:46:52nedbatcreate