Tutorial's claim about default exception chaining misleading

[smheidrich]

Documentation

The tutorial's section on exception chaining (raise x from y) currently claims:

Exception chaining happens automatically when an exception is raised inside an except or finally section.

While that is true, the semantics of automatically chained exceptions are different from ones explicitly chained with from, which is also reflected in how their relation is described in the resulting error messages: Automatically chained exceptions are linked with

During handling of the above exception, another exception occurred:

while for explicitly chained exceptions it says

The above exception was the direct cause of the following exception:

That is not mentioned anywhere in the tutorial section, making the claim that "chaining happens automatically" by itself extremely misleading because it suggests to people they'll get the same result whether they chain explicitly with from or not, which isn't the case. It's probably also confusing to those readers who give it a bit more thought, because the natural question to ask would be "Then why does from exist at all if it happens automatically anyway?"

My suggestion would be to explain the semantic difference and the different resulting outputs in the tutorial section, e.g. like this:

A kind of exception chaining also happens automatically when an exception is raised inside an except or finally section, although in this case the statement linking the exceptions in the error message will be different:

>>> try:
...     func()
... except ConnectionError as exc:
...     raise RuntimeError
...
Traceback (most recent call last):
 File "<stdin>", line 2, in <module>
 File "<stdin>", line 2, in func
ConnectionError

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
 File "<stdin>", line 4, in <module>
RuntimeError

As can be seen from the output, an exception raised inside an exception handler but not explicitly chained with from represents an additional, possibly unrelated error that occurred during handling, while an explicitly chained exception represents a direct consequence of the caught exception.

Of course the phrasing isn't perfect but that can be fought over in a PR if you think the overall point of this issue is valid.

Related issues

• Clarify chaining exceptions in tutorial/errors.rst #86345 went in the same direction but was more about whether the underlying technical difference, specifically __cause__ vs __context__, should be explained.

[stevendaprano]

It is a tutorial, not the reference manual. It doesn't have to dive deep into every facet of the feature.

As you say yourself, it "is true" that exceptions are chained automatically, exactly as the tutorial says.

I take your point about the (very slight) difference in intended semantics of the two situations, but they aren't two different kinds of chaining. There is only one kind of exception chaining, which differ only in whether the link between one exception and the other is described as a cause or not. Since the chain can be an arbitrary number of exceptions long, it can contain an arbitrary mix of exceptions with the cause or the context set.

the claim that "chaining happens automatically" by itself extremely misleading because it suggests to people they'll get the same result whether they chain explicitly with from or not

"Extremely" misleading? Over a slight difference in wording, that most people will neither notice nor care about? I don't think it is misleading at all, let alone "extremely" misleading. I think that dealing with this subtle difference as part of the tutorial is unnecessary detail for the tutorial's intended audience.

[smheidrich]

@stevendaprano So why have from be part of the tutorial at all if the wording that links exceptions in the output doesn't matter? That's all it does after all. If it truly didn't matter and the correct thing to teach people was to just not use it (which the "happens automatically" sentence suggests anyway), arguably it shouldn't even be in there. But if it's important enough to warrant its own keyword and its own tutorial section, I'd say it's important enough to explain in this section what the actual difference is between using and not using it.

Maybe another way to approach this would be to first have a paragraph either in that section or in an earlier one that shows what happens normally when an exception is raised from inside an except block (i.e. the automatic/implicit chaining), no matter whether it originates from a raise without from or another (non-raise) statement in the block. Then the explanation of explicit exception chaining with from doesn't need the "happens automatically" sentence anymore (because that has already been shown) and the subsequent explanation of from None to suppress implicit chaining can refer to that previous paragraph. It also wouldn't have to go into detail about the semantic difference then because that would be implied. I submitted a PR to illustrate how this could look.

[JelleZijlstra]

Backports were merged, thank you!