Disassemble Python Bytecode and Match to CPython Source

Topic Overview

Disassembling Python Bytecode

The \`dis\` module prints the opcodes CPython will execute. Pairing \`dis\` output with \`Python/compile.c\` and \`ceval.c\` is how you learn what the compiler actually emitted.

Reading dis Output

Each line shows offset, opcode name, and argument:

• \`LOAD_CONST\`: push a value from the code object's constant tuple
• \`LOAD_FAST\`: read a local by index
• \`CALL\`: invoke the callable on the stack (CPython 3.11+ uses specialized forms)

For example, \`def add(a, b): return a + b\` disassembles to loads of \`a\` and \`b\`, \`BINARY_OP\` or \`BINARY_ADD\`, then \`RETURN_VALUE\`.

Match opcodes to compiler phases:

1. AST from \`compile.c\`
2. Bytecode in \`co_code\`
3. Handlers in \`ceval.c\`

Design Notes

Specialized opcodes in CPython 3.11+ replace generic forms for common patterns. When dis output shows `CACHE` lines, you are looking at the adaptive specialization machinery, not user bytecode.

For This Exercise

This exercise asks you to disassemble sample functions and map opcodes to CPython source concepts. You will document how \`dis\` reveals the stack operations behind familiar Python syntax.

You will use the same mental model here when reading production interpreter source later in the track. Sketch one concrete input on paper, predict the outcome, then confirm with code. That discipline catches logic errors early and makes debugging far faster when you extend the implementation in follow-on tasks.

Your Task

Build a mini CPython 3.8 compiler plus dis. Read Python functions, compile them to 3.8 bytecode with 3.8's rules for locals, globals, constants and jumps, and print the disassembly exactly as dis.dis does. Then print the code object's co_consts, co_varnames, co_names and co_stacksize.

Input

One or more top-level def NAME(PARAMS): blocks, indented with spaces. Blank lines and # comments are allowed, and line numbers count every input line from 1.

Statements:

• x = EXPR
• return [EXPR]
• EXPR (usually a call)
• if EXPR: ... [else: ...]
• while EXPR: ...
• pass

Expressions, from lowest to highest precedence:

• one optional comparison (< <= == != > >=);
• + -;
• * // %;
• unary -;
• then integers, names, calls f(a, b) and parentheses.

Compilation rules

• Scope: parameters, then every assigned name (in order of first assignment), form co_varnames. These use LOAD_FAST/STORE_FAST, even when a read comes before the assignment. Any other name is a global: LOAD_GLOBAL, collected in co_names by first use.
• Constants: co_consts[0] is None, and the others are added on first use without duplicates. Arithmetic on two constants, and unary minus on a constant, is folded at compile time (Python floor semantics for // and %). A division by a literal 0 is left unfolded.
• Opcodes: BINARY_ADD/SUBTRACT/MULTIPLY/FLOOR_DIVIDE/MODULO, UNARY_NEGATIVE, COMPARE_OP i with i indexing ('<','<=','==','!=','>','>='), CALL_FUNCTION argc after the callee and the arguments, POP_TOP after an expression statement, and RETURN_VALUE.
• if: test; POP_JUMP_IF_FALSE else; body; JUMP_FORWARD end; else: orelse; end:. Without else, the false jump goes straight past the body.
• while: top: test; POP_JUMP_IF_FALSE end; body; JUMP_ABSOLUTE top; end:.
• Offsets and jumps: instruction i is at offset 2i. POP_JUMP_IF_FALSE and JUMP_ABSOLUTE take absolute targets. JUMP_FORWARD takes a delta from the next instruction, shown as (to T).
• Implicit return: if the body's last top-level statement is not return, append LOAD_CONST None; RETURN_VALUE.
• Line numbers: each statement's code belongs to the statement's line. Loop and branch jumps, and the implicit return, carry the line of the most recently compiled statement. No peephole optimization.
• co_stacksize: the maximum stack depth in a straight pass over the code.

Output

cCopy
Loading…

Each instruction line follows dis:

• the line number in a width-3 field, only on the first instruction of a new line (a blank line precedes it, except at offset 0);
• then 5 spaces, >> for a jump target or 2 spaces, a space, and the offset in a width-4 field;
• then a space, the opname padded to 20 columns;
• then, if there is an argument, a space, the argument in a width-5 field, and (repr) for constants, names, comparisons and JUMP_FORWARD.

Trailing spaces are dropped. Separate functions with a blank line, printed before each function after the first, even if that function then fails to compile. Print tuples Python-style: (None,) and ('n',).

A syntax error prints SyntaxError: line N: MSG and stops the whole run. Functions already printed stay printed. The messages are:

• invalid syntax
• expected an indented block
• unexpected indent
• unindent does not match any outer indentation level
• duplicate argument in function definition
• expected 'def' at the top level

Example

Input:

cCopy
Loading…

Output:

cCopy
Loading…

Requirements

1. Build the AST first, and collect the assigned names before generating code. That is how CPython's symbol table decides local versus global.
2. Patch jump arguments once the target offset is known.

Hidden tests cover nested if/else with JUMP_FORWARD, constant folding (including a division by zero that is left alone), a local read before assignment, pass, a bare return, a while at the end of a function, and an indentation error.