refactor: prerelease-pythons

README.md

@@ -30,7 +30,7 @@ What does it do?
 | CPython 3.9     | ✅ | ✅ | ✅  | ✅  | ✅ | ✅ | ✅ | ✅ | ✅ |
 | CPython 3.10¹     | ✅ | ✅ | ✅  | ✅  | ✅ | ✅ | ✅ | ✅ | ✅ |
 | PyPy 3.7 v7.3   | ✅ |   | ✅  |    | ✅ |    |    |    |   |
-<sup>¹ Requires `--pre` flag to be passed - Python Beta candidates not recommended for upload to PyPI. </sup><br>
+<sup>¹ Available as a prerelease under a [flag](https://cibuildwheel.readthedocs.io/en/stable/options/#prerelease-pythons)</sup><br>
 
 - Builds manylinux, macOS 10.9+, and Windows wheels for CPython and PyPy
 - Works on GitHub Actions, Azure Pipelines, Travis CI, AppVeyor, CircleCI, and GitLab CI
@@ -108,6 +108,7 @@ Options
 |   | [`CIBW_BUILD`](https://cibuildwheel.readthedocs.io/en/stable/options/#build-skip)  <br> [`CIBW_SKIP`](https://cibuildwheel.readthedocs.io/en/stable/options/#build-skip)  | Choose the Python versions to build |
 |   | [`CIBW_ARCHS`](https://cibuildwheel.readthedocs.io/en/stable/options/#archs)  | Change the architectures built on your machine by default |
 |   | [`CIBW_PROJECT_REQUIRES_PYTHON`](https://cibuildwheel.readthedocs.io/en/stable/options/#requires-python)  | Manually set the Python compatibility of your project |
+|   | [`CIBW_PRERELEASE_PYTHONS`](https://cibuildwheel.readthedocs.io/en/stable/options/#prerelease-pythons)  | Enable building with pre-release versions of Python |
 | **Build customization** | [`CIBW_ENVIRONMENT`](https://cibuildwheel.readthedocs.io/en/stable/options/#environment)  | Set environment variables needed during the build |
 |   | [`CIBW_BEFORE_ALL`](https://cibuildwheel.readthedocs.io/en/stable/options/#before-all)  | Execute a shell command on the build system before any wheels are built. |
 |   | [`CIBW_BEFORE_BUILD`](https://cibuildwheel.readthedocs.io/en/stable/options/#before-build)  | Execute a shell command preparing each wheel's build |

cibuildwheel/__main__.py

@@ -133,7 +133,7 @@ def main() -> None:
     )
 
     parser.add_argument(
-        "--pre",
+        "--prerelease-pythons",
         action="store_true",
         help="Enable pre-release Python versions if available.",
     )
@@ -212,6 +212,9 @@ def main() -> None:
     build_verbosity_str = get_option_from_environment(
         "CIBW_BUILD_VERBOSITY", platform=platform, default=""
     )
+    prerelease_pythons = args.prerelease_pythons or get_option_from_environment(
+        "CIBW_PRERELEASE_PYTHONS", platform=platform, default="0"
+    ) not in {"", "0"}
 
     package_files = {"setup.py", "setup.cfg", "pyproject.toml"}
 
@@ -233,7 +236,7 @@ def main() -> None:
         build_config=build_config,
         skip_config=skip_config,
         requires_python=requires_python,
-        filter_prerelease="" if args.pre else "310",
+        filter_prerelease="" if prerelease_pythons else "310",
     )
     test_selector = TestSelector(skip_config=test_skip)
 

docs/options.md

@@ -299,6 +299,30 @@ the package is compatible with all versions of Python that it can build.
 CIBW_PROJECT_REQUIRES_PYTHON: ">=3.6"
 ```
 
+###  `CIBW_PRERELEASE_PYTHONS` {: #prerelease-pythons}
+> Enable building with pre-release versions of Python
+
+By default, cibuildwheel only builds wheels compatible with minor versions of
+Python. However, during the Beta period when new versions of Python are being
+tested, cibuildwheel will often gain early support for beta releases. If you
+would like to test wheel building with these versions, you can enable this
+flag.  Please _do not_ upload these wheels to PyPI, as they are not guaranteed
+to work with the final Python release. Once Python is ABI stable and enters the
+release candidate phase, that version of Python will become available without
+this flag.
+
+Default: Off (0) if Python is available in beta phase. No effect otherwise.
+
+Platform-specific variants also available:<br/>
+`CIBW_PRERELEASE_PYTHONS_MACOS` | `CIBW_PRERELEASE_PYTHONS_WINDOWS` | `CIBW_PRERELEASE_PYTHONS_LINUX`
+
+#### Examples
+
+```yaml
+# Include latest Python beta
+CIBW_PRERELEASE_PYTHONS=1
+```
+
 ## Build customization
 
 ### `CIBW_ENVIRONMENT` {: #environment}

test/utils.py

@@ -31,7 +31,7 @@ def cibuildwheel_get_build_identifiers(project_path, env=None, *, pre=False):
     """
     cmd = [sys.executable, "-m", "cibuildwheel", "--print-build-identifiers", str(project_path)]
     if pre:
-        cmd.append("--pre")
+        cmd.append("--prerelease-pythons")
 
     cmd_output = subprocess.run(
         cmd,
@@ -73,7 +73,7 @@ def cibuildwheel_run(project_path, package_dir=".", env=None, add_env=None, outp
                 sys.executable,
                 "-m",
                 "cibuildwheel",
-                "--pre",
+                "--prerelease-pythons",
                 "--output-dir",
                 str(output_dir or tmp_output_dir),
                 str(package_dir),