fix(macos): make matching python3-config available in build/test venvs

[henryiii]

🤖 AI text below 🤖

Problem

On macOS, cibuildwheel builds and tests inside a virtualenv and only adds the venv's bin directory to PATH. Virtualenvs do not contain a python3-config (or versioned python{X.Y}-config) script. The python.org framework installs (/Library/Frameworks/Python.framework/Versions/{version}/bin/) do ship python3-config, but that directory is never placed on PATH.

As a result, complex C/C++ extension builds that invoke python3-config (to obtain include dirs / link flags) fall through to an unrelated python3-config found elsewhere on PATH — typically the system or Homebrew Python (e.g. /opt/homebrew/bin/python3-config). This produces broken wheels or ABI mismatches.

Root cause

cibuildwheel/venv.py creates the venv and activate_virtualenv only prepends the venv bin to PATH. No python*-config exists in that bin, and the matching one next to the base interpreter is not exposed.

Fix

After the venv is created (POSIX only), symlink the base interpreter's python*-config scripts into the venv's bin directory so the correct one is found first on PATH. This is done in a small helper _symlink_python_config_scripts(base_python, venv_bin) called from virtualenv().

• Uses a python*-config glob next to the base interpreter, so both the unversioned python3-config and the versioned python3.X-config are linked when present.
• Pre-existing entries in the venv bin are never overwritten.
• OSError during symlink creation is suppressed, so the build is never failed by this best-effort step.

Edge cases / limitations

• Windows: skipped entirely (config scripts are a POSIX concept; guarded by _IS_WIN).
• PyPy / GraalPy: these ship pypy3-config / similar, which the python*-config glob does not match, so nothing is linked — by design. The build is never failed when no config script exists.
• uv-managed interpreters: may not ship a config script; handled gracefully (nothing linked).
• This helper runs for all POSIX virtualenv() callers (macOS, iOS, Android, pyodide, audit), but only acts when a matching python*-config actually exists next to the base interpreter, so non-macOS flows are effectively unaffected.

Testing

Added unit_test/venv_test.py covering the helper directly (the full virtualenv() path requires network/installs and a real framework Python, so a true end-to-end unit test is impractical):

• a base interpreter with python3-config + python3.X-config gets both linked into the venv bin;
• a PyPy-style base (only pypy3-config) links nothing;
• a pre-existing real python3-config in the venv bin is left untouched.

All three pass; the full unit_test suite passes (791 passed). ruff, ruff-format, codespell, and flake8-lazy pass on the changed files; mypy is clean on venv.py apart from the pre-existing uv import-stub note that the project config already ignores.

Note for reviewers: the helper is best-effort (uses symlinks, suppresses OSError). Open question: should it prefer copying over symlinking, or restrict the behavior to the CPython/macOS path only rather than all POSIX virtualenv() callers? Happy to narrow the scope if preferred.

Closes #2021