PyRust

A tiny Python-like interpreter implemented in Rust.

Documentation

• Implemented features — language, built-in functions, type methods, math module, optimizer
• Known limitations — what is not yet supported
• Optimizer passes — details of the 15-pass peephole pipeline

Quick start

# REPL
cargo run

# Run a script
cargo run -- examples/demo.py

On Windows (PowerShell):

cargo run
cargo run -- examples/demo.py

Using with uv

PyRust is also packaged as a Python distribution via maturin, so it can be installed and run through uv.

# Inside the repo: build and run from the project venv
uv sync
uv run pyrust examples/demo.py

# Or one-shot via uvx (no persistent install)
uvx --from . pyrust examples/demo.py

# Once published to PyPI
uvx pyrust examples/demo.py
uv tool install pyrust

Note: uv run pyrust file.py invokes the PyRust binary. There is no way to make uv run file.py use PyRust instead of CPython — uv always dispatches .py scripts to the resolved Python interpreter.

Example

nums = [1, 2, 3]
total = 0
for n in nums:
    total += n
print("sum", total)      # sum 6
print(nums[::-1])        # [3, 2, 1]

Testing

Verify Python output parity

cargo test --test parity_compare

This runs all tests/cases/**/test_*.py with CPython and PyRust and compares outputs.

CPython 3.12 is the reference. Some slot semantics (e.g. sorted(reverse=…)'s coercion) differ between 3.11 and 3.12, and pyrust's fixtures lock in 3.12 behaviour. The test harness:

• honours PYRUST_PYTHON if set,
• otherwise uses a .venv (the repo's .python-version pins 3.12 so uv venv picks the right interpreter),
• falls back to a python3.12 on PATH before plain python3 / python,
• emits a warning to stderr if the resolved interpreter is older than 3.12.

On Windows — override the Python executable if needed:

$env:PYRUST_PYTHON = "C:\\Python312\\python.exe"
cargo test --test parity_compare

Compare execution speed (CPython vs PyRust)

cargo build
python tools/benchmark_compare.py --iterations 3 --top 12

Optional override for the PyRust binary path:

PYRUST_BIN=target/debug/pyrust python tools/benchmark_compare.py

Latest benchmark on master

Live page: https://chanyavrc.github.io/pyrust/

This image is regenerated by GitHub Actions on every push to master.

CI/CD

• CI: GitHub Actions runs on push to master and on pull requests.
  • OS matrix: ubuntu-latest, windows-latest
  • Jobs run in parallel:
    • fmt (Ubuntu): cargo fmt --all --check
    • unit_and_integration (Ubuntu/Windows): cargo build, cargo test
    • parity (Ubuntu/Windows): cargo build, cargo test --test parity_compare
    • benchmark (Ubuntu): python tools/benchmark_compare.py --iterations 2 --top 12
    • benchmark-readme (Ubuntu): publishes benchmark.svg to GitHub Pages
• CD: A GitHub Release is published automatically when a tag matching v* is pushed.
  • Builds and uploads:
    • pyrust-linux-x86_64
    • pyrust-windows-x86_64.exe

Create a release

git tag v0.1.0
git push origin v0.1.0