Merge branch 'main' into 1576-create-a-prek-hook-to-automatically-export-the-module-structure-with-docstrings-to-a-tree-diagram-file

nathanjmcdougall · web-flow · commit 11d8b944d9b4 · 2026-03-27T16:53:44.000+13:00
diff --git a/docs/cli/reference.md b/docs/cli/reference.md
@@ -475,6 +475,10 @@ Additional configuration in `pyproject.toml`:
 - `tool.usethis.sonarqube.exclusions` (list of strings, default `[]`) — sets `sonar.exclusions`.
 - `tool.coverage.xml.output` (string, required) — sets `sonar.python.coverage.reportPaths`.
 
+Supported options:
+
+- `--output-file` to write the output to a file instead of stdout.
+
 ## `usethis browse pypi <package>`
 
 Display or open the PyPI landing page associated with another project.
diff --git a/src/usethis/_core/show.py b/src/usethis/_core/show.py
@@ -2,19 +2,37 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from usethis._backend.dispatch import get_backend
 from usethis._console import plain_print
 from usethis._integrations.project.name import get_project_name
 from usethis._integrations.sonarqube.config import get_sonar_project_properties
 
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def show_backend(*, output_file: Path | None = None) -> None:
+    _output(get_backend().value, output_file=output_file)
+
 
-def show_backend() -> None:
-    plain_print(get_backend().value)
+def show_name(*, output_file: Path | None = None) -> None:
+    _output(get_project_name(), output_file=output_file)
 
 
-def show_name() -> None:
-    plain_print(get_project_name())
+def show_sonarqube_config(
+    *, project_key: str | None = None, output_file: Path | None = None
+) -> None:
+    _output(
+        get_sonar_project_properties(project_key=project_key), output_file=output_file
+    )
 
 
-def show_sonarqube_config(*, project_key: str | None = None) -> None:
-    plain_print(get_sonar_project_properties(project_key=project_key))
+def _output(content: str, *, output_file: Path | None = None) -> None:
+    if output_file is not None:
+        if not content.endswith("\n"):
+            content += "\n"
+        output_file.write_text(content, encoding="utf-8")
+    else:
+        plain_print(content)
diff --git a/src/usethis/_ui/interface/show.py b/src/usethis/_ui/interface/show.py
@@ -1,9 +1,11 @@
 """CLI commands for showing project information."""
 
+from pathlib import Path
+
 import typer
 
 from usethis._config import usethis_config
