What does traceback.extract_tb() return, and when do you want it over rendered text?

### From a traceback object to data A traceback object is a linked list of frames, and it is awkward to work with directly. `traceback.extract_tb(tb)` walks it once and gives you a `StackSummary`. The input is the traceback: `exc.__traceback__` if you are holding the exception, or the third member of `sys.exc_info()` inside a handler. There is a sibling, `traceback.extract_stack()`, that does the same for the *current* call stack with no exception involved — useful for answering "who called me?" in a diagnostic hook. ### What a FrameSummary carries Each element is a `FrameSummary` with four fields you will actually use: - `filename` — the source file as recorded in the code object. - `lineno` — the line executing in that frame. - `name` — the function or method name. - `line` — the stripped source text of that line. The critical property is what a `FrameSummary` does **not** hold: the live frame. It is a flat snapshot, so keeping one does not pin the frame's local variables and everything they reference in memory. That is the difference between a summary you can safely put in a list and a raw traceback you cannot. `line` is not stored in the traceback — it is looked up from the file via the `linecache` module at extraction time. So it is empty for code that was `exec`'d or typed at the REPL, and it is *wrong* rather than missing if the file changed between the failure and the extraction. That is the main reason to extract early rather than late. ### Ordering A `StackSummary` is ordered oldest call first, innermost last — the same order the printed report uses. So `frames[-1]` is where the exception was actually raised and `frames[0]` is your entry point. Grouping failures by `frames[-1].filename` and `frames[-1].name` is the cheapest useful fingerprint you can compute, and it is why the summary form matters: you cannot group on a blob of rendered text without parsing it back. ### Why you would prefer this to rendered text In a pipeline that ingests logs, a traceback rendered as one multi-line string is close to useless as data. It breaks line-oriented log shipping, it cannot be indexed, and two identical failures with different line numbers in a vendored dependency look like different strings. Extracting the frames instead lets you: - emit `file`, `line` and `func` as separate structured fields, one object per frame; - filter frames whose `filename` sits outside your own package, so a five-frame report is not buried under thirty frames of framework plumbing; - compute a stable fingerprint from the innermost frames for deduplication; - keep the full report as a secondary field for a human, generated with `StackSummary.format()` after the filtering. A worked case: an overnight batch of a log-ingest pipeline raises hundreds of failures across a 27-minute run, most of them the same clock-skew artefact hitting the same parsing frame. Rendered as text they are hundreds of distinct log entries; extracted and fingerprinted by the innermost frame, they collapse into one entry with a count — and the two genuinely different failures underneath finally become visible. ### Rendering back `StackSummary.format()` returns a list of strings for the frames, matching the frame section of an ordinary report, and `StackSummary.from_list()` builds one from plain tuples if you are reconstructing frames received over the wire. Note that a `StackSummary` covers the **frames only** — it has no exception type or message, so a report built from one must add that line itself, typically from `traceback.format_exception_only()`. ### The lower-level door `traceback.walk_tb(tb)` yields `(frame, lineno)` pairs, and `StackSummary.extract()` consumes such an iterator — `extract_tb` is essentially those two composed. Reach for the pair when you need to inspect the live frames themselves before they are summarised; use `extract_tb` for everything else. ### The current stack, without an exception `traceback.extract_stack()` returns the same kind of `StackSummary` for the call stack executing right now, no exception required. It is how a diagnostic helper answers "who called me?" — a deprecation shim recording its callers, or an audit hook noting where a sensitive call originated. The caveat is cost and size: the current stack in a framework can be dozens of frames deep, each one triggering a source lookup, so it is a debugging and instrumentation tool rather than something to call on a hot path. ### Keep the summary, drop the traceback One more reason to extract rather than retain: a `StackSummary` is plain data. If you need to remember where something failed — for the rest of a batch, or long enough to write a report — the summary is safe to keep, while holding the traceback object keeps the live frames and their locals alive with it.