refactor: address review comments

Signed-off-by: Henry Schreiner <[email protected]>

Author: henryiii

cibuildwheel/frontend.py

@@ -37,16 +37,19 @@ def options_summary(self) -> str | dict[str, str]:
 
 
 def _get_verbosity_flags(level: int, frontend: BuildFrontendName) -> list[str]:
-    if frontend == "pip":
-        if level > 0:
-            return ["-" + level * "v"]
-        if level < 0:
+    if level < 0:
+        if frontend == "pip":
             return ["-" + -level * "q"]
-    elif level > 1:
-        return ["-v"]
-    elif level < 0:
+
         msg = f"build_verbosity {level} is not supported for {frontend} frontend. Ignoring."
         log.warning(msg)
+
+    if level > 0:
+        if frontend == "pip":
+            return ["-" + level * "v"]
+        if level > 1:
+            return ["-" + (level - 1) * "v"]
+
     return []
 
 

docs/options.md

@@ -1762,14 +1762,25 @@ export CIBW_DEBUG_TRACEBACK=TRUE
 ### `CIBW_BUILD_VERBOSITY` {: #build-verbosity}
 > Increase/decrease the output of the build
 
-The setting vary a bit between build frontends.
-
-* `-1`: Hide as much build output as possible; passes `-q` to the build frontend. Not supported by `build`/`build[uv]`.
-* `0`: The default. On pip, this hides the build output if the build succeeds, other build frontends produce output from the build backend.
-* `1`: Produces build backend output. On `pip`, this passes `-v`. Other frontends do this by default.
-* `2`: Produces extra output from resolving packages too. On `pip`, this passes `-vv`, other build frontends use `-v`.
-* `3`: Even more resolving output from pip with `-vvv`, other build frontends continue to just pass `-v`.
-
+This setting controls `-v`/`-q` flags to the build frontend. Since there is
+no communication between the build backend and the build frontend, build
+messages from the build backend will always be shown with `1`; higher levels
+will not produce more logging about the build itself. Other levels only affect
+the build frontend output, which is usually things like resolving and
+downloading dependencies. The settings are:
+
+|             | build | pip    | desc                             |
+|-------------|-------|--------|----------------------------------|
+| -2          | N/A   | `-qq`  | even more quiet, where supported |
+| -1          | N/A   | `-q`   | quiet mode, where supported      |
+| 0 (default) |       |        | default for build tool           |
+| 1           |       | `-v`   | print backend output             |
+| 2           | `-v`  | `-vv`  | print log messages e.g. resolving info |
+| 3           | `-vv` | `-vvv` | print even more debug info       |
+
+Settings that are not supported for a specific frontend will log a warning.
+The default build frontend is `build`, which does show build backend output by
+default.
 
 Platform-specific environment variables are also available:<br/>
 `CIBW_BUILD_VERBOSITY_MACOS` | `CIBW_BUILD_VERBOSITY_WINDOWS` | `CIBW_BUILD_VERBOSITY_LINUX` | `CIBW_BUILD_VERBOSITY_IOS` | `CIBW_BUILD_VERBOSITY_PYODIDE`
@@ -1779,15 +1790,15 @@ Platform-specific environment variables are also available:<br/>
 !!! tab examples "Environment variables"
 
     ```yaml
-    # Increase pip debugging output
+    # Ensure that the build backend output is present
     CIBW_BUILD_VERBOSITY: 1
     ```
 
 !!! tab examples "pyproject.toml"
 
     ```toml
     [tool.cibuildwheel]
-    # Increase pip debugging output
+    # Ensure that the build backend output is present
     build-verbosity = 1
     ```
 

unit_test/options_test.py

@@ -585,8 +585,8 @@ def test_deprecated_image(
         ("build", 0, ["-Ca", "-Cb", "-1"]),
         ("build", 1, ["-Ca", "-Cb", "-1"]),
         ("build", 2, ["-Ca", "-Cb", "-1", "-v"]),
-        ("build", 3, ["-Ca", "-Cb", "-1", "-v"]),
-        ("build[uv]", 3, ["-Ca", "-Cb", "-1", "-v"]),
+        ("build", 3, ["-Ca", "-Cb", "-1", "-vv"]),
+        ("build[uv]", 3, ["-Ca", "-Cb", "-1", "-vv"]),
     ],
 )
 def test_get_build_frontend_extra_flags(