-from usethis._ui.options import offline_opt, quiet_opt
+from usethis._ui.options import offline_opt, output_file_opt, quiet_opt
 
 app = typer.Typer(
     help="Show information about the current project.", add_completion=False
@@ -21,6 +23,7 @@
 def backend(
     offline: bool = offline_opt,
     quiet: bool = quiet_opt,
+    output_file: Path | None = output_file_opt,
 ) -> None:
     from usethis._config_file import files_manager
     from usethis._console import err_print
@@ -29,7 +32,7 @@ def backend(
 
     with usethis_config.set(offline=offline, quiet=quiet), files_manager():
         try:
-            show_backend()
+            show_backend(output_file=output_file)
         except UsethisError as err:
             err_print(err)
             raise typer.Exit(code=1) from None
@@ -39,6 +42,7 @@ def backend(
 def name(
     offline: bool = offline_opt,
     quiet: bool = quiet_opt,
+    output_file: Path | None = output_file_opt,
 ) -> None:
     from usethis._config_file import files_manager
     from usethis._console import err_print
@@ -47,7 +51,7 @@ def name(
 
     with usethis_config.set(offline=offline, quiet=quiet), files_manager():
         try:
-            show_name()
+            show_name(output_file=output_file)
         except UsethisError as err:
             err_print(err)
             raise typer.Exit(code=1) from None
@@ -61,6 +65,7 @@ def sonarqube(
     offline: bool = offline_opt,
     quiet: bool = quiet_opt,
     project_key: str | None = project_key_opt,
+    output_file: Path | None = output_file_opt,
 ) -> None:
     from usethis._config_file import files_manager
     from usethis._console import err_print
@@ -69,7 +74,7 @@ def sonarqube(
 
     with usethis_config.set(offline=offline, quiet=quiet), files_manager():
         try:
-            show_sonarqube_config(project_key=project_key)
+            show_sonarqube_config(project_key=project_key, output_file=output_file)
         except UsethisError as err:
             err_print(err)
             raise typer.Exit(code=1) from None
diff --git a/src/usethis/_ui/options.py b/src/usethis/_ui/options.py
@@ -106,6 +106,13 @@
 # status command options
 status_arg = typer.Argument(default=..., help="Docstring style to enforce.")
 
+# show command options
+output_file_opt = typer.Option(
+    None,
+    "--output-file",
+    help="Write output to this file instead of stdout.",
+)
+
 # ruff command options
 linter_opt = typer.Option(
     True,
diff --git a/tests/usethis/_ui/interface/test_show.py b/tests/usethis/_ui/interface/test_show.py
@@ -32,6 +32,22 @@ def test_none_backend(self, tmp_path: Path):
         assert result.exit_code == 0, result.output
         assert result.output == "none\n"
 
+    def test_output_file(self, tmp_path: Path):
+        # Arrange
+        (tmp_path / "uv.lock").touch()
+        output_file = tmp_path / "backend.txt"
+
+        # Act
+        runner = CliRunner()
+        with change_cwd(tmp_path):
+            result = runner.invoke_safe(
+                app, ["backend", "--output-file", str(output_file)]
+            )
+
+        # Assert
+        assert result.exit_code == 0, result.output
+        assert output_file.read_text(encoding="utf-8") == "uv\n"
+
 
 class TestName:
     def test_output(self, tmp_path: Path):
@@ -60,6 +76,23 @@ def test_invalid_pyproject(self, tmp_path: Path):
         # Assert
         assert result.exit_code == 1, result.output
 
+    def test_output_file(self, tmp_path: Path):
+        # Arrange
+        path = tmp_path / "fun"
+        path.mkdir()
+        output_file = path / "name.txt"
+
+        # Act
+        runner = CliRunner()
+        with change_cwd(path):
+            result = runner.invoke_safe(
+                app, ["name", "--output-file", str(output_file)]
+            )
+
+        # Assert
+        assert result.exit_code == 0, result.output
+        assert output_file.read_text(encoding="utf-8") == "fun\n"
+
 
 class TestSonarqube:
     def test_runs(self, tmp_path: Path):
@@ -162,3 +195,64 @@ def test_invalid_pyproject(self, tmp_path: Path):
 
         # Assert
         assert result.exit_code == 1, result.output
+
+    def test_output_file(self, tmp_path: Path):
+        # Arrange
+        (tmp_path / "pyproject.toml").write_text(
+            """
+[tool.usethis.sonarqube]
+project-key = "fun"
+
+[tool.coverage.xml.output]
+"""
+        )
+        output_file = tmp_path / "sonar-project.properties"
+
+        # Act
+        runner = CliRunner()
+        with change_cwd(tmp_path):
+            result = runner.invoke_safe(
+                app, ["sonarqube", "--output-file", str(output_file)]
+            )
+
+        # Assert
+        assert result.exit_code == 0, result.output
+        content = output_file.read_text(encoding="utf-8")
+        assert "sonar.projectKey=fun" in content
+
+    def test_output_file_not_detected_as_existing(self, tmp_path: Path):
+        """Using --output-file avoids the redirect problem.
+
+        When using shell redirect (`> file`), the file is created empty before
+        the command runs, which causes sonarqube to read that empty file.
+        With --output-file, the file is written after generation.
+        """
+        # Arrange
+        (tmp_path / "pyproject.toml").write_text(
+            """
+[tool.usethis.sonarqube]
+project-key = "fun"
+
+[tool.coverage.xml.output]
+"""
+        )
+        # Simulate what happens with shell redirect: an empty file pre-exists
+        output_file = tmp_path / "sonar-project.properties"
+        output_file.write_text("", encoding="utf-8")
+
+        # Act
+        # Despite sonar-project.properties existing (empty), --output-file
+        # still causes the config to be read from that file (by design of
+        # get_sonar_project_properties), then overwrites it with that content.
+        runner = CliRunner()
+        with change_cwd(tmp_path):
+            result = runner.invoke_safe(
+                app, ["sonarqube", "--output-file", str(output_file)]
+            )
+
+        # Assert
+        assert result.exit_code == 0, result.output
+        content = output_file.read_text(encoding="utf-8")
+        # With --output-file, the file is written after content generation,
+        # so even if it was previously empty, it will have the content now
+        assert content != ""
