How to build and test extensions

Install a C compiler, Python 3.11, and uv. Use Xcode Command Line Tools on macOS or Visual Studio Build Tools on Windows.

uv venv --python 3.11
source .venv/bin/activate
make develop
make lint
make checks
make coverage
make dist
make test-dist

On Windows, activate with .venv\Scripts\activate instead. make test-dist installs compatible wheels in fresh environments and verifies compiled imports outside the checkout. It also rebuilds each sdist into a wheel and repeats those checks.

To compile another .py or .pyx module, add its path to [tool.hatch.build.targets.wheel.hooks.cython.options.files].targets in pyproject.toml, then run make develop again. Only explicitly selected modules are compiled. Keep package initialization and tests as Python sources.

Run make test after changing an extension. Tests check that both example modules load native binaries. Coverage measures Python code; the compiled _compiled.py is excluded because builds do not enable Cython line tracing.

For portable wheels, run make dist-py-wheel on the target platform. Linux wheel builds require Docker. Run make dist-py-sdist to build an sdist without compiling extensions. CI runs tests against each installed wheel through cibuildwheel.

To update the template from a clean branch:

copier update --answers-file .copier-answers.yaml --trust

Review the diff and rerun the checks above before committing.