docs: print a couple slighly more detailed error messages

cibuildwheel/errors.py

@@ -35,11 +35,14 @@ def __init__(self) -> None:
             """
             Build failed because a pure Python wheel was generated.
 
-            If you intend to build a pure-Python wheel, you don't need cibuildwheel - use
-            `pip wheel -w DEST_DIR .` instead.
-
-            If you expected a platform wheel, check your project configuration, or run
-            cibuildwheel with CIBW_BUILD_VERBOSITY=1 to view build logs.
+            If you intend to build a pure-Python wheel, you don't need
+            cibuildwheel - use `pip wheel .`, `pipx run build --wheel`, `uv
+            build --wheel`, etc. instead. You only need cibuildwheel if you
+            have compiled (not Python) code in your wheels making them depend
+            on the platform.
+
+            If you expected a platform wheel, check your project configuration,
+            or run cibuildwheel with CIBW_BUILD_VERBOSITY=1 to view build logs.
             """
         )
         super().__init__(message)

cibuildwheel/macos.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import functools
+import inspect
 import os
 import platform
 import re
@@ -149,11 +150,15 @@ def install_cpython(tmp: Path, version: str, url: str, free_threading: bool) ->
             if detect_ci_provider() is None:
                 # if running locally, we don't want to install CPython with sudo
                 # let the user know & provide a link to the installer
-                msg = (
-                    f"Error: CPython {version} is not installed.\n"
-                    "cibuildwheel will not perform system-wide installs when running outside of CI.\n"
-                    f"To build locally, install CPython {version} on this machine, or, disable this version of Python using CIBW_SKIP=cp{version.replace('.', '')}-macosx_*\n"
-                    f"\nDownload link: {url}"
+                msg = inspect.cleandoc(
+                    f"""
+                        Error: CPython {version} is not installed.
+                        cibuildwheel will not perform system-wide installs when running outside of CI.
+                        To build locally, install CPython {version} on this machine, or, disable this
+                        version of Python using CIBW_SKIP=cp{version.replace('.', '')}-macosx_*
+                        For portable builds, cibuildwheel needs the official builds from python.org.
+                        Download link: {url}
+                    """
                 )
                 raise errors.FatalError(msg)
             pkg_path = tmp / "Python.pkg"