Fine-Grained Source Locations

Through Python 3.10 a traceback frame told you a file, a line number and the text of that line. On a line such as `return sched["legs"] / sched["hours"]` that leaves three plausible culprits - two subscripts and a division - and no way to choose between them. PEP 657, shipped in **Python 3.11**, closed the gap. The compiler now records for every bytecode instruction not just a line number but a **start line, end line, start column and end column**, and the default exception display uses those columns to draw an anchor beneath the printed source: ``` File "differ.py", line 2, in rate return sched["legs"] / sched["hours"] ~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~ ``` ### Reading the anchor The two symbols have two jobs. The `~` characters span **the whole expression that was being evaluated**. The `^` characters sit under **the specific operation that raised**. In the example the division is the failing operation, and the two dictionary lookups are its operands, so the operator gets the caret and the operands get tildes. For a call, the callee is tilded and the parenthesised argument list is caretted - that is why `rate({...})` in the calling frame shows `~~~~^^^^^^^^`. For a subscript that raises `KeyError` the carets land on the brackets and the key. For a bare name that is not defined, the carets cover just the name. There is one rule that surprises people: **if the anchor would cover the entire displayed expression, CPython omits the anchor line altogether.** A row of carets under everything communicates nothing, so a frame whose whole line failed shows source with no marks under it. That is normal output, not a missing feature. ### Where the data lives The column offsets are stored in the code object, in a compressed table alongside the line-number table. Nothing decodes that table while your program runs - it is consulted only when something asks for a position: a traceback being displayed, a debugger, a coverage or profiling tool. So the feature has no per-instruction execution cost. Its real cost is space: larger `.pyc` files and more memory held by the code objects of a large codebase. Any tool can read the same data. `dis.get_instructions()` yields instruction records whose `positions` field carries exactly the four numbers the traceback uses, which is a useful way to convince yourself the anchor is derived data rather than heuristics over source text. ### Turning it off, and why you usually should not Because the cost is space, CPython offers an opt-out: start the interpreter with `-X no_debug_ranges`, or set `PYTHONNODEBUGRANGES=1` in the environment. Both keep the source line in the traceback and drop the anchor line under it. The switch also affects code compiled while it is in effect, so a `.pyc` written under it stays position-free until it is regenerated. The trade is bad in most deployments: you are saving a small amount of memory by giving up the diagnostic that most shortens an incident. Reach for it only in genuinely memory-constrained images, and know that you have made every future traceback vaguer. ### It is a display-time enrichment This is the part that bites in real systems. The anchor is computed while the exception is being *rendered*; it is not part of the exception's message. `str(exception)` for a `ZeroDivisionError` is still `"division by zero"` with no hint of which division. A service that catches an exception and logs only its message therefore throws away the column information the interpreter went to some trouble to record. If you want the precision, the rendered traceback is what has to reach your log store. ### Why it matters in practice The anchors pay off exactly where line numbers stop helping: chained lookups (`legs[i]["dep"]`), one-line comprehensions, arithmetic over several dictionary reads, and calls nested inside calls. A schedule differ that computes `legs[i]["dep"] - legs[i - 1]["arr"]` will, on bad input, tell you whether the missing key was the departure or the arrival - which used to require adding a print statement and reproducing the failure. Since **Python 3.13** the interpreter also colours the traceback when it believes it is writing to a terminal, and the anchor is one of the things it highlights, so on a developer machine the failing operation is picked out twice: by position and by colour.