pyssa

A Python IR with pluggable execution semantics.

Motivation

pyssa is motivated by two use cases:

1. a Python-version-agnostic bytecode-like IR for analysis
2. custom interpreters that mostly behave like Python, but intentionally diverge in specific places

It lowers Python AST into an explicit control-flow IR with nested regions, basic blocks, and ordinary operations. The goal is a stable, executable semantic IR that is easier to analyze, easier to transform, and easier to reinterpret with custom execution rules.

Installation

pip install pyssa-ir

The distribution is named pyssa-ir; the import package remains pyssa.

Dependencies:

• Python 3.6+ (newer syntax can be lowered when it is supported by the running Python parser)
• attrs
• cowlist
• typing_extensions

Quickstart

Subclass BaseFrame and override the dispatch_* methods you need. Unhandled instructions will raise NotImplementedError. BaseFrame provides block navigation, name resolution, and a dispatch loop.

Name resolution methods:

• load_name(self, scope: Scope, name: str) -> Any
• store_name(self, scope: Scope, name: str, value: Any) -> None
• delete_name(self, scope: Scope, name: str) -> None
• has_name(self, name: str) -> Optional[Scope]
• load_builtin(self, name: str) -> Any

from pyssa.compiler import compile_source, new_compiler_state
from pyssa.ir import BinaryOperator, print_region_ir
from pyssa.interpreter import BaseFrame, make_frame, NextInstructionEvent, ReturnEvent


# 1 ── compile Python source into a pyssa IR region ────────────────────────

source = "result = x + y"
module_ir = compile_source(new_compiler_state(), source, path="<tiny-add>")

# Inspect the bytecode-like IR before execution.
print_region_ir(module_ir)
#   region <module> entry=L0
#     block L0:
#       t0 = LoadName(scope=<Scope.NAME: 'name'>, name='x')
#       t1 = LoadName(scope=<Scope.NAME: 'name'>, name='y')
#       t2 = BinaryOp(op=<BinaryOperator.ADD: '+'>, lhs=t0, rhs=t1)
#       StoreName(src=t2, scope=<Scope.NAME: 'name'>, name='result')
#       t3 = Const(value=None)
#       Return(value=t3)


# 2 ── define a custom interpreter frame ───────────────────────────────────

class TinyAddOnlyFrame(BaseFrame):
    """A custom interpreter that only understands addition."""

    def __init__(self, region_ir, globals, locals, cells,
                 block_label, instr_index, finished, return_value):
        super().__init__(region_ir, globals, locals, cells,
                         block_label=block_label, instr_index=instr_index,
                         finished=finished, return_value=return_value)
        self.temps = {}    # map temporaries to values

    def dispatch_const(self, instr):
        self.temps[instr.dst] = instr.value
        return NextInstructionEvent()

    def dispatch_load_name(self, instr):
        self.temps[instr.dst] = self.load_name(instr.scope, instr.name)
        return NextInstructionEvent()

    def dispatch_store_name(self, instr):
        self.store_name(instr.scope, instr.name, self.temps[instr.src])
        return NextInstructionEvent()

    def dispatch_binary_op(self, instr):
        if instr.op != BinaryOperator.ADD:
            raise NotImplementedError(
                "TinyAddOnlyFrame only supports addition"
            )
        self.temps[instr.dst] = \
            self.temps[instr.lhs] + self.temps[instr.rhs]
        return NextInstructionEvent()

    def dispatch_return(self, instr):
        return ReturnEvent(self.temps[instr.value])


# 3 ── create a frame from the IR region and step through instructions ─────

add_frame = make_frame(
    TinyAddOnlyFrame,
    module_ir,
    globals={"x": 2, "y": 3},
)

while not add_frame.finished:
    instr = add_frame.get_current_instruction()
    print(f"  [{type(instr).__name__}]")

    event = add_frame.dispatch_current_instruction()
    if isinstance(event, ReturnEvent):
        break   # frame is done

print(add_frame.locals["result"])     # 5

IR overview

The IR is defined in terms of a small set of core classes:

• Region — a named executable unit with its own CFG: labeled BasicBlocks, nested child_regions, and metadata (locals, cells, freevars, argument descriptors, exception handlers).
• BasicBlock — a straight-line sequence of Instructions with a BasicBlockLabel.
• Instruction — two families: ValueInstruction (produces a result in dst: TemporaryValue) and EffectInstruction (side effects only).
• Operands — TemporaryValue (SSA-style temporaries), BasicBlockLabel, RegionLabel, SyntheticLocal (compiler-generated locals), and UnpackedTemporaryValue (splat markers).
• Structured kinds — scopes, operators, comparisons, formatting conversions, synthetic-local purposes, type-parameter kinds, and code flags use enums rather than string or integer tags.

Case study: cyclomatic complexity three ways

Three versions of the same tool are included:

• cyclomatic_complexity.py: compute complexity from pyssa IR regions
• cyclomatic_complexity_ast.py: compute complexity directly from Python AST nodes
• cyclomatic_complexity_bytecode.py: compute complexity from CPython bytecode CFG recovery

Run them on the same input:

python cyclomatic_complexity.py ir_test_program.py
python cyclomatic_complexity_ast.py ir_test_program.py
python cyclomatic_complexity_bytecode.py ir_test_program.py

All three emit the same recursive JSON shape:

{
  "name": "<module>",
  "cyclomatic_complexity": 2,
  "child_regions": []
}

Result

The pyssa-based implementation is the smallest by LOC. With pyssa, the hard parts are already explicit in the IR:

• nested scopes are already nested as child_regions
• control flow is already split into basic blocks
• branches, jumps, and loop iteration edges are already explicit

AST lowering coverage

ASDL builtin leaf types

mod

stmt

expr

Supporting AST records