pythonrs 0.1.0

Python as a fusevm frontend: a lexer/parser and compiler to fusevm::Chunk on a PyHost object heap, with no bespoke VM or JIT — the first compiled standalone Python runtime
Documentation
██████╗ ██╗   ██╗████████╗██╗  ██╗ ██████╗ ███╗   ██╗██████╗ ███████╗
██╔══██╗╚██╗ ██╔╝╚══██╔══╝██║  ██║██╔═══██╗████╗  ██║██╔══██╗██╔════╝
██████╔╝ ╚████╔╝    ██║   ███████║██║   ██║██╔██╗ ██║██████╔╝███████╗
██╔═══╝   ╚██╔╝     ██║   ██╔══██║██║   ██║██║╚██╗██║██╔══██╗╚════██║
██║        ██║      ██║   ██║  ██║╚██████╔╝██║ ╚████║██║  ██║███████║
╚═╝        ╚═╝      ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝

CI Rust Docs license status

[PYTHON, COMPILED TO BYTECODE — rkyv-CACHED ON EVERY RUN, AOT-NATIVE]

"CPython compiles to its own bytecode and walks it. pythonrs lowers Python to a shared machine, caches the result on every run, and can bake a script into a native binary."

pythonrs is Python as a fusevm frontend — a lexer/parser and compiler that lowers Python 3 to fusevm::Chunk bytecode running on the fusevm three-tier Cranelift JIT, over a PyHost object heap. There is no bespoke VM and no bespoke JIT: pythonrs is a pure front end; execution and codegen live in fusevm — the same engine behind zshrs, strykelang, awkrs, vimlrs, elisprs, and rubylang.

It is, to our knowledge, the first compiled standalone Python runtime that both transparently caches bytecode via rkyv on every run and AOT-compiles a script to a native executable.

Read the Docs · Engineering Report · Builtin Reference


Table of Contents


[0x00] OVERVIEW

pythonrs keeps Python the language and throws away CPython's execution model. It lexes and parses Python to an AST, lowers the AST to fusevm bytecode, and runs the bytecode on a stack VM with a Cranelift JIT. Arithmetic and comparisons lower to native ops; Python-specific behavior — truthiness, str/list concat, bignum promotion, attribute and method dispatch — runs through a strict numeric hook and a numbered builtin-call protocol into the PyHost object heap.

Two things set it apart from every other standalone Python:

  • Transparent rkyv bytecode cache — on every run. python foo.py hashes the source, consults ~/.pythonrs/scripts.rkyv, and on a hit runs the compiled chunks directly with lex/parse/lower skipped entirely. No flags, no separate build step, no __pycache__ ritual.
  • AOT to a native executable. python --build foo.py emits a standalone native binary (via fusevm::aot, linked against the pythonrs runtime staticlib) that runs the script with no interpreter present.

[0x01] INSTALL

# Via the Homebrew tap (bumped by each release; formula is `pythonrs`)
brew install menketechnologies/menketech/pythonrs

# Or from source
git clone https://github.com/MenkeTechnologies/pythonrs
cd pythonrs && cargo build --release
# binary: target/release/python  (+ libpythonrs.a for AOT linking)

Zsh tab completion

cp completions/_python "${fpath[1]}/"
# or: fpath=(/path/to/pythonrs/completions $fpath) in .zshrc

[0x02] USAGE

python foo.py               # run a script (transparently rkyv-cached)
python -c 'print(1 + 1)'    # run a one-liner
python --build foo.py       # AOT-compile to a native ./foo executable
python --dump-bytecode f.py # print the lowered fusevm bytecode
python --repl               # interactive REPL
python --lsp                # Language Server Protocol over stdio

Set PYTHONRS_TRACE=1 to log cache hit/miss to stderr (silent otherwise).

[0x03] LANGUAGE FEATURES

Arbitrary-precision integers, real closures, classes with inheritance, operator dunders, generators (yield / yield from / lazy generator expressions, backed by stackful corosensei coroutines), match/case structural pattern matching, own-scope comprehensions (list/dict/set) and proper nonlocal, f-strings, exceptions, and full call-site and literal * / ** unpacking. The PyHost heap implements the str / list / dict / tuple / set / instance object model with the operator, attribute, item, and iteration protocols. See [0x07] and BUGS.md for the honest list of what is not yet implemented.

[0x04] COMMAND-LINE FLAGS

Flag Effect
(none) Run the script/one-liner, transparently rkyv-cached.
--build AOT-compile the script to a standalone native executable.
--dump-bytecode Print the lowered fusevm bytecode and exit.
--repl Start the interactive REPL.
--lsp Run the Language Server Protocol server over stdio.

[0x05] ARCHITECTURE

lexer  →  parser  →  AST  →  compiler  →  fusevm::Chunk  →  fusevm VM + JIT
                                              │                    │
                                              └── CallBuiltin ─────→ host (PyHost heap)
  • lexer.rs — indentation-significant tokenizer (INDENT/DEDENT/NEWLINE, f-strings).
  • parser.rs — recursive-descent Python grammar → ast.rs.
  • compiler.rs — lowers the AST to fusevm ops + CallBuiltin dispatches.
  • host.rs — the PyHost object heap (str/list/dict/tuple/set/instances/…), the operator/attribute/item/iteration semantics, and the fusevm run plumbing.
  • builtins.rs — the CallBuiltin handler table, the numeric hook, the Kernel builtin functions (print / len / range / …), and per-type methods.
  • cache.rs — the rkyv-shard bytecode cache.
  • aot_native.rs — native-executable emission via fusevm::aot.

[0x06] PARITY HARNESS

Correctness is measured, not asserted: an example corpus runs through both pythonrs and the reference python3, and the output is diffed byte-for-byte. pythonrs runs a large, real subset of Python 3, verified against CPython on that corpus.

Beyond the fixed corpus, the parity-fuzz binary is a differential fuzzer. It generates thousands of grammar-driven, deterministic-output snippets — biased toward the historically fragile areas (float repr, integer ///% sign rules, bignum, slices, the format mini-language, string methods) — runs each through python -c and the reference python3 -c, and reports every case where stdout or accept/reject diverges. Each case is seeded, so any divergence is delta-debugged to a minimal reproducer and replays exactly:

cargo build --bin parity-fuzz
./target/debug/parity-fuzz --count 5000          # fuzz every mode
./target/debug/parity-fuzz --formatspec          # one surface only
./target/debug/parity-fuzz --seed 51 --once      # replay + minimize one case

The generator never emits nondeterministic output, so every reported divergence is a real gap. PYTHONRS_FUZZ_PYTHON names the reference interpreter; a --baseline allowlist keeps known gaps from failing while new ones exit non-zero.

[0x07] STATUS & ROADMAP

Active, in development. The runtime executes a substantial real subset of Python 3. BUGS.md is the honest ledger of unimplemented features — async, bytes operations, and most of the standard library are not yet carried. A DAP debug adapter (--dap), man pages, and the generated reference.html land alongside the growing builtin surface.

[0x08] DOCUMENTATION

[0xFF] LICENSE

MIT.