Skip to main content

petitpy

petitpy is a small Python interpreter written in Zig, for two places where CPython is too heavy. In the browser, it is a 346 KB wasm module that drives the DOM from Python. On native Linux or macOS, a 6.7 KLOC system daemon runs on it in 4 MB of memory instead of CPython's 17 MB. It speaks more of CPython's language than its small size suggests: Unicode strings, match, exception chaining, dataclasses, and an everyday stdlib with pathlib, json, logging, subprocess and unittest.mock. It installs with pip or npm, as petitpy, with ppy as the short command; the repository and its internals still use its development name, nanopython.

petitpy builds on MicroPython: it shares MicroPython's .mpy bytecode format and much of its design, and uses MicroPython's test suite as a conformance check. See Acknowledgments.

$ petitpy --version
petitpy 0.7.1

$ echo 'print("hello from", 0.1 + 0.2)' | petitpy /dev/stdin
hello from 0.30000000000000004

$ ppy                     # interactive REPL
petitpy 0.7.1 — interactive REPL (Ctrl-D to exit)
>>> def fib(n):
...     return n if n < 2 else fib(n-1) + fib(n-2)
>>> [fib(i) for i in range(10)]
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34]

Install

uvx petitpy script.py           # run once, no install
uv tool install petitpy         # or pip install petitpy: installs `petitpy` and `ppy`
npm install petitpy             # the browser build, see npm/README.md

Prebuilt wheels cover macOS (arm64, x86_64) and Linux (x86_64, aarch64); elsewhere pip builds from the sdist with Zig, in about a minute. This is an alpha: see the differences from CPython.

Who is this for?

Three audiences are served, in priority order:

Status

The runtime works end to end on both native and wasm. Active work is on user experience, language and stdlib reach, size, and speed. The current roadmap is docs/src/adrs/010-roadmap-v06.md (009 is the previous cycle).

