Skip to content

AGENTS.md

Latest commit

 

History

History
57 lines (49 loc) · 3.73 KB

AGENTS.md

File metadata and controls

57 lines (49 loc) · 3.73 KB

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 — mkdocs 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/ — mkdocs 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.