PyAsm

A Python based language that reads like assembly. PyAsm reads disassembled Python (the exact text dis prints) and runs it.

$ cat main.pya
LOAD_GLOBAL 1 (print + NULL)
LOAD_CONST 0 ('Hello, World!')
CALL 1
POP_TOP
LOAD_CONST 1 (None)
RETURN_VALUE

$ pyasm main.pya
Hello, World!

Install

$ pip install -e .

Python 3.11 or newer. No dependencies. Without installing, every command below also works as python -m pyasm.

Usage

$ pyasm main.pya                            # assemble and run
$ pyasm run main.pya --dump-python out.py   # run, and save the generated Python
$ pyasm dump main.pya -o out.py             # only write the generated Python
$ pyasm check main.pya                      # assemble to verify, then stop
$ pyasm dis script.py -o script.pya         # disassemble Python into assembly
$ pyasm opcodes                             # list the opcodes PyAsm understands

Shared flags: --dump-python PATH (-d, or -o on dump) writes the generated Python, with - meaning stdout; --no-comments leaves the original instructions out of it; --entry-point NAME renames the generated entry point.

Exit codes: 0 success, 1 the assembled program itself failed, 2 the file could not be assembled.

Errors

Failures are reported against the assembly you wrote, never against the generated Python, at run time as well as at assembly time:

$ pyasm hi.pya
hi.pya:3: RuntimeError: stack underflow, needed 2 values
    CALL 1
    ^^^^^^

A failure raised inside the runtime, or inside a function your program called, is attributed to the instruction that led to it. pyasm run --traceback prints the Python traceback through the generated module underneath, for when the generator itself is the suspect.

--dump-python

PyAsm assembles by translating: every program becomes an ordinary Python module that walks the same value stack the interpreter would. --dump-python writes that module out. It carries its own runtime, so the result is a standalone script with no dependency on PyAsm:

$ pyasm dump main.pya -o hello.py && python hello.py
Hello, World!

def _pyasm_main(_ns):
    _st = []
    # LOAD_GLOBAL 1 (print + NULL)
    _st.append(_pyasm_load_name(_ns, 'print'))
    _st.append(NULL)
    # LOAD_CONST 0 ('Hello, World!')
    _st.append('Hello, World!')
    # CALL 1
    _st.append(_pyasm_call(_st, 1))
    ...

Straight-line programs become straight-line Python. Programs with jumps become a dispatch loop with one case per basic block, so labels and backward jumps work without any goto.

Syntax

Every field except the opcode is optional, so real dis output pastes in unchanged:

[lineno] [label:] [>>] [offset] OPCODE [arg] [(argrepr)]

   3   L1:    22  FOR_ITER          12  (to L2)     # straight from dis
              46  JUMP_BACKWARD     14  (to L1)

Hand written assembly can drop the bookkeeping and name things directly. # and ; start a comment.

        LOAD_CONST 3            ; a bare number is the constant itself
        STORE_NAME n

loop:   LOAD_NAME n             ; labels are easier than byte offsets
        POP_JUMP_IF_FALSE done
        LOAD_NAME print
        PUSH_NULL
        LOAD_NAME n
        CALL 1
        POP_TOP
        LOAD_NAME n
        LOAD_CONST 1
        BINARY_OP (-)
        STORE_NAME n
        JUMP_BACKWARD loop

done:   RETURN_CONST (None)

The value in parentheses is what PyAsm actually uses: the name to look up, the constant to push, the operator to apply. A text file has no constant or name table to index into. Jump targets are taken from a label (JUMP_BACKWARD 14 (to L1), or just JUMP_BACKWARD loop) or from a byte offset ((to 22)).

Both calling conventions are understood: the NULL marker may sit either side of the callable (print + NULL or NULL + print), and 3.13-style END_FOR is told apart from 3.14-style POP_ITER automatically.

Examples

Library

import pyasm

pyasm.run_file("main.pya")                       # assemble and run
source = pyasm.assemble_file("main.pya").python_source
assembly = pyasm.disassemble_file("script.py").text

assemble() returns an AssemblyResult holding the parsed Program, the generated python_source, any warnings, and a line_map from generated line back to instruction. result.describe_error(exc) uses that map to turn an exception into an ExecutionError carrying the .pya location, which is what the CLI renders.

Scope

PyAsm assembles one flat code object from text, which leaves two things out:

• Exception handling. try/except is driven by a code object's exception table, and text disassembly does not carry one. Handler blocks that only the exception table could reach (the tails CPython emits after comprehensions, for instance) are replaced by a stub and reported as a warning, so those programs still assemble and run. RAISE_VARARGS works; exceptions propagate to the caller.
• Nested code objects. def, class and lambda compile to separate code objects that dis prints as <code object f ...>, which cannot be rebuilt from their repr. pyasm dis warns when it sees one.

Everything else in common use is supported: constants, names, fast locals, attributes and methods, subscripts and slices, all binary and comparison operators, calls (positional, keyword, *args, **kwargs), list/tuple/set/dict construction, comprehension bodies, f-strings, imports, unpacking, and the full jump and FOR_ITER family. pyasm opcodes prints the current list.

LOAD_DEREF and STORE_DEREF are treated as ordinary locals, since a flat code object has no cells.

Development

$ python -m unittest discover -s tests    # or: pytest

The pieces: parser.py turns text into instructions, codegen.py turns instructions into Python, runtime.py holds the prelude that generated files carry, disassembler.py goes the other way, and cli.py is the front end.