From 18f54c08e2106c005728f4d09f921c3607c669db Mon Sep 17 00:00:00 2001
From: Henry Schreiner <HenrySchreinerIII@gmail.com>
Date: Fri, 18 Oct 2024 08:52:05 -0400
Subject: [PATCH] docs: print a couple slighly more detailed error messages
 (#2044)

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
---
 cibuildwheel/errors.py | 13 ++++++++-----
 cibuildwheel/macos.py  | 15 ++++++++++-----
 2 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/cibuildwheel/errors.py b/cibuildwheel/errors.py
index a1cc6a33c..6f828b630 100644
--- a/cibuildwheel/errors.py
+++ b/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)
diff --git a/cibuildwheel/macos.py b/cibuildwheel/macos.py
index 0a07bb651..2a65da733 100644
--- a/cibuildwheel/macos.py
+++ b/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"