Platforms stage

[henryiii]

PR to PR to show a --stage feature.

Assisted-by: ClaudeCode:claude-opus-4.8

Summary by Sourcery

Introduce stage-aware build and test execution, allowing separate build-only, test-only, or combined runs while reusing prebuilt wheels.

New Features:

• Add a --stage command-line option (and CIBW_STAGE env var support) to control whether cibuildwheel runs build-only, test-only, or both stages.
• Allow test-only runs to consume prebuilt wheels from the output directory using interpreter- and platform-aware wheel selection.

Enhancements:

• Refine wheel selection logic to distinguish free-threaded builds and handle platform tag variants across macOS, Linux, Android, iOS, Pyodide, and Windows.
• Propagate stage selection through platform backends and shared host build driver to gate before_all, build, test, and wheel copying steps accordingly.

Tests:

• Add unit tests for the new find_built_wheel helper and its matching logic, including free-threaded and cross-ABI cases.
• Add run_host_build tests to verify behavior for all, build-only, and test-only stages and error handling when prebuilt wheels are missing.

[sourcery-ai]

Reviewer's Guide

Adds a stage-aware build/test pipeline with a new --stage CLI option, enabling build-only and test-only runs that reuse prebuilt wheels, and centralizes logic for matching previously built wheels to identifiers across platforms.

Sequence diagram for the stage-aware build and test pipeline

sequenceDiagram
    actor User
    participant main_inner
    participant build_in_directory
    participant platform_build as platform_module.build
    participant run_host_build
    participant find_prebuilt_wheel
    participant find_built_wheel

    User->>main_inner: cibuildwheel --stage=test
    main_inner->>build_in_directory: build_in_directory(args)
    build_in_directory->>build_in_directory: stages = {Stage.TEST}
    build_in_directory->>platform_build: build(options, tmp_path, stages)
    platform_build->>run_host_build: run_host_build(platform_module, options, tmp_path, stages)

    loop per identifier
        alt Stage.BUILD not in stages
            run_host_build->>find_prebuilt_wheel: find_prebuilt_wheel(output_dir, identifier)
            find_prebuilt_wheel->>find_built_wheel: find_built_wheel(wheels, identifier)
            find_built_wheel-->>find_prebuilt_wheel: wheel
            find_prebuilt_wheel-->>run_host_build: prebuilt wheel path
            run_host_build->>run_host_build: run tests on prebuilt wheel
        else Stage.BUILD in stages
            run_host_build->>platform_build: build_in_container(..., stages)
            platform_build->>platform_build: build wheel
            platform_build-->>run_host_build: built wheel
            run_host_build->>run_host_build: run tests on built wheel
        end
    end

    run_host_build-->>platform_build: stage complete
    platform_build-->>build_in_directory: stage complete
    build_in_directory-->>main_inner: exit
    main_inner-->>User: command finished

Loading

File-Level Changes

Change	Details	Files
Introduce stage-aware wheel lookup and matching for previously built wheels, including free-threaded and multi-platform tags.	Add _platform_tag_matches helper to compare wheel platform tags against identifier platforms, ignoring version segments where appropriate. Implement find_built_wheel to first try cross-compatible wheels via find_compatible_wheel and otherwise match wheels by interpreter, ABI (including free-threaded suffix), and platform. Extend utils_test to cover find_built_wheel success and failure cases for multiple platforms and interpreters. Update platforms._run.find_prebuilt_wheel to use find_built_wheel and improve the error message when no wheel is found.	cibuildwheel/util/packaging.py unit_test/utils_test.py cibuildwheel/platforms/_run.py
Add a --stage CLI option and propagate stage selection through platform build entry points to gate build and test phases.	Add stage field to CommandLineArguments defaults and a --stage argument to the main CLI, defaulting from CIBW_STAGE or 'all'. Compute a frozenset of Stage values from the parsed stage string and pass it into platform_module.build from main.py. Update the PlatformModule protocol and all platform-specific build() signatures to accept a stages parameter with default ALL_STAGES. Wire stages through Android, iOS, macOS, Pyodide, Windows, and Linux build pipelines via run_host_build or build_in_container.	cibuildwheel/__main__.py cibuildwheel/options.py cibuildwheel/platforms/__init__.py cibuildwheel/platforms/android.py cibuildwheel/platforms/ios.py cibuildwheel/platforms/macos.py cibuildwheel/platforms/pyodide.py cibuildwheel/platforms/windows.py cibuildwheel/platforms/linux.py
Gate Linux container build pipeline steps by stage and support test-only runs consuming prebuilt wheels.	Add stages parameter to linux.build and linux.build_in_container with default ALL_STAGES. Guard before_all, build/test decision branches, wheel copying back to host, and output_wheel movement with Stage.BUILD/Stage.TEST checks as appropriate. In test-only mode (no Stage.BUILD), locate a prebuilt wheel from the host output_dir using find_built_wheel, copy it into the container, and treat it as the repaired_wheel. Ensure build-only mode skips tests and avoids copying wheels when not building.	cibuildwheel/platforms/linux.py
Add shared host build stage gating tests via a fake backend for run_host_build.	Introduce unit_test/run_host_build_test.py with a FakeBackend that records which phases run and a FakeOptions wrapper feeding into run_host_build. Test all-stages, build-only, and test-only flows, including behavior when prebuilt wheels are missing. Verify that wheels are moved to the output directory only in build-capable stages and that test-only runs reuse existing wheels.	unit_test/run_host_build_test.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.