Exception Groups

### Matching is a split, not a catch A plain `except` clause asks one question — is the propagating object an instance of this type? — and if the answer is yes it consumes the whole exception. An `except*` clause asks a different question of a *group*: which of your members are instances of this type? It then partitions the group into the matching part and the rest. The matching part is wrapped in a new group of the same kind and bound by the `as` name; the rest is carried forward to the next `except*` clause. This has three consequences that interviewers probe directly: 1. **More than one clause can run for a single raise.** With members `ValueError` and `OSError`, both `except* ValueError` and `except* OSError` execute, in source order. This is the biggest behavioural difference from `except`, where the first match wins and the rest are skipped. 2. **Each clause runs at most once**, on the whole matching subgroup, not once per matching member. If you want per-member handling, loop over `eg.exceptions` inside the clause. 3. **The bound object is always a group.** Even `except* ValueError as eg` binds an `ExceptionGroup`, never the `ValueError` itself, so `eg.exceptions[0]` is the leaf. That holds even when the try body raised a bare exception: `except*` wraps a non-group exception in a group before matching, which is what lets one handler cover both a single failure and a fan-out. ### Leftovers are re-raised, never dropped Whatever no clause matched does not disappear. When the try statement finishes, Python re-raises a group containing exactly the unmatched members, preserving the original nesting and each leaf's own traceback, cause, context and notes: ```python try: try: raise ExceptionGroup('m', [ValueError('a'), OSError('b')]) except* ValueError: print('handled the value error') except ExceptionGroup as leftover: print(leftover.exceptions) # (OSError('b'),) ``` That is the property that makes `except*` safe in the middle of a stack: a handler that knows about one failure mode cannot accidentally swallow the ones it does not understand. A bare `raise` inside an `except*` block re-raises the subgroup that clause received, putting it back among the leftovers. ### If a handler itself raises An exception raised inside an `except*` body does not replace the leftovers — the two are combined. At the end of the try statement one group propagates, carrying both the unhandled members and whatever the handlers raised, with the original group recorded as the new exception's `__context__`. Rendering that group shows both branches of the story: what failed originally, and what failed while handling it. ### The syntax restrictions, and why they exist Three things are rejected at compile time: * **Mixing forms.** `cannot have both 'except' and 'except*' on the same 'try'`. The two have incompatible matching models, and allowing both would make the order of evaluation meaningless. * **A bare `except*:`.** It must name one or more types — `expected one or more exception types`. "Catch everything" has no coherent meaning for a construct whose job is to partition by type; use plain `except` (or `except* BaseException` deliberately) if that is really what you want. * **`break`, `continue` and `return` inside an `except*` body** — `'break', 'continue' and 'return' cannot appear in an except* block`. Because several clauses may run and the leftovers must still be re-raised afterwards, jumping out of the middle of that sequence would either lose exceptions or leave the statement half-finished. Set a flag and act on it after the try statement instead. One more restriction is enforced at run time rather than compile time: naming a group type in the clause. `except* ExceptionGroup` raises `TypeError: catching ExceptionGroup with except* is not allowed. Use except instead.` Matching a group by its group-ness would make the partitioning circular, so if you really mean "the whole group", use a plain `except`. `else` and `finally` behave exactly as they do on an ordinary try, and `try`/`except*` may be nested freely. ### Practical notes You do not have to switch a whole codebase to `except*`. It is worth using where a call site can genuinely produce several independent failures — the boundary around a fan-out — and pointless where one exception is raised at a time. Where you need the non-matching half in hand rather than re-raised, or where the predicate is not a type at all, use the group's `split` and `subgroup` methods directly; `except*` is syntax over the same partitioning. ### Version note `except*` is Python 3.11 (PEP 654) and is a syntax error before it, so it cannot be feature-flagged at runtime — a module using it fails to compile on 3.10. Its behaviour is unchanged through 3.14. One related 3.12 change worth knowing: `contextlib.suppress` learned to suppress matching members *inside* a group, splitting it and re-raising the rest, rather than only matching a bare exception.