classification
Title: Doc: Use of old description of raise in Python3
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, ezio.melotti, jayvdb, martin.panter, r.david.murray, terry.reedy, xiang.zhang
Priority: normal Keywords: patch

Created on 2015-10-12 08:11 by xiang.zhang, last changed 2016-01-04 03:36 by ezio.melotti.

Files
File name Uploaded Description Edit
doc_extending.patch xiang.zhang, 2015-10-12 08:11 review
doc_extending2.patch xiang.zhang, 2015-10-13 03:18 review
Messages (11)
msg252848 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2015-10-12 08:11
In the first paragraph of https://docs.python.org/3/extending/extending.html#intermezzo-errors-and-exceptions,
it is wrong to use the sentence "the second argument to raise" since
the raise syntax has been changed in Python3.
msg252858 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-10-12 15:17
Looks good to me.
msg252859 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-10-12 15:21
Actually, I take that back.  Shouldn't it be "the object passed *as* the exception object to raise?
msg252866 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2015-10-12 15:49
With this sentence

A second global variable stores the “associated value” of the exception (the second argument to raise).

I think the phrase inside the parentheses is to explain the "associated value", which is usually a string passed to the exception object, not the exception object itself.

Do I misunderstand anything?
msg252867 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-10-12 15:57
Yes.  The second element of the sys.exc_info result is the exception instance, not the argument to the exception constructor.  The old raise syntax allowed you to specify the exception instance as the second argument to raise, but if you specified a string it converted it to an exception instance using the first argument as the constructor to call.  So, the 2.7 docs aren't entirely accurate, since it isn't the second argument to raise that is stored, but the object that results from raise *processing* its second argument.
msg252871 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2015-10-12 16:34
Oops, I misunderstand sys.exc_info all the time, sad :(

Now, both versions of doc are not correct. Please make them fixed.
msg252907 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2015-10-13 03:18
I fix my patch with David's comment.
msg252913 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-10-13 05:07
“Associated value” still seems a bit weird. I wonder if it would be clearer to say

The exception type is stored in a static global variable . . . A second global variable stores the exception instance passed to :keyword:`raise` . . .

Also further down that section it looks like there are other problems. “Exception object” is perhaps actually a C object referencing the exception class (type). ‘Python string object . . . stored as the "associated value" ’ should perhaps be the exception instance (object). I think a long time ago Python may have actually worked this way, but not any more, and the whole section probably needs updating.
msg252917 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2015-10-13 05:38
Yes, you are right martin. It seems the whole chapter needs more updates, not only the bits I mentioned. I won't provide a new patch since I am not an English native and I am not sure I can provide an accurate and right description. Hope someone else may help.
msg252930 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-10-13 13:20
There's also the fact that the argument to raise can be an exception class, but the second element of sys.exc_info is still an instance of that class, which only occurred to me while reading your revised patch.
msg252933 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2015-10-13 14:03
Actually what I intend is that the exception object passed to raise is the exception instance raise finally throws (what is stored in the second variable). So it seems wise not to do any more for me. A single sentence has lead to confusion, not to mention more.
History
Date User Action Args
2016-01-04 03:36:12ezio.melottisetnosy: + ezio.melotti

type: enhancement
versions: - Python 3.4
2015-12-23 11:38:58jayvdbsetnosy: + jayvdb
2015-10-17 01:23:07terry.reedysetnosy: + terry.reedy
2015-10-13 14:03:08xiang.zhangsetmessages: + msg252933
2015-10-13 13:20:22r.david.murraysetmessages: + msg252930
stage: patch review -> needs patch
2015-10-13 05:38:44xiang.zhangsetmessages: + msg252917
2015-10-13 05:07:24martin.pantersetnosy: + martin.panter
messages: + msg252913
2015-10-13 03:18:14xiang.zhangsetfiles: + doc_extending2.patch

messages: + msg252907
2015-10-12 16:34:17xiang.zhangsetmessages: + msg252871
2015-10-12 15:57:28r.david.murraysetmessages: + msg252867
2015-10-12 15:49:50xiang.zhangsetmessages: + msg252866
2015-10-12 15:22:58r.david.murraysetstage: commit review -> patch review
2015-10-12 15:21:20r.david.murraysetmessages: + msg252859
2015-10-12 15:17:04r.david.murraysetnosy: + r.david.murray
title: Doc: Use old description of raise in Python3 -> Doc: Use of old description of raise in Python3
messages: + msg252858

versions: + Python 3.4, Python 3.5, Python 3.6
stage: commit review
2015-10-12 08:18:55vstinnersettitle: Use old description of raise in Python3 -> Doc: Use old description of raise in Python3
2015-10-12 08:11:36xiang.zhangcreate