// PYTHONRS — ENGINEERING REPORT

Summary

CPython compiles Python to its own bytecode and walks it in C. pythonrs takes a different path: it lexes and parses Python 3 to an AST, lowers that to fusevm bytecode, and runs it on a compiled VM with a Cranelift JIT. Arithmetic and comparison operators lower to native VM ops so the JIT can trace hot loops; Python-specific behaviour is served by a thread-local PyHost object heap through a numbered builtin-call protocol. It joins fusevm alongside zshrs, stryke, awkrs, elisp, and rubylang, and reuses that shared bytecode VM and JIT rather than shipping its own.

Two things set it apart from every other standalone Python: it transparently caches compiled bytecode via rkyv on every run (~/.pythonrs/scripts.rkyv; a hit skips lex/parse/lower), and it AOT-compiles a script to a standalone native executable via python --build. To our knowledge it is the first compiled standalone Python runtime to do both.

The current tree implements the lexer/parser, AST-to-bytecode lowering, the object heap and method dispatch (str, list, dict, tuple, set, instances), a growing Kernel-builtin and per-type-method surface, functions/closures/*args/**kwargs, user-defined classes with inheritance and operator dunders, list/dict/set comprehensions, f-strings, exceptions (try/except/finally/raise, with), arbitrary-precision int, generators (yield / yield from), async/await on a native event loop, match/case structural pattern matching, the standalone python binary and REPL, the transparent rkyv bytecode cache, AOT native-executable emission, and a glob-matched AOP method-intercept registry. The standard library arrives through the stdlib-ffi bridge to an embedded libpython (on by default). Behaviour is checked against the reference python3 by a differential parity harness and a differential fuzzer. The LSP and DAP surfaces are partial — see BUGS.md for the honest ledger.

Hosting on fusevm

pythonrs contains no virtual machine or JIT of its own. The execution path is:

Python source  →  lexer  →  parser → AST  →  lower to fusevm bytecode  →  fusevm VM + Cranelift JIT
                                                    │
                                       PyHost heap (str/list/dict/tuple/set/instances, CallBuiltin)

Value model

Immediate values — int (within i64 range), float, True/False, and None — ride through the VM directly as fusevm::Value. The reference types (str, list, dict, tuple, set, and class instances) live on the PyHost object heap behind Value::Obj(u32) handles, so mutation is observed through every alias — a.append(x) changes the list the caller still holds, exactly as in Python. dict preserves insertion order (an IndexMap), matching CPython's guaranteed iteration order since 3.7. int promotes to arbitrary precision across + - * ** // % and the bitwise ops & | ^ << >>.

Truthiness follows Python, not C or the shell: None, False, 0, empty str/list/dict are falsy. Conditions are therefore normalized through a truthiness host op before a native branch, rather than relying on the VM's default numeric truthiness. Operator overloading routes through the instance dunders (__add__, __eq__, __getitem__, __len__, __iter__, …) with reflected __r*__ fallbacks.

Component status

Dependency posture

Dependencies are kept foundational and durable — the goal is a crate that still builds cleanly years from now. Direct dependencies from Cargo.toml:

Compatibility & longevity

Links

• Docs — index.html
• Source — github.com/MenkeTechnologies/pythonrs
• Issues — github.com/MenkeTechnologies/pythonrs/issues
• fusevm — github.com/MenkeTechnologies/fusevm (the shared VM)
• License — MIT (LICENSE)