Documentation for except* clause and ExceptionGroup can be improved .

except*

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

ExceptionGroup extends both BaseExceptionGroup and Exception.

BaseException

BaseExceptionGroup
- ExceptionGroup
...
Exception
- ExceptionGroup
...

gh-98172: Fix formatting in `except*` docs

I opened #98173 to fix the formatting issue.

gh-98172: Fix formatting in `except*` docs (#98173)

pythongh-98172: Fix formatting in `except*` docs (pythonGH-98173)

gh-98172: Fix formatting in `except*` docs (GH-98173)

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.

Merge branch 'main' into typewatch

Merge branch 'main' into cached_property

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.

pythongh-98172: mention that except* handles naked exceptions

gh-98172: [doc] mention that except* handles naked exceptions (GH-98496)

pythongh-98172: [doc] mention that except* handles naked exceptions (p…

@mrolle45

Thank you @mrolle45 .

gh-98172: [doc] mention that except* handles naked exceptions (GH-98496)

gh-98172: Fix formatting in `except*` docs (GH-98173)

Navigation Menu

Repository navigation

Documentation for except* clause and ExceptionGroup can be improved . #98172

except*

ExceptionGroup

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Documentation for except* clause and ExceptionGroup can be improved . #98172

Description

except*

ExceptionGroup

Activity

JelleZijlstra commented on Oct 11, 2022

JelleZijlstra commented on Oct 12, 2022

iritkatriel commented on Oct 20, 2022

iritkatriel commented on Oct 21, 2022

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions