Skip to content

Documentation for except* could be clearer #135629

Open
@mandeep

Description

@mandeep

Documentation

https://docs.python.org/3.14/reference/compound_stmts.html#except-star

This is the current documentation for except* which I think could be clearer. I had to read this a few times over and even ask an AI chat bot for clarification.

The except* clause(s) are used for handling ExceptionGroups, but in the case of exception groups we can have partial 
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 at most 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.

I think it could be much clearer with something like this where the large paragraph is made more concise and broken up into bullet points.

The except* clause(s) are used to handle ExceptionGroups, which contain multiple exceptions raised together. 
Like a regular except clause, except* matches exceptions based on their type, but it can also match a subset of exceptions within 
an ExceptionGroup. This allows multiple except* clauses to execute, each handling a specific part of the exception group. 

- Each except* clause executes at most once and handles a subgroup of exceptions that match its specified type.
- Every exception in the group is handled by only one except* clause, the first one that matches its type.

The first paragraph could also include why one would want to use an except* clause. The second paragraph of 8.4.2 could be made clearer as well.

Please let me know your thoughts. I am happy to submit a patch for this.

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation in the Doc dir

    Projects

    Status

    Todo

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions