These pages are for someone changing the compiler. User-facing docs live in docs/, the design overview is ARCHITECTURE.md, and the published site is at https://pyscriptc.pages.dev.
Preview the internal notes with mise run docs:internal (a docmd dev server over this directory, no build step).
- Invariants — rules a change has to keep
- Debug mode —
compile --debug,PYSC_DEBUG,--debug-dirartifacts - PYSC_MIR escape hatch: switching the opt-in MIR lane, per-function behavior, comparing lanes
- Compiler progress trend — reading the
--markdowntrend table and what moves it - Audit logging — the JSONL audit log and its directives
- Map — which file owns a fence, a runtime call, or a test
- Toolchain — C compiler driver resolution, Zig preference, and
ziglang - Benchmark audit — what the benchmark suite measures and what it does not
- Compat site — the data file, the builder and the deploy
- E1 entrypoint detector spec (the permanent detector is
benchmarks/compat2/entrypoints.py) - E2 exception model — the exception surface
- IR canonicity — the canonical IR rules
- Fence repro probes
- Import classifier
- Refused features (PS4xxx) — what is refused by design
- External oracles — mypy and pyright as second opinions
- HTTP seam design
- Checker bridge
- IR buffer type — the first-class contiguous numeric array in the IR (#372)
- Coroutine lowering
- MIR adapter fallback telemetry
- FFI manifest — the typed extern manifest and its lanes
- ABI strategy
- Release process — the bar, the rehearsal and the tag
- Python version window — why the floor is CPython 3.14
- Embedded runtime pack — pinning, the bump procedure and the security cadence
The two pages below are generated from the compiler by scripts/gen_support_table.py (data in scripts/support_data.toml); tests/test_support_docs.py fails when they drift. Do not hand-edit them.
- Supported surface — builtins and standard library, probe-checked
- Top-100 library compatibility — live
coverageruns over the pinned top-100 sources
These files are the in-repo snapshot of the data the compat site publishes.
The pipeline that feeds the site is in scripts/build_compat_json.py and scripts/compat_schema.py; it reads the same support_data.toml through the same evaluate function, so the tree keeps one definition of "supported". Its output is compat/data/compat.json, rebuilt by the nightly workflow and landed through a bot PR. The design is in Compat site.
The site itself is one Cloudflare Pages project at https://pyscriptc.pages.dev, with the compat page at /compat (linked from the docs through the PYSC_COMPAT_URL placeholder, default https://pyscriptc.pages.dev/compat). Until it is deployed, these two generated pages and compat/data/compat.json are the machine-readable status in the tree.