Documentation for except* clause and ExceptionGroup can be improved .

[mrolle45]

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
• ...

[JelleZijlstra]

I opened #98173 to fix the formatting issue.

[JelleZijlstra]

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]

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]

Thank you @mrolle45 .