Skip to main content

Crate pythonrs

Crate pythonrs 

Source
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 asyncio runtime for pythonrs: a single-thread, cooperative event loop (ready-queue + timer-heap) that drives async def coroutines, plus the Future/Task machinery and the asyncio.* module surface.
banner
The REPL banner (shown only for the interactive python --repl, never for script execution).
builtins
The pythonrs builtin layer: the fusevm CallBuiltin handler 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 the host object 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.py run is transparently cached: the source is hashed, the shard consulted, and on a hit the compiled fusevm::Chunks run directly — lex/parse/lower are skipped entirely. On a miss the program is compiled, stored, then run. python --build warms 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 to char::to_lowercase, so str.casefold uses 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 python binary.
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, their split/subgroup/derive protocol, and the reconstruction except* does when its handlers finish.
excunicode
UnicodeEncodeError, UnicodeDecodeError and UnicodeTranslateError: 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 single run() that prints a report and returns a process exit code. None of this is on the hot path; it exists so a python --doctor / --cacheview tells 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, or python on 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.py grammar (parse and everything it calls) plus the one check re/_compiler.py makes 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 of traceback.py’s _compute_suggestion_error and _levenshtein_distance — and its SyntaxError keyword hint, _find_keyword_typos (with the difflib and textwrap pieces 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.c writes 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) is a and 2 ** -1 is 2 ** (-1); constants are their repr, with an infinite float spelled 1e309.

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 SystemExit message).

Enums§

ReportOrder
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 (prints repr(value) for non-None results and binds _). Not used for scripts.
compile_or_load
Transparent bytecode cache: return the cached compiled Program for src (skipping lex/parse/lower entirely), else compile it, store it in the ~/.pythonrs/scripts.rkyv shard, and return it. This runs on EVERY ordinary python foo.py / python -c invocation, so scripts are rkyv-cached automatically — not only under --build. Set PYTHONRS_TRACE=1 to log hit/miss to stderr (silent otherwise; normal runs print nothing).
compile_or_load_cacheable
compile_or_load with 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 .pyc for -c/stdin. Real script files and imported modules stay cacheable.
compile_or_load_labeled
compile_or_load that labels a stored entry with source (its module path) instead of the runtime’s traceback filename. Imported modules use this so --cacheview attributes 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 .py file (transparently rkyv-cached — see compile_or_load).
eval_file_debug
Read and run a .py file 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 default sys.argv of [''].
eval_str_captured
Run a Python source string on a fresh host with globals bound and the program’s output captured in-process, returning the program’s outcome alongside everything it wrote.
eval_to_string
Evaluate src and return the repr of 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 N header, the offending line, a caret run under the position, and Class: 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 python binary’s run: run_program_report with the report written to stderr where CPython writes it — after the program’s own buffered stdout for a script, before it for -c (see ReportOrder) — and before atexit callbacks run, since CPython prints the exception in PyErr_Print and runs atexit later, in Py_FinalizeEx. Returns the exit code.
run_module
Run python -m <module> [args…]. Delegates to the embedded CPython’s runpy (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 the stdlib-ffi bridge; a native-only build has no interpreter to host runpy.
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 SystemExit handling), 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_program is the binary’s entry, which prints it at the point CPython does.