Headline Value
Native corpus, nano (byte-exact vs. MicroPython's test outputs) 541/541, held
Native corpus, full 545/552, 7 documented known-fails
WASM corpus (under wasmtime) 490/541, baseline + skip list green
Integration smoke (native + wasm, hand-written) 189/189 on both arms
Real-world Python programs that work on both arms 580 in golden-programs/works/; see docs/src/COMPATIBILITY.md for the bucket-by-bucket breakdown
wasm32-wasi shipping size (web/nanopython.wasm) 346 KB (post-wasm-opt -Oz, integrated into make web)
Native arm64 shipping size (ReleaseFast) 1170 KB

Gate state

The harness has four independent gates plus an aggregate. Each answers a different question, and none substitutes for another. See Build & Test for the full breakdown.

Gate What it answers Result
make check Does the full-arm binary match the corpus minus its documented baseline? 545/552, green
make check CONFIG=nano Does the nano binary match the frozen MicroPython reference byte-exact? 541/541, invariant
make wasm-check Does the wasm binary match the corpus minus the documented wasm baseline? GREEN at 490/541 (51-test known-fails baseline matches exactly)
make test-integration Does the native binary actually start up and run real Python? 189/189
make test-integration-wasm Same question, against the wasm binary via wasmtime. 189/189
make check-capability Do both front-ends and both back-ends agree on 67 language constructs? GREEN, 0 gaps; not in the aggregate (needs vendor MicroPython + uv)
make (the aggregate) Runs all of the above bar the last, both arms. The "I'm about to commit" gate. exit 0

Quick start

Needs Zig 0.16 and wasmtime (for running wasm locally). A MicroPython source tree is required at vendor/micropython; if it's missing, make port (and everything downstream: make build, make check, …) will run make bootstrap, cloning MicroPython at the pinned MICROPY_REV into that path on first use. If you already keep MicroPython checked out elsewhere, symlink it at vendor/micropython before the first build to skip the auto-clone.

make build               # Debug native binary → zig-out/bin/nanopython
make build-small         # ReleaseSmall native (development companion)
make web                 # production wasm → web/nanopython.wasm

make                     # the aggregate gate (all 4 + lint, both arms)
make test                # native-only test pyramid (faster)
make check               # native byte-exact corpus only
make wasm-check          # wasm gate against the corpus baseline

make metrics-record      # snapshot size + coverage to metrics/history.ndjson
make metrics-report      # print recent rows as a trend table
make help                # list all targets

Test harness: why four gates

Each gate is small, fast, and answers a question the others can't. The recent float-print signature mismatch (commit 7d5131c → 571b1d6) shipped because the wasm corpus had the failing tests on a known-fails list for unrelated reasons. The integration suite was native-only at the time. The fix adds orthogonal gates: under the both-arms integration suite, the float bug would have surfaced at commit time.

  • byte-exact corpus catches regressions in the Zig front-end + VM + the few remaining vendor C bridges.
  • integration smoke catches "does the binary actually run real Python": small, hand-written, runs in ~1 s, regression-pin cases for every wasm-only bug we've shipped.
  • integration-wasm is the same suite via wasmtime; it would have caught the float bug atomically at commit time.
  • golden-programs (ADR 008) is the strategic signal: 756 real Python programs sourced from MicroPython's tests, CPython's tests, PEP examples, and curated demos, bucketed by what they need.

Binary size

All measurements were taken on macOS arm64. wasm and native are co-primary distributions; both ship.

Build Size Notes
wasm32-wasi make web 346 KB the shipping artifact (ReleaseSmall + frozen-tiny + post-wasm-opt -Oz); ADR 007 §4 P6 wires the optimizer into the release pipeline
wasm32-wasi raw (pre-optimizer) 384 KB what zig build produces before wasm-opt, for inspection
native make build (Debug) 3.9 MB dev default (full profile), with DWARF symbols and no DCE
native make build-release (ReleaseFast) 1170 KB inlined, full optimization (full profile)
native make build-small (ReleaseSmall) 558 KB full, 492 KB nano smallest native: the same arm with -Doptimize=ReleaseSmall
upstream MicroPython unix-standard 652 KB their default, a feature superset of nano

The wasm size is the metric that matters most: raw bytes drive both parse time and download cost. Trends are tracked over time in metrics/history.ndjson (tools/metrics.py).

What works

Core types: int (arbitrary precision on native full; 63-bit small on native nano; 64-bit long long on wasm32), float (IEEE 754 double), str (Unicode code points), bytes, bytearray, bool, None, list, tuple, dict, set, frozenset, range (with start/stop/step attributes and [a:b] slicing), slice, memoryview, array.array.

Control flow + classes: full try/except/finally/raise, generators with .send()/.throw()/.close(), walrus (:=), match statements (literals, singletons, captures, or-patterns, sequences with *rest, mappings, class patterns, as, guards; vendor MicroPython parses none of it), all comprehensions, async def coroutines; classes with single and multiple inheritance, descriptors, properties, all dunder methods including __getitem__ override on dict subclasses.

Strings: f-strings, %-formatting (%d/%f/%s/%r), .format(), all str.* methods including .title(), .center(width, fillchar), .zfill(n), named-field formatting on tuples, bytes ↔ bytearray interop everywhere it matters.

Modules: sys, math (including hypot and gcd), errno, struct, gc, micropython, array. Plus pure-Python _thread, js, json, types, heapq, bisect, functools, itertools (including permutations, combinations, product, groupby, zip_longest), collections (with Counter and defaultdict), random, re, string, typing, datetime, pathlib, enum, all frozen-tiny (ADR 003). Native full adds os (with os.path), time, socket, select, signal, subprocess, open() and file I/O.

Directives: from __future__ import ... is consumed by the compiler and emits nothing, as CPython does. There is no __future__ module to import; vendor MicroPython raises ImportError for the whole statement.

Process semantics: petitpy script.py and petitpy -c CODE; uncaught exceptions exit 1 (not 0); sys.exit(N) propagates correctly; SystemExit with no arg or None exits 0.

What doesn't work yet

The full list, by build, is Differences from CPython. Tracked by bucket in golden-programs/. The headline gaps:

  • Arbitrary-precision ints on nano and wasm: 2**100 raises OverflowError (64-bit long long on wasm32, 63-bit small ints on native nano).
  • asyncio: coroutines run, but there is no event loop module.
  • Float literals in the browser build can parse one ulp off with 17 significant digits (vendor's parser, kept for size); native parses them correctly rounded.
  • Complex literals: 2j fails to compile, although full has the complex type.
  • open() and file I/O on nano: no HAL; wasm sees stdout/stderr via WASI.
  • Insertion-ordered dicts: a dict iterates in hash order, as in MicroPython (list({"b": 1, "a": 2}) is ['a', 'b']); class __annotations__ is an OrderedDict.
  • Implicit exception chaining (__context__; raise ... from works).
  • Unicode case mapping: upper()/lower() change ASCII letters only, as in MicroPython.
  • Threading.

Documentation

Document Purpose
docs/src/adrs/ Architecture Decision Records; 010-roadmap-v06.md is the next-step plan
docs/src/case-study-daemon.md Case study: running hop3-rootd (6.7 KLOC Linux daemon) under petitpy: tests, memory, disk and speed vs CPython 3.11

Built docs live under docs/. Render via Zensical:

make doc-setup       # one-time: pip install zensical
make doc-serve       # dev server with live reload at http://localhost:8000
make doc-build       # render to ./site/ (gitignored)

Layout

Path What
src/*.zig Zig subsystems + main.zig entry point
src/runtime/, src/objects/, src/modules/, src/memory/ VM track
src/compiler/, src/frontend/ Compiler track
src/mp_mirrors.zig Type mirrors for vendor MicroPython C structs
src/pyerr.zig PyError!T error union + polled-sentinel bridge
build.zig Build script; explicit per-arm addCSourceFiles lists drive vendor C inclusion
port/ mpconfigport.h (nano + full arms) + Makefile generating the embed package
nanopython-lib/ Pure-Python frozen-tiny stdlib modules
tools/ Build, test, metrics scripts (corpus.py, progress.py, wasm_gate.py, metrics.py)
tests/integration.py 189-case integration smoke (runs against any binary via --runner)
benchmarks/, sandbox/p2w/programs/benchmarks/ Benchmark programs (used by tools/metrics.py)
corpus/nano/basics/ Frozen byte-exact goldens for native
corpus/wasm-known-fails.txt Documented expected wasm failures (51 today)
golden-programs/ 756 real Python programs bucketed by what they need (ADR 008)
metrics/history.ndjson Append-only size/coverage/perf history
web/ Browser demos + shipping wasm artifact
docs/ User-facing documentation (Zensical)
examples/ Small runnable example programs

Acknowledgments

petitpy would not exist without MicroPython, by Damien P. George and its contributors. Its design showed that a complete, small Python is possible. petitpy's Zig runtime builds on its C code and its design, and its test suite still checks petitpy on every commit. Its .mpy bytecode format is still petitpy's, so the compilers of both projects produce code that runs on either. A little of its C remains, for floats, re and, on some builds, big integers. Thank you.

License

MIT, shared with MicroPython, on which petitpy builds. The heapq, bisect and types modules come from micropython-lib, which derives them from CPython, and are under the Python license. Both texts are in LICENSE.

Metadata

Release files for petitpy 0.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for petitpy 0.8.0
File Size Uploaded Provenance Actions
petitpy-0.8.0.tar.gz 778.3 kB Without provenance Details for petitpy-0.8.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for petitpy 0.8.0
File Actions
petitpy-0.8.0-py3-none-manylinux_2_17_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for petitpy-0.8.0-py3-none-manylinux_2_17_x86_64.whl
petitpy-0.8.0-py3-none-manylinux_2_17_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for petitpy-0.8.0-py3-none-manylinux_2_17_aarch64.whl
petitpy-0.8.0-py3-none-macosx_11_0_x86_64.whl Python 3 none macOS 11.0+ x86-64 Details for petitpy-0.8.0-py3-none-macosx_11_0_x86_64.whl
petitpy-0.8.0-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for petitpy-0.8.0-py3-none-macosx_11_0_arm64.whl

Total release size: 4.0 MB

Release files / petitpy-0.8.0.tar.gz

Download URL petitpy-0.8.0.tar.gz
Size 778.3 kB
Tags Source
SHA-256 checksum
How to use checksums
0ea67b9d1db1216c3c0ca1fbd157fa13ce37557c813cc3e078cb54f6239387cd
BLAKE2b-256 checksum
How to use checksums
8d4d56d8c9ce73010ef7bcd0154398ecb6ad8a7cc7d727d21cb8b020a643d658
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.0

Release files / petitpy-0.8.0-py3-none-manylinux_2_17_x86_64.whl

Download URL petitpy-0.8.0-py3-none-manylinux_2_17_x86_64.whl
Size 873.3 kB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
7a8bedd2a7abc4b781d9a0294913e2e9abeb6c923a54b24ca77b701cda20e7f3
BLAKE2b-256 checksum
How to use checksums
ba7711a3c80da0de9c07cb8f6f088f976805310753c204beaa7768ca8612a767
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.0

Release files / petitpy-0.8.0-py3-none-manylinux_2_17_aarch64.whl

Download URL petitpy-0.8.0-py3-none-manylinux_2_17_aarch64.whl
Size 824.5 kB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
b59e871d63acae72a5331eb14774de9e65289bc534a9a7c1ae8674515f216fbb
BLAKE2b-256 checksum
How to use checksums
131b139274d5f35d5a4e4d22fa711033d4cc4667c5816ec200a8230ea9b938bd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.0

Release files / petitpy-0.8.0-py3-none-macosx_11_0_x86_64.whl

Download URL petitpy-0.8.0-py3-none-macosx_11_0_x86_64.whl
Size 788.9 kB
Tags Python 3 macOS 11.0+ x86-64
SHA-256 checksum
How to use checksums
106ff2cedd11572d5f5097d82c7858bb8e6439333a7af5c90f7b45dd62f80672
BLAKE2b-256 checksum
How to use checksums
65b31d8137620b299db5d279243fc3c875d5e5bcd38c28bca78526b68545fd4e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.0

Release files / petitpy-0.8.0-py3-none-macosx_11_0_arm64.whl

Download URL petitpy-0.8.0-py3-none-macosx_11_0_arm64.whl
Size 771.8 kB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
be2e9fe0a61f9b3bd866a4f54cc2b316ed96a779700a900ba0851712ef17434a
BLAKE2b-256 checksum
How to use checksums
cf5ac7420ce9fda78fd1fb9b67feebfb5be6f0dd5f62b271c78dc3e35463e817
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.0

Security for petitpy 0.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page