Expand description
pythonrs — Python as a fusevm frontend.
Pipeline: lexer → parser builds a Python AST → compiler lowers it to a
fusevm::Chunk (plus a table of function/lambda/class-body sub-chunks and
try-block chunks) → fusevm executes it, calling back into the host (through
registered builtins and the strict numeric hook) for every Python-specific
operation. There is no bespoke VM or JIT here — execution and codegen live in
fusevm.
Re-exports§
pub use embed::run_program;
Modules§
- aot
- Ahead-of-time compilation (
python --build). - aot_
native - Native AOT for pythonrs via
fusevm::aot(python --build). - ast
- Python abstract syntax tree.
- async_
rt - Native
asyncioruntime for pythonrs: a single-thread, cooperative event loop (ready-queue + timer-heap) that drivesasync defcoroutines, plus the Future/Task machinery and theasyncio.*module surface. - banner
- The REPL banner (shown only for the interactive
python --repl, never for script execution). - builtins
- The pythonrs builtin layer: the fusevm
CallBuiltinhandler table (install), the strict numeric hook, the Kernel builtin functions (print,len,range, …) and the per-type method dispatch (str/list/dict/… methods). Handlers pop their arguments off the VM stack, call into thehostobject model, and push the result back. - cache
- rkyv-backed bytecode cache for compiled Python scripts (mirrors the fleet’s
zshrs/rubylang design). Every ordinary
python foo.pyrun is transparently cached: the source is hashed, the shard consulted, and on a hit the compiledfusevm::Chunks run directly — lex/parse/lower are skipped entirely. On a miss the program is compiled, stored, then run.python --buildwarms the same shard ahead of time. - casefold
- Unicode full case-folding overrides (generated from CPython 3.14
str.casefold). Each entry is a codepoint whose fold differs from its simple lowercase mapping — the multi-character “full” folds (e.g.ß->ss) plus the handful of single-char folds that lowercasing gets wrong. Every other codepoint folds identically tochar::to_lowercase, sostr.casefolduses this table only as an override and defers to lowercasing otherwise. Sorted by codepoint for binary search; do not edit by hand. - cli
- Command-line interface for the
pythonbinary. - compiler
- Lower the Python AST to
fusevm::Chunk. - dap
- Debug Adapter Protocol over stdio (
python --dap). - embed
- Embedding entry point: run a Python program from a host and capture its output.
- excgroup
- PEP 654 exception groups —
ExceptionGroup/BaseExceptionGroup, theirsplit/subgroup/deriveprotocol, and the reconstructionexcept*does when its handlers finish. - excunicode
UnicodeEncodeError,UnicodeDecodeErrorandUnicodeTranslateError: their constructor, their attributes and their__str__.- extensions
- CLI extensions beyond the core interpreter — diagnostics and cache
inspection that the fleet siblings (zshrs
--doctor, elisprs--cache-*) ship. Each submodule exposes a singlerun()that prints a report and returns a process exit code. None of this is on the hot path; it exists so apython --doctor/--cacheviewtells the truth about the runtime and the rkyv bytecode shard without the user reading source. - ffi
- CPython stdlib FFI bridge (feature
stdlib-ffi). - host
- The Python object heap and runtime, reached from fusevm through registered
builtins (
register_builtin) and the strict numeric hook. - intercepts
- Method-call intercepts (aspect-oriented advice) — a glob-matched registry of before/after/around hooks keyed by method-name pattern.
- lexer
- Python tokenizer.
- lsp
- Language Server Protocol over stdio (
python --lsp). - lsp_nav
- Name resolution for the LSP’s go-to-definition and signature help
(
src/lsp.rs): over the open document, and from there into the modules it imports and the classes it defines. - mangle
- Private-name mangling — CPython’s
_Py_Mangle. - oracle
- Resolving the reference CPython the differential harnesses compare against.
- parser
- Recursive-descent Python parser: token stream -> AST.
- pyhash
- CPython’s
hash()algorithms, ported from the CPython 3.14.6 C sources. - regexpr
- The regex engine behind
re. - repl
- Interactive REPL (
python --repl, orpythonon a TTY). - rust_
ffi - Python wiring for inline Rust FFI (
rust { ... }blocks). - sre_
parse - The pattern checker in front of the regex engines: a port of CPython’s
re/_parser.pygrammar (parseand everything it calls) plus the one checkre/_compiler.pymakes on the parsed tree (a look-behind must be fixed-width). - stack
- How much native stack the running code has left, measured the way CPython 3.14 measures it.
- stdio
- The process’s
stdout/stderr, buffered exactly as CPython buffers them. - stdlib
- Python standard-library modules kept native for pythonrs.
- suggest
- CPython’s
Did you mean: 'x'?hint — a port oftraceback.py’s_compute_suggestion_errorand_levenshtein_distance— and itsSyntaxErrorkeyword hint,_find_keyword_typos(with thedifflibandtextwrappieces it uses). - symtable
- The declaration checks of CPython’s symbol table (
Python/symtable.c). - tbcolor
- The colours of a traceback printed for an uncaught exception.
- tiers
- Which fusevm execution tier a program’s bytecode actually reaches.
- unparse
- An expression back to source text, as CPython’s
Python/ast_unparse.cwrites it: the string a PEP 563 annotation (from __future__ import annotations) is stored as. Parentheses come from operator precedence, not from the source, so(a)isaand2 ** -1is2 ** (-1); constants are theirrepr, with an infinite float spelled1e309.
Structs§
- RunReport
- How a program run ended: the process exit code plus any text the runtime must
emit to stderr (a traceback block or a
SystemExitmessage).
Enums§
- Report
Order - When the binary flushes the standard streams relative to reporting the program’s uncaught exception — the one place CPython’s entry points differ.
- Value
- Core value type — what lives on the stack and in variables.
Functions§
- compile
- Compile a source string to a runnable program.
- compile_
debug - Compile with per-statement DAP line markers enabled (
python --dap). - compile_
interactive - Compile one interactive REPL line in CPython “single” mode: a top-level
expression statement echoes its value through
sys.displayhook(printsrepr(value)for non-Noneresults and binds_). Not used for scripts. - compile_
or_ load - Transparent bytecode cache: return the cached compiled
Programforsrc(skipping lex/parse/lower entirely), else compile it, store it in the~/.pythonrs/scripts.rkyvshard, and return it. This runs on EVERY ordinarypython foo.py/python -cinvocation, so scripts are rkyv-cached automatically — not only under--build. SetPYTHONRS_TRACE=1to log hit/miss to stderr (silent otherwise; normal runs print nothing). - compile_
or_ load_ cacheable compile_or_loadwith an explicit cacheability gate. A-c/stdin program (cacheable == false) is compiled fresh and NEVER touches the shard: such one-off snippets are never re-run byte-for-byte, so caching them only bloats the append-only shard (and forces an O(shard) rewrite per miss) for no hit — CPython likewise never writes a.pycfor-c/stdin. Real script files and imported modules stay cacheable.- compile_
or_ load_ labeled compile_or_loadthat labels a stored entry withsource(its module path) instead of the runtime’s traceback filename. Imported modules use this so--cacheviewattributes each cached blob to the module that produced it, not the<string>/script name of whatever run triggered the import.- eval_
file - Read and run a
.pyfile (transparently rkyv-cached — seecompile_or_load). - eval_
file_ debug - Read and run a
.pyfile under the DAP debugger. - eval_
str - Parse/load, compile, and run a Python source string on a fresh host. Runs as
the top-level
__main__with a defaultsys.argvof['']. - eval_
str_ captured - Run a Python source string on a fresh host with
globalsbound and the program’s output captured in-process, returning the program’s outcome alongside everything it wrote. - eval_
to_ string - Evaluate
srcand return thereprof the last expression’s value. - load_
merged - Rebase a freshly compiled program’s func/try ids above those already loaded on the host, then install its functions/tries and return the (rebased) main chunk to run. Shared by the initial script run, each REPL line, and imports.
- plain_
error - An error as an embedder reads it: a syntax error’s position trailer (see
parser::split_syntax_error) is for the runtime’s own exception builder and traceback, and comes off at the library boundary. - render_
compile_ error - A program that does not compile, reported the way CPython reports one: the
File "…", line Nheader, the offending line, a caret run under the position, andClass: message. A message the compiler positioned only by a(line N)suffix gets the header and the line without carets; one with no position at all is printed as it is. - run_
compiled - Run an already-compiled program on the current host.
- run_
main_ program - The
pythonbinary’s run:run_program_reportwith the report written to stderr where CPython writes it — after the program’s own buffered stdout for a script, before it for-c(seeReportOrder) — and beforeatexitcallbacks run, since CPython prints the exception inPyErr_Printand runsatexitlater, inPy_FinalizeEx. Returns the exit code. - run_
module - Run
python -m <module> [args…]. Delegates to the embedded CPython’srunpy(the same code path as CPython’s-m), so-m pip/-m venv/… run on the real interpreter. Returns the process exit code. Only available with thestdlib-ffibridge; a native-only build has no interpreter to hostrunpy. - run_
program_ report - Run a top-level program with a fully specified CLI/runtime context and reduce
the outcome to a process exit code + stderr text (uncaught-exception traceback
or
SystemExithandling), running interpreter shutdown (atexit, stream flushes) before returning. The text is returned rather than printed, so an embedder or a test reads it;run_main_programis the binary’s entry, which prints it at the point CPython does.