GeezerVison is showing github.com — Documentation for except* clause and ExceptionGroup can be improved . · Issue #98172 · python/cpython
Documentation for except* clause and ExceptionGroup can be improved . #98172Descriptionexcept*
except * currently reads:
The except* clause(s) are used for handling ExceptionGroups. The exception type for matching is interpreted as in the case of except, but in the case of exception groups we can have partial matches when the type matches some of the exceptions in the group. This means that multiple except* clauses can execute, each handling part of the exception group. Each clause executes once and handles an exception group of all matching exceptions. Each exception in the group is handled by at most one except* clause, the first that matches it.
try:
raise ExceptionGroup("eg",
[ValueError(1), TypeError(2), OSError(3), OSError(4)])
except* TypeError as e:
print(f'caught {type(e)} with nested {e.exceptions}')
except* OSError as e:
print(f'caught {type(e)} with nested {e.exceptions}')
caught <class 'ExceptionGroup'> with nested (TypeError(2),)
caught <class 'ExceptionGroup'> with nested (OSError(3), OSError(4))
- Exception Group Traceback (most recent call last):
| File "", line 2, in
| ExceptionGroup: eg
+-+---------------- 1 ----------------
| ValueError: 1
+------------------------------------
The following text appears in the same box as the example code, so you want to remove whatever caused that to occur in the source for the doc.
Any remaining exceptions that were not handled by any :keyword:!except*
clause are re-raised at the end, combined into an exception group along with
all exceptions that were raised from within :keyword:!except* clauses.
An :keyword:!except* clause must have a matching type,
and this type cannot be a subclass of :exc:BaseExceptionGroup.
It is not possible to mix :keyword:except and :keyword:!except*
in the same :keyword:try.
:keyword:break, :keyword:continue and :keyword:return
cannot appear in an :keyword:!except* clause.
What is needed to be explained:
- When the try body raises a single exception, not an ExceptionGroup, it will be handled by at most one handler (the first one that matches).
- The except* clause handles an exception group of all matching exceptions which were not already matched in an earlier except* clause.
- Note that ExceptionGroup is a subclass of BaseExceptionGroup, and so cannot be the type in an except* clause.
ExceptionGroup extends both BaseExceptionGroup and Exception.
BaseException
- BaseExceptionGroup
-
- ...
- Exception
-
- ...
ActivityJelleZijlstra commented on Oct 11, 2022 I opened #98173 to fix the formatting issue. changed the title [-]except* clause and ExceptionGroup need more work.[/-] [+]Documentation for except* clause and ExceptionGroup can be improved .[/+] on Oct 11, 2022JelleZijlstra commented on Oct 12, 2022 I fixed the formatting issue, thanks for pointing that out!
Your points about the substance of the docs remain. Feel free to submit a PR with improvements. iritkatriel commented on Oct 20, 2022 For except*:
When the try body raises a single exception, not an ExceptionGroup, it will be handled by at most one handler (the first one that matches).
Agreed, I will add this.
The except* clause handles an exception group of all matching exceptions which were not already matched in an earlier except* clause.
This is already stated: "Each exception in the group is handled by at most one :keyword:!except* clause, the first that matches it."
Note that ExceptionGroup is a subclass of BaseExceptionGroup, and so cannot be the type in an except* clause.
I don't think this is needed here (this is a language reference, not a tutorial, and the exception hierarchy is documented).
ExceptionGroup extends both BaseExceptionGroup and Exception.
This is why BaseExceptionGroup is in square brackets after ExceptionGroup:
"ExceptionGroup [BaseExceptionGroup]"
This is a text diagram, not sure how else we could do it. iritkatriel commented on Oct 21, 2022
MetadataMetadataDevelopmentNo branches or pull requestsIssue actions
|