A code object records which source line each instruction came from in its
co_lnotab table. It is used for tracebacks and for line tracing.
The co_lnotab table
co_lnotab is a bytes object holding pairs of bytes. The
first byte of a pair is how far the address moves on, in bytes of
co_code. The second is how far the line number moves on. Both are
unsigned, so neither can go down.
To find the line of an instruction, start with address 0 and line
co_firstlineno. For each pair, add the first byte to the address. If the
address has now gone past the instruction, stop: the line so far is its line.
Otherwise add the second byte to the line and go on.
A step too big for one byte is spread over several pairs. CPython’s
Objects/lnotab_notes.txt says the line step stays 0 in each pair until
the remaining address step is under 256. So a step of 300 bytes and 3 lines is written
as FF 00 2D 03.
Worked example
This example is constructed by hand from the rules above, with no Python 3.0 to 3.2 running it here. It is a three-line function, leaving out the code that follows its last statement.
1 def f(a):
2 x = a
3 return x| Offset | Bytes | Instruction |
|---|---|---|
| 0 | 7C 00 00 | LOAD_FAST 0 |
| 3 | 7D 01 00 | STORE_FAST 1 |
| 6 | 7C 01 00 | LOAD_FAST 1 |
| 9 | 53 | RETURN_VALUE |
co_firstlineno is 1, the line of the def. The first
statement is on line 2 at offset 0, so the first pair is 00 01. The
second starts at offset 6, six bytes on and one line on, so the table is
00 01 06 01.
Reading it back, the first pair moves to offset 0 and line 2, and the second to offset 6 and line 3. Offsets 0 to 5 are line 2 and offsets from 6 are line 3.