Validate pyodide-version option against Pyodide build identifier (#2925)

* Validate pyodide-version against identifier

* Add tests

* Allow Pyodide nightly xbuildenvs too (for later)

.github/workflows/copilot-setup-steps.yml

@@ -19,7 +19,7 @@ jobs:
       contents: read
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -28,7 +28,7 @@ jobs:
           python-version: "3.x"
           allow-prereleases: true
 
-      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
 
       - name: Install tooling
         run: |

.github/workflows/release.yml

@@ -13,7 +13,7 @@ jobs:
   dist:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+    - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       with:
         persist-credentials: false
 

.github/workflows/test.yml

@@ -39,13 +39,13 @@ jobs:
     name: Linters (mypy, ruff, etc.)
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+    - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       with:
         persist-credentials: false
     - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
       with:
         python-version: "3.x"
-    - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+    - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
     - uses: j178/prek-action@bdca6f102f98e2b4c7029491a53dfd366469e33d # v2.0.4
     - name: PyLint checks
       run: uvx nox -s pylint -- --output-format=github
@@ -55,14 +55,14 @@ jobs:
     needs: lint
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+    - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       with:
         persist-credentials: false
     - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
       name: Install Python
       with:
         python-version: "3.x"
-    - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+    - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
     - name: Install dependencies
       run: uv sync --no-dev --group test
     - name: Generate a sample project
@@ -117,7 +117,7 @@ jobs:
           test_select: android
     timeout-minutes: 180
     steps:
-    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+    - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       with:
         persist-credentials: false
     - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
@@ -126,7 +126,7 @@ jobs:
         python-version: ${{ matrix.python_version }}
         allow-prereleases: true
 
-    - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+    - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
 
     - name: Free up disk space
       if: runner.os == 'Linux' && matrix.test_select != 'android'
@@ -247,13 +247,13 @@ jobs:
     outputs:
       archs: ${{ steps.archs.outputs.archs }}
     steps:
-    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+    - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       with:
         persist-credentials: false
     - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
       with:
         python-version: "3.x"
-    - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+    - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
     - name: Install dependencies
       run: uv sync --no-dev --group test
     - name: Get qemu emulated architectures
@@ -272,13 +272,13 @@ jobs:
       matrix:
         arch: ${{ fromJSON(needs.emulated-archs.outputs.archs) }}
     steps:
-    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+    - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       with:
         persist-credentials: false
     - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
       with:
         python-version: "3.x"
-    - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+    - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
     - name: Install dependencies
       run: uv sync --no-dev --group test
 
@@ -296,14 +296,14 @@ jobs:
     runs-on: ubuntu-24.04
     timeout-minutes: 180
     steps:
-    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+    - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       with:
         persist-credentials: false
     - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
       name: Install Python 3.12
       with:
         python-version: '3.12'
-    - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+    - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
 
     - name: Install dependencies
       run: uv sync --no-dev --group test
@@ -348,7 +348,7 @@ jobs:
         - os: macos-15
           test_select: android
     steps:
-    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+    - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       with:
         persist-credentials: false
     - name: Download a sample project

.github/workflows/update-dependencies.yml

@@ -37,11 +37,11 @@ jobs:
         permission-contents: write
         permission-pull-requests: write
 
-    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+    - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       with:
         persist-credentials: false
 
-    - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+    - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
       with:
         python-version: "3.14"
 

.github/workflows/update-major-minor-tag.yml

@@ -21,7 +21,7 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 

.github/workflows/zizmor.yml

@@ -16,7 +16,7 @@ jobs:
       security-events: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 

.pre-commit-config.yaml

@@ -37,7 +37,6 @@ repos:
       - dependency-groups>=1.2
       - humanize
       - nox>=2025.2.9
-      - orjson
       - packaging
       - pygithub
       - pytest

cibuildwheel/architecture.py

@@ -107,13 +107,29 @@ class Architecture(StrEnum):
                 case "auto32":
                     result |= cls.bitness_archs(platform=platform, bitness="32")
                 case _:
-                    try:
-                        result.add(cls(arch_str))
-                    except ValueError as e:
+                    if arch := cls._parse_arch_name(arch_str, platform=platform):
+                        result.add(arch)
+                    else:
                         msg = f"Invalid architecture '{arch_str}'"
-                        raise errors.ConfigurationError(msg) from e
+                        raise errors.ConfigurationError(msg)
         return result
 
+    @classmethod
+    def _parse_arch_name(cls, arch_str: str, platform: PlatformName) -> Self | None:
+        """Resolve an architecture name case-insensitively.
+
+        The same value (e.g. "arm64"/"ARM64") can map to different members
+        depending on the platform, so prefer a member valid for ``platform``
+        before falling back to any case-insensitive match.
+        """
+        for arch in cls.all_archs(platform):
+            if arch.value.lower() == arch_str.lower():
+                return arch
+        for arch in cls:
+            if arch.value.lower() == arch_str.lower():
+                return arch
+        return None
+
     @classmethod
     def native_arch(cls, platform: PlatformName) -> Self | None:
         native_machine = platform_module.machine()

cibuildwheel/options.py

@@ -833,9 +833,11 @@ class Options:
                     msg = f"Failed to parse test runtime config. {e}"
                     raise errors.ConfigurationError(msg) from e
 
-            test_requires = self.reader.get(
-                "test-requires", option_format=ListFormat(sep=" ")
-            ).split()
+            test_requires = shlex.split(
+                self.reader.get(
+                    "test-requires", option_format=ListFormat(sep=" ", quote=shlex.quote)
+                )
+            )
             test_extras = self.reader.get("test-extras", option_format=ListFormat(sep=","))
             test_groups_str = self.reader.get("test-groups", option_format=ListFormat(sep=" "))
             test_groups = [x for x in test_groups_str.split() if x]
@@ -932,9 +934,11 @@ class Options:
             )
             audit_command = audit_command_str.split(" && ") if audit_command_str else []
 
