SPy – A Statically Compilable Python Variant and Its Emerging Ecosystem

Thesis

SPy attempts to reconcile two historically opposed ambitions: the rapid, interactive experience that Python developers cherish, and the performance guarantees that come from static compilation. By providing both an interpreter for day‑to‑day development and a compiler that emits C and ultimately native binaries, SPy positions itself as a pragmatic bridge between the dynamic and the static, inviting Python practitioners to experiment with ahead‑of‑time compilation without abandoning familiar syntax.

---

Core Arguments

1. Design Philosophy – “Python‑ish but compile‑ready”

The language is deliberately a variant of Python rather than a superset. Its syntax mirrors CPython, and most idiomatic constructs (lists, dictionaries, first‑class functions) remain unchanged. Where divergence occurs, the changes are motivated by the need for a deterministic compilation model: type annotations become mandatory for function signatures, and certain reflective features are limited to preserve compile‑time predictability. The project’s own exposition, Inside SPy, part 1: Motivations and Goals and part 2: Language semantics, outlines this trade‑off in depth.

2. Dual‑Mode Runtime – Interpreter and Compiler

SPy ships with two complementary runtimes:

• Interpreter mode – The classic REPL‑style experience. The interpreter is written in Python and runs on top of CPython, loading the core runtime library (libspy) as a WebAssembly module via wasmtime. This mode is useful for rapid prototyping, debugging, and running test suites.
• Compiler mode – A pipeline that transforms source code through several stages (pyparse → parse → symtable → redshift → cwrite → compile). The final step produces a C file that is compiled into a static executable. The spy build command encapsulates the entire process, allowing developers to obtain a binary with a single invocation.

The pipeline is intentionally transparent; each stage can be halted with a flag (spy pyparse, spy redshift, etc.) to inspect intermediate representations. This design encourages learning the internals and debugging compilation issues.

3. Installation Flexibility – pip, uv, and Pixi

Because SPy depends on both Python packages and a native garbage collector library (bdw‑gc), the project offers three installation pathways:

• pip – Requires a pre‑installed Python 3.12 and the system package libgc-dev (or equivalent). After creating a virtual environment, pip install -e .[dev] builds the libspy runtime.
• uv – Automates Python version management but still expects bdw‑gc to be present on the host.
• Pixi – The most frictionless route; Pixi resolves all dependencies, including the Boehm‑Demers‑Weiser collector, without any external system packages. Commands such as pixi run make-libspy and pixi shell set up a ready‑to‑use environment.

The most current installation steps are codified in the repository’s GitHub Actions workflow, ensuring that documentation stays in sync with actual build requirements.

4. WebAssembly as a Unifying Layer

WebAssembly (WASM) is not merely a target platform for SPy; it underpins the interpreter itself. The libspy runtime is compiled to WASM and loaded by the Python interpreter through wasmtime. This arrangement yields two distinct execution models:

• Interpreted mode – libspy.wasm runs inside the host Python process, enabling the interpreter to call into compiled code for performance‑critical operations while still benefiting from Python’s dynamic features.
• Compiled mode – When building a native executable, libspy.a is statically linked, and the resulting binary contains the same runtime logic without the WASM indirection.

The architecture also supports running SPy on Pyodide, where the entire Python environment already lives inside a WASM runtime. In that scenario, the llwasm wrapper detects the surrounding engine (emscripten) and loads libspy.wasm directly, bypassing wasmtime.

5. Development Workflow and Tooling

SPy’s tooling mirrors familiar Python ecosystems:

• Testing – pytest -n auto -v -x runs the test suite in parallel, leveraging the same fixtures used for CPython projects.
• Formatting and linting – Commands like pixi run ruff-format and pixi run ruff-check keep code style consistent.
• Documentation – MkDocs powers the documentation site; mkdocs serve launches a live preview during development.
• Playground – An in‑browser playground (hosted on the project site) lets users experiment with SPy without any local installation, lowering the barrier for newcomers.

---

Implications for the Python Community

If SPy matures, it could become a viable path for Python developers who need the speed of compiled languages but are reluctant to rewrite codebases in Rust, Go, or C++. Because the language remains a close cousin of Python, incremental migration is feasible: a module can be rewritten in SPy, compiled, and linked back into a larger CPython application. Moreover, the WASM‑centric runtime opens the door to running SPy code in browsers or serverless environments where native binaries are unavailable, echoing the broader trend of bringing traditionally heavyweight languages to the edge.

---

Counter‑Perspectives

Critics may argue that SPy’s limited standard library and nascent tooling make it unsuitable for production workloads. The requirement of explicit type annotations for all public functions also introduces friction for developers accustomed to Python’s duck typing. Additionally, reliance on the Boehm garbage collector—while convenient—may not match the performance characteristics of Python’s reference‑counting plus cyclic‑GC model, especially in memory‑intensive scenarios.

---

Getting Started

1. Explore the playground – Visit the online SPy sandbox to write and run a simple program like def main() -> void: print_str('Hello world!').
2. Clone the repository – git clone https://github.com/spylang/spy.git && cd spy.
3. Choose an installation method – For a zero‑dependency start, run pixi run make-libspy && pixi shell.
4. Run the hello example – spy examples/hello.spy should print Hello world!
5. Inspect the compilation pipeline – spy redshift -x examples/hello.spy shows the generated C code and executes it in one step.

---

Further Reading

• Blog post: Inside SPy, part 1: Motivations and Goals – https://github.com/spylang/spy/blob/main/blog/inside-spy-1.md
• Blog post: Inside SPy, part 2: Language semantics – https://github.com/spylang/spy/blob/main/blog/inside-spy-2.md
• PyCon Italy 2025 talk (slides & recording) – https://github.com/spylang/spy/presentations/pycon-italy-2025
• PyCon US 2024 talk (slides & recording) – https://github.com/spylang/spy/presentations/pycon-us-2024
• Antonio Cuni’s blog – https://antoniocuni.dev/tag/spy
• “A peek into a possible future of Python in the browser” by Łukasz Langa – https://langa.dev/blog/python-browser-future

---

Contributing

The project welcomes contributions ranging from documentation improvements to core compiler enhancements. Prospective contributors should read the CONTRIBUTING.md file, follow the code‑style guidelines enforced by ruff, and run the full test suite before submitting a pull request.

---

SPy is an evolving project; the information above reflects the state of the repository as of May 2026.