Henry Schreiner
1af5cd76db
properdocs is a drop-in MkDocs fork by the original MkDocs maintainers. The existing plugins (include-markdown, macros, intersphinx) and pymdown extensions work unchanged; themes are unbundled, so the readthedocs theme comes from properdocs-theme-readthedocs. Assisted-by: ClaudeCode:claude-fable-5
58 lines
3.7 KiB
Markdown
58 lines
3.7 KiB
Markdown
# 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.
|