-            audit_requires = self.reader.get(
-                "audit-requires", option_format=ListFormat(sep=" ")
-            ).split()
+            audit_requires = shlex.split(
+                self.reader.get(
+                    "audit-requires", option_format=ListFormat(sep=" ", quote=shlex.quote)
+                )
+            )
 
             return BuildOptions(
                 globals=self.globals,

cibuildwheel/platforms/pyodide.py

@@ -218,6 +218,36 @@ def validate_pyodide_build_version(
         raise errors.FatalError(msg)
 
 
+def validate_pyodide_target_python(
+    xbuildenv_info: PyodideXBuildEnvInfo, python_configuration: PythonConfiguration
+) -> None:
+    """
+    Validate that the resolved Pyodide xbuildenv targets the same Python version
+    as the identifier being built.
+
+    This is to catch the case where a global ``pyodide-version`` is applied to an
+    identifier whose Python version does not match, such as setting
+    ``pyodide-version = "3Y.0.0"`` (a Python 3.Y environment) while
+    building ``cp3X-pyodide_wasm32``.
+    """
+    xbuildenv_version = xbuildenv_info["version"]
+    identifier = python_configuration.identifier
+    expected_version = python_configuration.version
+    default_version = python_configuration.default_pyodide_version
+    xbuildenv_python_minor = ".".join(xbuildenv_info["python"].split(".")[:2])
+    if xbuildenv_python_minor != expected_version:
+        msg = unwrap_preserving_paragraphs(f"""
+            The `pyodide-version` option is set to {xbuildenv_version}, which
+            provides Python {xbuildenv_python_minor}, but the {identifier} build
+            needs Python {expected_version}.
+
+            Either remove `pyodide-version` so {identifier} uses its default
+            ({default_version}), or stop building {identifier} so that
+            `pyodide-version` only applies to an identifier it matches.
+        """)
+        raise errors.ConfigurationError(msg)
+
+
 def install_xbuildenv(env: dict[str, str], xbuildenv_cache_path: Path, pyodide_version: str) -> str:
     """Install a particular Pyodide xbuildenv version and set a path to the Pyodide root."""
     pyodide_root = xbuildenv_cache_path / pyodide_version / "xbuildenv" / "pyodide-root"
@@ -337,6 +367,10 @@ def setup_python(
         xbuildenv_info=xbuildenv_info,
         pyodide_build_version=pyodide_build_version,
     )
+    validate_pyodide_target_python(
+        xbuildenv_info=xbuildenv_info,
+        python_configuration=python_configuration,
+    )
 
     xbuildenv_cache_path = CIBW_CACHE_PATH / f"pyodide-build-{pyodide_build_version}"
 

docs/options.md

@@ -807,9 +807,9 @@ instead.
 ### `before-build` {: #before-build env-var toml}
 > Execute a shell command preparing each wheel's build
 
-A shell command to run before building the wheel. This option allows you to run a command in **each** Python environment before the `pip wheel` command. This is useful if you need to set up some dependency so it's available during the build.
+A shell command to run before building the wheel. This option allows you to run a command in **each** Python environment before the wheel is built. This is useful if you need to set up some dependency so it's available during the build.
 
-If dependencies are required to build your wheel (for example if you include a header from a Python module), instead of using this command, we recommend adding requirements to a `pyproject.toml` file's `build-system.requires` array instead. This is reproducible, and users who do not get your wheels (such as Alpine or ClearLinux users) will still benefit.
+If dependencies are required to build your wheel (for example if you include a header from a Python module), instead of using this command, we recommend adding requirements to a `pyproject.toml` file's `build-system.requires` array instead. This is reproducible, and users who do not get your wheels (such as BSD operating system variants) will still benefit.
 
 The active Python binary can be accessed using `python`, and pip with `pip`; cibuildwheel makes sure the right version of Python and pip will be executed. The placeholder `{package}` can be used here; it will be replaced by the path to the package being built by cibuildwheel.
 
@@ -1670,6 +1670,10 @@ Platform-specific environment variables are also available:<br/>
     # Install specific versions of test dependencies
     [tool.cibuildwheel]
     test-requires = ["pytest==8.2.2", "packaging==24.1"]
+
+    # Dependency specifiers with environment markers are supported
+    [tool.cibuildwheel]
+    test-requires = ["pytest", "pyzstd; python_version >= '3.14'"]
     ```
 
     In configuration files, you can use an array, and the items will be joined with a space.
@@ -1682,6 +1686,10 @@ Platform-specific environment variables are also available:<br/>
 
     # Install specific versions of test dependencies
     CIBW_TEST_REQUIRES: pytest==8.2.2 packaging==24.1
+
+    # Use shell-style quoting around specifiers containing spaces, such as
+    # those with environment markers
+    CIBW_TEST_REQUIRES: "pytest 'pyzstd; python_version >= \"3.14\"'"
     ```
 
 

test/test_android.py

@@ -405,7 +405,11 @@ def test_environment_markers(tmp_path: Path) -> None:
             **cp313_env,
             "CIBW_TEST_COMMAND": f"python -m pytest {test_filename}",
             "CIBW_TEST_SOURCES": test_filename,
-            "CIBW_TEST_REQUIRES": "pytest certifi;sys_platform=='android' platformdirs;sys_platform!='android'",
+            "CIBW_TEST_REQUIRES": (
+                "pytest"
+                " 'certifi; sys_platform == \"android\"'"
+                " 'platformdirs; sys_platform != \"android\"'"
+            ),
         },
     )
 

