Community

Where to start

Add a library module

The most self-contained way to contribute. Pick a module from the wanted list, write it in Python, and test it against CPython.

Compile your program

Try pyc on real code. Each refusal is either a real limit, which belongs in the documentation, or a pyc bug, which belongs in an issue.

Fix a filed issue

Each issue documents the symptom, the root cause where known, a proposed fix and a verification plan.

Browse issues →

Work on the analysis

The IFA library is a general interprocedural analysis with extensive design notes. Read the design rules below before changing it.

ifa/INDEX.md →

Reporting a bug

The most useful report is a short program plus both outputs:

$ python3 repro.py > expected.txt
$ pyc --strict repro.py && ./repro > actual.txt
$ diff expected.txt actual.txt

A program that compiles and prints something different from CPython is the most serious kind of bug pyc can have. Please say so in the report title. Open issues on GitHub.

Design rules

pyc has a short list of rules that every change is measured against. They are spelled out, with the history behind each one, in AGENTS.md.

CPython semantics, not another compiler’s.	If a change makes pyc agree with something else and disagree with CPython, it is wrong.
Split only on demand.	A function or data contour exists because something observed a distinction that required it, never because a neighbouring contour split.
Provenance is never identity.	Contours are keyed on what the types are, never on where a value came from.
Never decide by name.	Analysis and code generation use the call graph and the class hierarchy, never matching identifier strings.
Root-cause; don’t retreat.	A conservative fallback that makes a test pass needs proof that the better solution can’t be reached.
Every accommodation is flagged.	Anything beyond CPython 3 semantics is named, warns, and is off under --strict.

Change acceptance

One command runs everything CI runs, on both backends:

$ make test

For a change to the analysis, the 77-program corpus is the larger benchmark. ./corpus_sweep.sh -m check compiles and runs every program and compares its output with CPython's. Results are cached under sweeps/, keyed on the source tree.