How do you use add_note in an except handler to add context before re-raising?

The pattern interviews are really asking about is *enriching an error in flight*. A failure happens deep in a call stack, where the code knows the mechanism but not the business context; the layers above know the context — which record, which shard, which tenant — but not the mechanism. `add_note` lets each layer contribute what it knows to one exception object. ## The idiom ```python def load(record_id: int, raw: bytes) -> str: try: return raw.decode("utf-8") except UnicodeDecodeError as exc: exc.add_note(f"record_id={record_id}") raise ``` Three things make this work. The `as exc` binding is the **same object** that will keep propagating, so mutating it is not a copy-and-lose situation. `add_note` appends rather than replaces, so an outer layer can add `batch=night-rescore` on top of the inner `record_id=8842`. And the bare `raise` re-raises the exception currently being handled, preserving its class and traceback so every `except` clause above behaves exactly as it would have without your handler. ## Bare raise versus raise exc Both re-raise the same object and both carry the notes. The difference is cosmetic but visible: `raise exc` adds a traceback entry pointing at your `raise` line, so the rendered traceback shows the re-raise site before the original frames; a bare `raise` does not. Bare `raise` is the idiom, and it cannot accidentally raise the wrong name. ## The `as` name is deleted Python unbinds the `except ... as exc` name at the end of the block — it is compiled to an implicit `del exc` — so touching `exc` afterwards raises `NameError` (an `UnboundLocalError` inside a function). Annotate inside the block. If you genuinely need the object later, bind it to another name first (`err = exc`) before the block ends. ## Why not just wrap it Wrapping — catching a low-level error and raising your own type instead — is a contract change: callers who used to catch the original type now cannot, and readers of the traceback have a second exception to walk. That is sometimes exactly what you want, when the low-level type leaks an implementation detail your API should not promise. But when the type is right and only the *context* is missing, wrapping is a heavy tool. `add_note` adds the context and leaves the contract alone. The other alternative — logging at each layer — turns one failure into several log lines that only reassemble if your pipeline correlates them. A note travels attached to the object, so wherever the traceback is finally rendered, the whole trail is in one place. ## What to put in a note Consider a fraud-scoring service that re-scores a 2.4 GB working set of stored records overnight and hits an encoding mismatch on a handful of them. Useful notes are the record identifier, the shard or batch name, the codec that was attempted, the stage of the pipeline. Useless or dangerous ones are the record itself (it may be large, and a note is a string held for the lifetime of the exception), anything containing credentials or personal data, and anything a program is expected to parse back out. Notes are reproduced verbatim in every rendered traceback, every crash report and every ticket someone pastes into chat, so treat them as public and keep them short and greppable. ## Pitfalls **A reused exception instance accumulates notes forever.** If a module-level exception object is raised repeatedly — a pre-built sentinel, or an exception cached and re-raised — every annotation piles onto the same `__notes__` list, and the tenth failure shows ten stale lines. Build a fresh exception per failure, which is the norm anyway. **A retry loop double-annotates.** Annotating the same caught exception on each of three attempts leaves three near-identical notes. Add the attempt number if you want that, or annotate once at the boundary. **Notes are not a data channel.** Because `add_note` takes a string and nothing enforces its shape, it is tempting to encode structured context and parse it back in an outer handler. That is a fragile contract with no schema; if code must branch on the value, put it on the exception as an attribute and let the note carry the human-readable rendering. **Silent loss in string-formatted logs.** `logger.error("failed: %s", exc)` prints only the message. Use `logger.exception(...)` or format the traceback if you want the notes to reach the log. ## In review The pattern is small enough to spot in a diff: a handler that binds the exception, adds one short note, and re-raises bare. Anything that catches, logs, and swallows — or catches and re-raises a different type without a reason — is the thing to question.