unit_test/architecture_test.py

@@ -7,6 +7,7 @@ import sys
 import pytest
 
 import cibuildwheel.architecture
+import cibuildwheel.errors
 from cibuildwheel.architecture import Architecture, arch_synonym
 
 TYPE_CHECKING = False
@@ -142,3 +143,33 @@ def test_arch_synonym(
     arch: str, from_platform: PlatformName, to_platform: PlatformName, expected: str | None
 ) -> None:
     assert arch_synonym(arch, from_platform, to_platform) == expected
+
+
+@pytest.mark.parametrize(
+    ("config", "platform", "expected"),
+    [
+        # Case-insensitive, platform-resolved names (issue #2373).
+        ("arm64", "windows", {Architecture.ARM64}),
+        ("ARM64", "windows", {Architecture.ARM64}),
+        ("amd64", "windows", {Architecture.AMD64}),
+        ("AMD64", "windows", {Architecture.AMD64}),
+        ("X86", "windows", {Architecture.x86}),
+        ("x86", "windows", {Architecture.x86}),
+        # macOS resolves the lowercase arm64 even when given uppercase.
+        ("ARM64", "macos", {Architecture.arm64}),
+        ("arm64", "macos", {Architecture.arm64}),
+        ("X86_64", "macos", {Architecture.x86_64}),
+        # Multiple, mixed-case archs in one config string.
+        ("arm64 amd64", "windows", {Architecture.ARM64, Architecture.AMD64}),
+    ],
+)
+def test_arch_parse_config_case_insensitive(
+    config: str, platform: PlatformName, expected: set[Architecture]
+) -> None:
+    assert Architecture.parse_config(config, platform) == expected
+
+
+@pytest.mark.parametrize("platform", ["windows", "macos", "linux"])
+def test_arch_parse_config_invalid(platform: PlatformName) -> None:
+    with pytest.raises(cibuildwheel.errors.ConfigurationError):
+        Architecture.parse_config("nonexistent", platform)

