cibuildwheel/AGENTS.md

# cibuildwheel — Agent Notes

## Always run

- `prek -a` should be run after changes to reformat, lint, and type check

## Developer commands
- `uv run pytest unit_test` — Quick run for unit tests
- `nox -s tests` — run doctests + unit tests + integration tests (slow, >30 min, requires system Python installs on macOS).
- `nox -s tests -- unit_test` — fast unit tests only.
- `nox -s tests -- test -k before_build` — single integration test/file via pytest `-k`.
- `nox -s lint` — run all linters (pre-commit/prek).
- `nox -s pylint` — run pylint separately (not in pre-commit).
- `nox -s docs` — properdocs serve (interactive) or build (non-interactive).
- Set up local dev env at `.venv`: `uv sync` (dependency groups used).

## Project layout
- `cibuildwheel/` — main package. Entry point: `cibuildwheel.__main__:main`.
- `test/` — **integration tests** (expensive, run actual wheel builds).
- `unit_test/` — **unit tests** (fast, no wheel builds).
- `bin/` — maintainer scripts (update pins, generate README tables, schema, etc.).
- `docs/` — properdocs (MkDocs fork) source.

## Testing specifics
- Three test suites exist, run in this order by `bin/run_tests.py`:
  1. `pytest cibuildwheel` — doctests.
  2. `pytest unit_test [...]` — unit tests.
  3. `pytest test [...]` — integration tests (split into `serial` and `not serial` runs).
- Serial integration tests **must not** run in parallel; non-serial use pytest-xdist by default.
- Custom pytest options:
  - `--run-docker` (unit_test + test): run OCI container tests. Linux only.
  - `--run-podman`: run podman tests (Linux).
  - `--run-emulation` (test): run QEMU emulation tests (e.g., `--run-emulation aarch64`).
  - `--platform linux` (test): force integration tests to target Linux container builds even on macOS/Windows.
  - `--enable` (test): sets `CIBW_ENABLE` env var (e.g., `pypy`, `graalpy`).
- Integration tests auto-set a default `CIBW_ENABLE` if the env var is absent.
- The `build_frontend_env` fixture parameterizes over `pip`, `build`, `build[uv]`, `uv` and skips unsupported combos per platform.
- Some integration tests require system Python.org installs on macOS; missing them prints a download URL in the error.
- iOS/Android/pyodide tests have dedicated pytest marks (`ios`, `android`, `pyodide`) and need platform-specific runners/simulators.

## Lint / typecheck
- Ruff (lint + format) and mypy run via pre-commit. Pylint runs separately via `nox -s pylint`.
- Mypy is strict (`strict = true`) and targets Python 3.11 for the package, 3.14 for a second check in pre-commit.
- Ruff config in `pyproject.toml` (`line-length = 100`).
- Python 3.11 is the minimum supported version for the package itself.

## Generated / maintained files
- `README.md` contains two **cog-generated** tables (options table, changelog preview). Pre-commit runs `cog -c -P -r -I ./bin README.md`. Edit the source scripts (`bin/readme_*.py`) or the upstream files (`docs/options.md`, `docs/changelog.md`) — do not hand-edit the generated blocks. Note the identifier is _not_ cog generated, and can be edited.
- `cibuildwheel/resources/cibuildwheel.schema.json` is generated by `bin/generate_schema.py` (run via `nox -s generate_schema`).
- `cibuildwheel/resources/constraints-*.txt` are generated via `nox -s update_constraints`.
- `cibuildwheel/resources/pinned_docker_images.cfg` and other resource files are updated via `nox -s update_pins`.

## CI / release quirks
- CI uses `uv sync --no-dev --group test` for test installs, then `uv run --no-sync` to execute.
- The release workflow uses `hynek/build-and-inspect-python-package` for dist building.
- `test.yml` skips unrelated paths to avoid burning CI time on docs-only changes.
- A sample project artifact is built once and downloaded by downstream test jobs to avoid redundant work.