Do notes added with add_note survive when an except* handler splits an ExceptionGroup?

Exception groups are how a concurrent fan-out reports many failures at once, and notes are how each of those failures says *which unit of work* it came from. The two features shipped one release apart — notes in 3.11 with PEP 678, groups in 3.11 with PEP 654 — and they compose better than most people expect, because filtering a group does not rebuild its leaves. ## The scenario A fraud-scoring service re-scores a 2.4 GB working set of stored records. The records are decoded and scored in parallel; a few carry an encoding mismatch and raise `UnicodeDecodeError`. The failures are collected and reported together: ```python failures = [] for record_id, raw in batch: try: score(raw.decode("utf-8")) except UnicodeDecodeError as exc: exc.add_note(f"record_id={record_id}") failures.append(exc) if failures: group = ExceptionGroup("decode failures", failures) group.add_note("shard=7") raise group ``` Without the per-member note, the caller sees a dozen identical `'utf-8' codec can't decode byte 0xff in position 0` lines and no way to tell which records to quarantine. With it, every branch of the rendered tree names its record. ## What except* actually does to the objects An `except* UnicodeDecodeError` clause does not hand you the original group. It calls the group's splitting machinery to produce the matching part, and the same machinery backs `BaseExceptionGroup.split` and `BaseExceptionGroup.subgroup` when you call them yourself. That machinery: * **reuses the leaf exceptions.** The members of the derived group are the identical objects that were in the original — same identity, same `__traceback__`, same `__notes__`. Nothing about a member's annotation is at risk. * **rebuilds the group nodes**, including nested subgroups, so the derived tree mirrors only the matching part of the original shape. * **copies `__notes__` onto each derived group node.** Both the matched and the unmatched group come out carrying the same note strings in a *new* list. Equal contents, different list object — so appending a note to one part after the split does not touch the other part or the original. That copy is the detail worth knowing. It means group-level context — shard, batch, run identifier — is not lost when a handler peels off the errors it can deal with and re-raises the rest, and it means the two halves cannot accidentally share a mutable list. ## Reading notes programmatically If a predicate needs to inspect notes, remember the attribute is absent until the first `add_note` call: ```python part = group.subgroup(lambda e: any(n.startswith("record_id=") for n in getattr(e, "__notes__", []))) ``` `subgroup` returns `None` when nothing matches, so there is no group to carry notes at all in that case. And filtering on note *text* is a smell: notes are free-form strings for humans. If code must select members by identity, put the identifier on the exception as an attribute and let the note carry the human-readable version of the same fact. ## How it renders Group tracebacks are a tree, and notes attach to whichever node owns them: ``` | ExceptionGroup: decode failures (3 sub-exceptions) | shard=7 +-+---------------- 1 ---------------- | UnicodeDecodeError: 'utf-8' codec can't decode byte 0xff in position 0: invalid start byte | record index 0 +---------------- 2 ---------------- ``` The group's own notes sit directly under its header line; each member's notes sit under that member's final error line, inside the member's indented branch. Nothing is merged or hoisted, so a reader can see at a glance which context is per-batch and which is per-record. ## Operational payoff and limits The payoff is that one raised object carries the whole failure report: how many failed, of what kind, and which inputs. A handler upstream can `except*` the class it knows how to retry, keep the annotated members for a quarantine queue, and re-raise the rest with their group note intact. The limits are the same as for notes generally. They are strings, so they cost memory for as long as the exception lives — with a large working set, note the record identifier, never the record. They are rendered verbatim wherever the traceback goes, so no secrets. And they are not a routing mechanism: use the exception type and attributes for control flow, and let the notes explain the failure to whoever reads it at three in the morning.