From adcd489817fda76b79778128c4390753637f3458 Mon Sep 17 00:00:00 2001 From: simontreanor Date: Mon, 28 Sep 2026 02:45:45 +0100 Subject: [PATCH] docs: a Going native section in the README How --native and pyfun build --native work, the one-line build, and the measured speed-ups, pointing at DESIGN 5.6 for the details. --- README.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/README.md b/README.md index 1b2277d..6c42185 100644 --- a/README.md +++ b/README.md @@ -451,6 +451,28 @@ Every lesson of the course also comes as a notebook for this kernel, in --- +## Going native + +The Python Pyfun emits by default is written to be read. When a program needs speed instead, +`--native` emits Python shaped for [mypyc](https://mypyc.readthedocs.io), the compiler that turns +typed Python into a C extension: every `match` becomes an `if`/`isinstance` ladder, and top-level +functions carry annotations taken from their inferred types, so the annotations can't be wrong. + +```bash +pip install mypy # mypyc ships with mypy; it needs a C compiler +pyfun build --native collatz.pyfun -o collatz_native +python collatz_native # runs the compiled program +``` + +On the repository's benchmarks (CPython 3.12, `bench/mypyc_run.py`), the mypyc build runs 1.3x to +13x faster than the same program as plain Python, and the arithmetic-heavy one runs about 12x +faster than the hand-written Python it's measured against. `pyfun compile --native` alone, without +mypyc, is already faster on match-heavy code, because CPython skips its pattern-matching +machinery. Native builds are single-file for now; [`DESIGN.md` ยง5.6](https://github.com/simontreanor/Pyfun/blob/main/DESIGN.md) +has the details. + +--- + ## How it works Pyfun is a dependency-free Rust crate that runs a classic pipeline, and the compiler is the