6.9 The raise statement is confusing

[67684a2b-d186-4855-8b2e-6c5925ced7a9]

BPO	532467
Nosy	@freddrake, @rhettinger
Files	ref6_small.diff: Small doc patch clarifying objects vs expressions ref6_big.diff: Bigger patch with greater clarity.

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields: ```python assignee = 'https://github.com/freddrake' closed_at = created_at = labels = ['docs'] title = '6.9 The raise statement is confusing' updated_at = user = 'https://bugs.python.org/pobrien' ``` bugs.python.org fields: ```python activity = actor = 'fdrake' assignee = 'fdrake' closed = True closed_date = None closer = None components = ['Documentation'] creation = creator = 'pobrien' dependencies = [] files = ['374', '375'] hgrepos = [] issue_num = 532467 keywords = [] message_count = 7.0 messages = ['9793', '9794', '9795', '9796', '9797', '9798', '9799'] nosy_count = 3.0 nosy_names = ['fdrake', 'rhettinger', 'pobrien'] pr_nums = [] priority = 'high' resolution = 'fixed' stage = None status = 'closed' superseder = None type = None url = 'https://bugs.python.org/issue532467' versions = ['Python 2.2'] ```

[67684a2b-d186-4855-8b2e-6c5925ced7a9]

The description supplied for "6.9 The raise statement" is confusing. In particular, it starts by explaining the intent of each "expresssion" and midway switches to "object" instead of expression. In particular, I can't make heads or tails out of the following passage:

"If the first object is a string, it then raises the exception identified by the first object, with the second one (or None) as its parameter. If the first object is a class or instance, it raises the exception identified by the class of the instance determined in the previous step, with the instance as its parameter."

[rhettinger]

Logged In: YES user_id=80475

Attached two alternative patches.

The first makes minimal changes to achieve a clear and consistent use of "objects" versus "expressions".

The second alternative re-paragraphs the text and uses parallel sentence contruction to provide (IMHO) greater clarity without getting a headache reading it.

If accepted, please re-assign to Raymond for a commit to 2.3 and to release22-maint.

[67684a2b-d186-4855-8b2e-6c5925ced7a9]

Logged In: YES user_id=179604

Raymond, I really appreciate your patches. The big patch is terrific and gets my vote. I do have one more request for clarification in what you wrote. You say:

"If the first expression is a class object, it raises the exception identified by the class of an instance determined by the second expression. If the second expression is an instance, that instance is used."

So we're talking about the form: raise class, instance

What I'm picturing is a situation where the second expression is an instance of a class other than the class object used as the first expression. Is this allowed, disallowed, allowed but nonsensical or allowed because it offers some practical benefit that I'm just not grasping?

I found and read the essay on "Standard Exception Classes in Python 1.5" (http://www.python.org/doc/essays/stdexceptions.html) and I can see that much was done to maintain backward compatibility. and apparently the "raise class, instance" form goes back quite a ways. Is this just a wart to be avoided? I'm probably expecting too much to expect the language reference to distinguish between what is strictly allowed vs. why it is allowed and whether it should even be used at all. It's just that the more I dug into this the more confused I became. I think I'm understanding the situation now.

In any case, make of this what you will. The bottom line is that your batch is definitely an improvement and I greatly appreciate your time and effort on this. Thanks.

[rhettinger]

Logged In: YES user_id=80475

Thanks Patrick.

Since I'm the new guy, I'll defer additional changes to Fred. My patch style is to make the least invasive change that improves clarity and accuracy.

Also, this may be a case where additional wording, even if informative and accurate, may detract from a strong understanding of how raise works.

This section's cyclomatic complexity (nested if/elif/else paths) already impinges its understandability.

[freddrake]

Logged In: YES user_id=3066

Bumped priority since Raymond is waiting for my review.

[freddrake]

Logged In: YES user_id=3066

Raymond is still waiting, so bumping to 7 so I notice it in the morning (when I'm not really asleep).

[freddrake]

Logged In: YES user_id=3066

I've checked in a different patch as Doc/ref/ref4.tex 1.32 and Doc/ref/ref6.tex 1.54.

Please review the changes; if not sufficient, please re-open this report with comments on what else is needed (or file a new report).

http://www.python.org/dev/doc/devel/ref/raise.html