Quickstart

Quickstart

pyscriptc lowers a typed Python subset to a native binary. Parsing is CPython’s own ast; mypy is a preflight checker. Anything the subset does not prove stops at a fence (PSxxxx), not a guess.

Requirements

• CPython 3.10 or later (PyPI installs only; the prebuilt binary has no Python dependency). The emitted IR is stamped with the interpreter that lowered it.
• A C toolchain to link compiled programs: clang, or zig which also unlocks cross-compilation via --driver zig.
• The preflight checker, mypy, ships inside the installed package. No extra setup.

Installing clang or zig

Install

uv tool install pyscriptc

pipx install pyscriptc

pip install pyscriptc

mise use -g github:sigilco/pyscriptc

Compile and run

pyscriptc compile examples/sum_squares.py --run --call sum_squares --args '[10]' -o /tmp/sum_squares

That prints 285, the same value CPython returns, from a native binary.

How a compile works

pyscriptc compile FILE --run --call FUNC --args '[...]' -o /tmp/name

• FILE is one Python file or a package directory. Imports resolve from the closed standard-library table.
• --call is the function the generated main calls. The binary prints its return value.
• --args is a Python list literal (ast.literal_eval). Elements can be int, float, bool, or str.
• The printed return is an int, a float (%.17g), or a str. A bool return cannot be printed.
• --emit ir writes JSON. --emit llvm writes textual LLVM. --emit bin (or --run) links a binary.

When it stops

A fence output names the construct and the code. pyscriptc explain PS2003 prints what the code means.