From source to bytecode: the six steps Python takes before the first instruction

Nobody executes your text

There is a common picture: Python reads the file line by line and does what is written. That is not Python — that is a very simple calculator.

In reality there is a translator between your file and the work. It reads the text once, whole, takes it apart, and produces a list of short commands, each doing exactly one simple thing: "push the value of this variable", "get this attribute from this object", "add the top two values".

From then on it is the commands that run. Nobody reads the text again.

Six stations on the conveyor

The translator does not work in one go — it works in steps, and each step turns the material into something else.

• Text. Just a string of characters.
• Words. The text is cut into pieces: def, f, (, a, ). For each one, where it stood — line and column — is remembered. That will matter right at the end.
• Tree. The list of words becomes a structure: here is a function, it has a name, a list of arguments and a body, and the body returns a sum.
• List of names. A separate pass decides, for every name, whether it belongs here or came from outside. Here, not at run time.
• Tidying up. Everything that can be worked out in advance is worked out in advance; everything unreachable is thrown away.
• Commands. Whatever is left is what runs.

Switch the tabs on the diagram below — it holds the real output of each step for one small function.

Tidying up is fairly generous

Some things can be computed without running the program at all. Python does compute them.

def g():
    return 2 + 3 * 4

There is no multiplication in the finished commands — there is the number 14 right away. The multiplication happened once, during translation.

The same fate meets:

• code after return — it is unreachable anyway;
• an if False: branch, along with everything inside it;
• adjacent quoted strings: 'a' 'b' 'c' becomes the single string 'abc'.

Hence a practical conclusion: hoisting 2 + 3 * 4 into a variable "so it is not recomputed every time" is wasted effort. It was never being recomputed.

def f(a): return a.x + 1

Six commands, sixteen cells

Here is the number that surprises people. For one line,

def f(a): return a.x + 1

you get six commands. And they take up as much room as sixteen.

Ten cells are empty. They are scratch space: while the program runs, Python watches what actually happens — what type the object is, where its attribute lives — and writes down what it saw in those cells. Next time the same work can be skipped.

The command that asks for the most scratch space is "get an attribute" — nine cells. That is not an accident: attribute access is the most frequent operation in Python, so it is the first thing worth making faster.

Where the coordinates of words end up

Remember that at the second step, where every word stood was recorded? That is not bookkeeping for its own sake.

def boom(a, b, c, d):
    return a.x + b.y * c.z - d.w

If d turns out not to be what was expected, Python shows:

    return a.x + b.y * c.z - d.w
                             ^^^
AttributeError: 'NoneType' object has no attribute 'w'

The carets sit exactly under d.w — not under the whole line, even though there are four attribute accesses in it. The coordinates written down at the very beginning made it to the end and surfaced at the moment of the error.

It is not free: the files of ready-made commands for the standard library grew 22% because of this. Python's developers decided a precise caret was worth it.

Why a variable can be "already local"

That step with the list of names explains a famous puzzle:

x = 10
 
def f():
    print(x)   # UnboundLocalError
    x = 5

It looks as if x = 5 has not been reached yet, so print(x) should pick up the outer x. But the decision about local versus outer is made not at run time — it is made at the fourth step of the conveyor, during translation, when the whole function is visible at once.

If there is an assignment anywhere in the body, the name is local for the entire function, including the lines above the assignment. By run time there is nobody left to argue with.

Three things worth remembering

Translation happens once. When the file is loaded, not on every call.

Some of the work is done in advance. Arithmetic on constants, joining string literals, dropping unreachable code — all before the start.

The empty cells are not waste, they are a workbench. They are exactly where the interpreter puts what it noticed, so that the second time round it can work faster.

Why bother?

Almost everything that happens later in the runtime rests on the code object. Until you can see that there are more instructions than lines, and more cells than instructions, there is nothing to hang a conversation about specialisation or the attribute cache on: it is an instruction that specialises, and the cache lives in exactly those cells.