unit_test/options_test.py

@@ -25,12 +25,19 @@ from cibuildwheel.options import (
     _get_pinned_container_images,
 )
 from cibuildwheel.platforms import ALL_PLATFORM_MODULES, get_build_identifiers
+from cibuildwheel.platforms.pyodide import (
+    PyodideXBuildEnvInfo,
+    validate_pyodide_target_python,
+)
+from cibuildwheel.platforms.pyodide import (
+    PythonConfiguration as PyodidePythonConfiguration,
+)
 from cibuildwheel.util import resources
 from cibuildwheel.util.packaging import DependencyConstraints
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Callable, Sequence
 
 PYPROJECT_1 = """
 [tool.cibuildwheel]
@@ -106,6 +113,91 @@ def test_options_1(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
     assert local.pyodide_version == "0.29.4"
 
 
+@pytest.fixture
+def make_pyodide_xbuildenv_info() -> Callable[[str, str], PyodideXBuildEnvInfo]:
+    def _make(version: str, python: str) -> PyodideXBuildEnvInfo:
+        return {
+            "version": version,
+            "python": python,
+            "emscripten": "5.0.3",
+            "pyodide_build": {"min": None, "max": None},
+            "compatible": True,
+        }
+
+    return _make
+
+
+@pytest.fixture
+def make_pyodide_python_configuration() -> Callable[[str, str], PyodidePythonConfiguration]:
+    def _make(identifier: str, version: str) -> PyodidePythonConfiguration:
+        return PyodidePythonConfiguration(
+            version=version,
+            identifier=identifier,
+            default_pyodide_version="0.0.0",
+            node_version="v22",
+        )
+
+    return _make
+
+
+def test_validate_pyodide_target_python_matching(
+    make_pyodide_xbuildenv_info: Callable[[str, str], PyodideXBuildEnvInfo],
+    make_pyodide_python_configuration: Callable[[str, str], PyodidePythonConfiguration],
+) -> None:
+    xbuildenv_info = make_pyodide_xbuildenv_info("314.0.0", "3.14.2")
+    config = make_pyodide_python_configuration("cp314-pyodide_wasm32", "3.14")
+    # should not raise
+    validate_pyodide_target_python(xbuildenv_info, config)
+
+
+def test_validate_pyodide_target_python_mismatch(
+    make_pyodide_xbuildenv_info: Callable[[str, str], PyodideXBuildEnvInfo],
+    make_pyodide_python_configuration: Callable[[str, str], PyodidePythonConfiguration],
+) -> None:
+    # a Python 3.14 xbuildenv applied to a cp313-pyodide_wasm32 build, when a global
+    # pyodide-version is set across mismatched targets
+    xbuildenv_info = make_pyodide_xbuildenv_info("314.0.0", "3.14.2")
+    config = make_pyodide_python_configuration("cp313-pyodide_wasm32", "3.13")
+
+    with pytest.raises(errors.ConfigurationError) as exc_info:
+        validate_pyodide_target_python(xbuildenv_info, config)
+
+    message = str(exc_info.value)
+    assert "cp313-pyodide_wasm32" in message
+    assert "314.0.0" in message
+    assert "3.13" in message
+    assert "3.14" in message
+
+
+def test_test_and_audit_requires_with_dependency_specifiers(tmp_path: Path) -> None:
+    """Regression test for https://github.com/pypa/cibuildwheel/issues/2912"""
+    pyproject_toml = tmp_path / "pyproject.toml"
+    pyproject_toml.write_text(
+        """
+[tool.cibuildwheel]
+test-requires = [
+    "pytest",
+    "pyzstd; python_version >= '3.14'",
+    "zarr>=3",
+]
+audit-requires = ["abi3audit; python_version >= '3.9'"]
+"""
+    )
+
+    args = CommandLineArguments.defaults()
+    args.package_dir = tmp_path
+
+    options = Options(platform="linux", command_line_arguments=args, env={})
+    build_options = options.build_options(identifier=None)
+
+    assert build_options.test_requires == [
+        "pytest",
+        "pyzstd; python_version >= '3.14'",
+        "zarr>=3",
+    ]
+    assert build_options.audit_requires == ["abi3audit; python_version >= '3.9'"]
+
+
 def test_passthrough(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
     with tmp_path.joinpath("pyproject.toml").open("w") as f:
         f.write(PYPROJECT_1)