How do ExceptionGroup.split and subgroup let you recover from part of a group and re-raise the rest?

### Two methods, one operation Every exception group carries a pair of partitioning methods: * `subgroup(condition)` returns a new group containing only the members that satisfy the condition, or `None` when nothing matches. * `split(condition)` returns a two-tuple `(matching, non_matching)`. Either element may be `None` — a group where everything matches gives `(group, None)`, and one where nothing matches gives `(None, group)`. The condition is an exception type, a tuple of types, or a callable that takes one exception and returns a bool. The callable form is the reason to use these methods at all rather than `except*`: it can ask questions a type cannot, such as whether an `OSError` has a particular `errno`, whether a timestamp delta is inside tolerance, or whether the failure names a resource you are willing to skip. Both methods recurse. For a nested group they descend into each child, keep the branches that still contain matching leaves, and drop the branches that do not — so the surviving structure mirrors the original rather than being flattened. The rebuilding goes through `derive`, which is also what a group subclass overrides to carry extra state through a split; each leaf keeps its own `__traceback__`, `__cause__`, `__context__` and `__notes__`, and the group's own traceback is copied onto both halves. Neither method mutates the original group. ### Partial recovery, concretely Take a video-metadata extractor that fans out across a batch of files and reports its failures as one group. Two failure modes are mixed inside it. Some files fail with a clock-skew artefact — container timestamps ahead of the wall clock — which is recoverable: you can clamp the timestamps, mark the record degraded, and still return metadata. The rest are real: an unreadable header, a truncated file, a codec you cannot parse. The 92nd-percentile budget for the batch does not survive a retry of everything, so "fail the whole batch" is the wrong answer and "log everything and continue" is worse. ```python try: extract_all(paths) except ExceptionGroup as eg: skew, fatal = eg.split(ClockSkewError) if skew is not None: record_degraded(skew) if fatal is not None: raise fatal ``` That is the shape to be able to write on a whiteboard. The recoverable half is handled and accounted for; the other half propagates as a real exception group, with its structure and tracebacks intact, so the caller sees exactly what it would have seen if nothing had been handled. Nothing is swallowed, and nothing is re-wrapped into a shape the caller has to re-parse. When the predicate is not a type — say only skew beyond tolerance is fatal — the callable form does the same job: ```python recoverable, fatal = eg.split(lambda exc: isinstance(exc, ClockSkewError) and exc.delta_seconds < 5) ``` ### When to use these over `except*` `except*` is the ergonomic form and should be the default at a try statement. Reach for the methods when: * **the condition is not a type** — `except*` can only name types; * **you need both halves at once** — `except*` hands you the matching part and re-raises the rest implicitly, which is right for handling but wrong when you want to record one half and return the other; * **the handling lives away from the try statement** — a supervisor helper, a retry policy, or a decorator that takes a group and decides what is retryable is a plain function that takes a group and calls `split`; * **you are writing a library** whose caller will do the catching, and you only want to reshape what propagates. ### Observability, and the mistake to avoid The common failure here is flattening. It is tempting to catch the group, walk it into a list of strings, log those, and re-raise something generic. That throws away every leaf traceback and the nesting that says which stage produced what — the two things that make a fan-out failure diagnosable. Prefer to keep the group and let the standard rendering print its tree; `traceback.print_exception` on a group prints each leaf under numbered markers. If you need a flat view for a metric, walk the leaves explicitly and count them by type, but keep the group object itself for the log and for the re-raise: ```python def leaves(exc): if isinstance(exc, BaseExceptionGroup): for sub in exc.exceptions: yield from leaves(sub) else: yield exc ``` Two more details worth stating. Re-raising the non-matching half is `raise fatal` — a fresh raise of an existing exception object, which records the handled group as its context; that is usually what you want in a log. And in cleanup or supervision code, catch `BaseExceptionGroup` rather than `ExceptionGroup`, and check membership with `isinstance`, so a group carrying a control-flow signal is not silently missed. ### Version note `split`, `subgroup` and `derive` arrived with the group types in Python 3.11 (PEP 654) and are unchanged through 3.14. A related 3.12 change: `contextlib.suppress` performs this same split internally, removing the matching members from a group and re-raising the remainder rather than treating the group as unmatched.