There is a practical side too. This is where it becomes clear why UnboundLocalError happens on a line where the variable "obviously exists", why a traceback in 3.11+ points at the precise sub-expression, and why code that looks identical sometimes compiles to a different number of instructions.

The honest place to start is the warning that opens the dis documentation:

Everything below is about CPython, and about specific versions. None of these numbers is part of the language.

The model to hold in your head

Python's compiler is a pipeline, not a function. The text passes through six stations, and at each one it stops being what it was.

1. Source text — a string of bytes.
2. Tokens — words with coordinates.
3. Tree — structure instead of sequence.
4. Symbol table — who is local here and who is global.
5. Graph and optimisations — whatever can be dropped is dropped.
6. Code object — the thing that runs.

The key property of the pipeline: the coordinates from step 2 survive to step 6. The line and column recorded during tokenisation end up in the code object and, years later, surface in a traceback as a caret under the right character.

Five of the six steps are observable from Python itself — there is a module that shows each. The sixth, the control-flow graph, is observable through nothing at all, and that is worth saying plainly rather than drawing an "approximate diagram".

def f(a): return a.x + 1

What is actually visible at each step

Tokens come from tokenize. Fourteen of them for one line, each with a pair of coordinates. Those coordinates are what PEP 657 is about.

The tree comes from ast.parse. Note the ctx=Load() on Name and Attribute: reading and writing are already different things here, long before any bytecode. Different opcodes will grow out of that difference later.

The symbol table comes from symtable — a module few people remember, though it shows the least obvious pass in the compiler. A separate walk over the tree, entirely before code generation, decides for every name whether it is local, global, or captured from an enclosing scope. For our function:

>>> st = symtable.symtable("def f(a): return a.x + 1", "<s>", "exec")
>>> f = st.get_children()[0]
>>> f.get_parameters()
('a',)
>>> [(s.get_name(), s.is_local(), s.is_parameter()) for s in f.get_symbols()]
[('a', True, True)]

This, not the runtime, is where LOAD_FAST instead of LOAD_GLOBAL comes from. And it is where UnboundLocalError comes from. That can be shown rather than told:

x = 10
 
def f():
    print(x)   # UnboundLocalError
    x = 5

>>> st = symtable.symtable(open("unbound.py").read(), "unbound.py", "exec")
>>> for s in st.get_children()[0].get_symbols():
...     print(s.get_name(), s.is_local(), s.is_global())
print False True
x     True  False

x is marked local at parse time, before a single line has run — and it is marked local for the whole function, print(x) above the assignment included. By runtime there is nobody left to argue with:

  File "unbound.py", line 4, in f
    print(x)
          ^
UnboundLocalError: cannot access local variable 'x' where it is not associated with a value

The same table also marks print as is_global. Hence the different opcodes — and the old advice to put a builtin in a local variable before a hot loop. The advice is checkable, so let us check it (3.13.7, minimum of seven runs of 2,000,000 calls):

1.36 ns, about 10%. The difference is real and reproducible — but this is one of those cases where the right conclusion from a number is the opposite of the expected one: a trick passed around as a notable optimisation buys one and a half nanoseconds per call. Not worth spoiling readability for.

The code object: six instructions, sixteen cells

Now the central number of this article.

>>> def f(a): return a.x + 1
>>> len(list(dis.get_instructions(f)))
6
>>> len(f.__code__.co_code) // 2
16

Six and sixteen. The difference is neither a bug nor padding: ten cells are the inline cache, room an instruction reserves for its own notes about what it has already seen.

LOAD_ATTR reserves nine cells, BINARY_OP one. The whole table is visible without reading any C:

>>> import opcode
>>> {k: v for k, v in sorted(opcode._inline_cache_entries.items()) if v}
{'BINARY_OP': 1, 'BINARY_SUBSCR': 1, 'CALL': 3, 'COMPARE_OP': 1, ...
 'LOAD_ATTR': 9, 'LOAD_GLOBAL': 4, 'STORE_ATTR': 4, 'TO_BOOL': 3, ...}

The leading underscore is a warning: private, changes between versions. Which is exactly what happens — on 3.14 BINARY_OP is already 5.

Why this matters beyond arithmetic. Specialisation — the subject of the next article — works by having an instruction rewrite itself into a specialised variant and stash its observations in these very cells. Until you know the cells exist, specialisation looks like magic.

The coordinates that made it to the end

PEP 657 added four numbers per instruction to the code object: start and end line, start and end column. Visible through co_positions(), and it works like this:

class O: pass
 
def boom(a, b, c, d):
    return a.x + b.y * c.z - d.w
 
o = O(); o.x = 1; o.y = 2; o.z = 3
boom(o, o, o, None)

On 3.12.3:

  File "pep657.py", line 4, in boom
    return a.x + b.y * c.z - d.w
                             ^^^
AttributeError: 'NoneType' object has no attribute 'w'

The caret sits under d.w, not under the whole line — even though the line has four attribute accesses and three operations. Those are the coordinates recorded during tokenisation.

On 3.13.7 the same program also gets carets on the call line:

    boom(o, o, o, None)
    ~~~~^^^^^^^^^^^^^^^

The price is named in the PEP itself and not hidden: the standard library's pyc files grew 22%, from 28.4 to 34.7 MB. Traceback precision is paid for in disk and memory, and it is a deliberate trade.

What the optimiser does

Step five is the only one invisible from Python entirely. No module, no flag: the control-flow graph lives inside compile.c, between _PyAST_Compile (line 442 at tag v3.13.7) and optimize_and_assemble (line 7689), and is never exposed.

Its consequences, though, are fully measurable. Everything below is a real co_consts and a real opcode sequence on 3.13.7:

The NOP left where the if used to be is not junk. PEP 626 requires every executable instruction to carry a line number and requires lines that did execute not to vanish from the debugging information; the NOP keeps that bookkeeping straight.

Note what the table does not contain: not one optimisation that reorders computation or drops an attribute access. Python's compiler deliberately knows almost nothing about values — everything interesting happens later, in the interpreter.

What changed in 3.12, 3.13 and 3.14

The numbers come from one script (bench/bytecode_bench.py) run on one function.

The trap is in the second-to-last row. HAVE_ARGUMENT fell from 90 to 44, which reads easily as "fewer instructions take an argument". The last row says the opposite: there are more of them, 101 → 107. HAVE_ARGUMENT is simply a boundary in the opcode numbering, and its move means the numbering was rearranged, not that anything got simpler. A number that means nothing on its own is a good reason to distrust one-line version comparisons.

What is honestly unexplained. On 3.14 co_consts became (1,) instead of (None, 1), and the disassembler shows LOAD_SMALL_INT where LOAD_CONST used to be. The fact is measured; I have not read the reason in flowgraph.c, so there is no explanation here. If you meet an article that explains it confidently in two sentences, it is worth checking where that came from.

About the documentation. CPython's compiler does have internal docs — InternalDocs/compiler.md, code_objects.md, parser.md. Checked by request against both tags: on v3.14.0 all three return 200, on v3.13.7 they return 404. In 3.13 the InternalDocs/ directory holds exactly one file, string_interning.md. So an article about the 3.13 compiler has to read the code rather than a document, and any citation of InternalDocs/compiler.md for 3.13 is a citation of something that does not exist.

What to do about it

Do not count instructions from dis output. It shows six where memory holds sixteen cells. For "how much does this take" there is len(co_code), and for "how much in total" there is sys.getsizeof.

Do not compare versions by a single number. HAVE_ARGUMENT is a live example of a value that halved without changing meaning.

Do not optimise what the compiler already folded. 2 + 3 * 4, adjacent string literals, tuples of constants, not not — each is already one constant or one operation. Hoisting them into a variable "for speed" is wasted work.

Remember that names are decided before execution. An assignment anywhere in a function body makes the name local for the entire function — a decision of the symbol table, not of the runtime. Hence UnboundLocalError on a line that comes before the assignment.

And the part that matters for what comes next. Those ten empty cells are not overhead, they are a workbench. In the next article the interpreter starts filling them in.