usethis-python · nathanjmcdougall · Oct 26, 2025 · Oct 26, 2025 · Oct 26, 2025 · Oct 26, 2025
diff --git a/src/usethis/_config.py b/src/usethis/_config.py
@@ -28,6 +28,8 @@ class UsethisConfig:
         quiet: Suppress all output, regardless of any other options.
         frozen: Do not install dependencies, nor update lockfiles.
         alert_only: Suppress all output except for warnings and errors.
+        instruct_only: Suppress all success and info output; do not suppress
+                       instructions, warnings, or errors.
         backend: The package manager backend to use. Attempted subprocesses to other
                  backends will raise an error.
         disable_pre_commit: Disable pre-commit integrations. Assume that pre-commit is
@@ -42,6 +44,7 @@ class UsethisConfig:
     quiet: bool = QUIET_DEFAULT
     frozen: bool = FROZEN_DEFAULT
     alert_only: bool = False
+    instruct_only: bool = False
     backend: BackendEnum = BackendEnum(BACKEND_DEFAULT)  # noqa: RUF009
     disable_pre_commit: bool = False
     subprocess_verbose: bool = False
@@ -55,6 +58,7 @@ def set(  # noqa: PLR0913
         quiet: bool | None = None,
         frozen: bool | None = None,
         alert_only: bool | None = None,
+        instruct_only: bool | None = None,
         backend: BackendEnum | None = None,
         disable_pre_commit: bool | None = None,
         subprocess_verbose: bool | None = None,
@@ -65,6 +69,7 @@ def set(  # noqa: PLR0913
         old_quiet = self.quiet
         old_frozen = self.frozen
         old_alert_only = self.alert_only
+        old_instruct_only = self.instruct_only
         old_backend = self.backend
         old_disable_pre_commit = self.disable_pre_commit
         old_subprocess_verbose = self.subprocess_verbose
@@ -78,6 +83,8 @@ def set(  # noqa: PLR0913
             frozen = old_frozen
         if alert_only is None:
             alert_only = self.alert_only
+        if instruct_only is None:
+            instruct_only = self.instruct_only
         if backend is None:
             backend = self.backend
         if disable_pre_commit is None:
@@ -91,6 +98,7 @@ def set(  # noqa: PLR0913
         self.quiet = quiet
         self.frozen = frozen
         self.alert_only = alert_only
+        self.instruct_only = instruct_only
         self.backend = backend
         self.disable_pre_commit = disable_pre_commit
         self.subprocess_verbose = subprocess_verbose
@@ -102,6 +110,7 @@ def set(  # noqa: PLR0913
         self.quiet = old_quiet
         self.frozen = old_frozen
         self.alert_only = old_alert_only
+        self.instruct_only = old_instruct_only
         self.backend = old_backend
         self.disable_pre_commit = old_disable_pre_commit
         self.subprocess_verbose = old_subprocess_verbose

diff --git a/src/usethis/_console.py b/src/usethis/_console.py
@@ -26,33 +26,60 @@
 def plain_print(msg: str | Exception) -> None:
     msg = str(msg)
 
-    if not (usethis_config.quiet or usethis_config.alert_only):
+    if not (
+        usethis_config.quiet
+        or usethis_config.alert_only
+        or usethis_config.instruct_only
+    ):
         console.print(msg)
 
 
 def table_print(table: Table) -> None:
-    if not (usethis_config.quiet or usethis_config.alert_only):
+    if not (
+        usethis_config.quiet
+        or usethis_config.alert_only
+        or usethis_config.instruct_only
+    ):
         console.print(table, justify="left", overflow="fold", soft_wrap=True)
 
 
 def tick_print(msg: str | Exception) -> None:
     msg = str(msg)
 
-    if not (usethis_config.quiet or usethis_config.alert_only):
+    if not (
+        usethis_config.quiet
+        or usethis_config.alert_only
+        or usethis_config.instruct_only
+    ):
         console.print(f"✔ {msg}", style="green")
 
 
-def box_print(msg: str | Exception) -> None:
+def instruct_print(msg: str | Exception) -> None:
     msg = str(msg)
 
     if not (usethis_config.quiet or usethis_config.alert_only):
         console.print(f"☐ {msg}", style="red")
 
 
+def how_print(msg: str | Exception) -> None:
+    msg = str(msg)
+
+    if not (
+        usethis_config.quiet
+        or usethis_config.alert_only
+        or usethis_config.instruct_only
+    ):
+        console.print(f"☐ {msg}", style="red")
+
+
 def info_print(msg: str | Exception, temporary: bool = False) -> None:
     msg = str(msg)
 
-    if not (usethis_config.quiet or usethis_config.alert_only):
+    if not (
+        usethis_config.quiet
+        or usethis_config.alert_only
+        or usethis_config.instruct_only
+    ):
         if temporary:
             end = "\r"
         else:

diff --git a/src/usethis/_core/browse.py b/src/usethis/_core/browse.py
@@ -2,12 +2,12 @@
 
 import typer
 
-from usethis._console import box_print
+from usethis._console import how_print
 
 
 def browse_pypi(*, package: str, browser: bool = False) -> None:
     url = f"https://pypi.org/project/{package}/"
     if browser:
         typer.launch(url)
     else:
-        box_print(f"Open URL <{url}>.")
+        how_print(f"Open URL <{url}>.")
diff --git a/src/usethis/_core/ci.py b/src/usethis/_core/ci.py
@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from usethis._console import box_print, info_print
+from usethis._console import how_print, info_print
 from usethis._integrations.ci.bitbucket.config import (
     add_bitbucket_pipeline_config,
     remove_bitbucket_pipeline_config,
@@ -62,4 +62,4 @@ def print_how_to_use_ci_bitbucket() -> None:
     if not PytestTool().is_used():
         info_print("Consider `usethis tool pytest` to test your code for the pipeline.")
 
-    box_print("Run your pipeline via the Bitbucket website.")
+    how_print("Run your pipeline via the Bitbucket website.")
diff --git a/src/usethis/_core/readme.py b/src/usethis/_core/readme.py
@@ -3,7 +3,7 @@
 from typing import TYPE_CHECKING
 
 from usethis._config import usethis_config
-from usethis._console import box_print, tick_print, warn_print
+from usethis._console import how_print, tick_print, warn_print
 from usethis._integrations.file.pyproject_toml.errors import PyprojectTOMLError
 from usethis._integrations.file.pyproject_toml.name import get_description
 from usethis._integrations.project.name import get_project_name
@@ -56,7 +56,7 @@ def add_readme() -> None:
 
     tick_print("Writing 'README.md'.")
     (usethis_config.cpd() / "README.md").write_text(content, encoding="utf-8")
-    box_print("Populate 'README.md' to help users understand the project.")
+    how_print("Populate 'README.md' to help users understand the project.")
 
 
 def get_readme_path():

diff --git a/src/usethis/_core/tool.py b/src/usethis/_core/tool.py
@@ -7,7 +7,7 @@
 from typing_extensions import assert_never
 
 from usethis._config import usethis_config
-from usethis._console import box_print, info_print, tick_print
+from usethis._console import info_print, instruct_print, tick_print
 from usethis._deps import get_project_deps
 from usethis._init import ensure_dep_declaration_file
 from usethis._integrations.backend.dispatch import get_backend
@@ -205,7 +205,9 @@ def use_pre_commit(*, remove: bool = False, how: bool = False) -> None:
         try:
             install_pre_commit_hooks()
         except PreCommitInstallationError:
-            box_print("Run 'uv run pre-commit install' to install pre-commit to Git.")
+            instruct_print(
+                "Run 'uv run pre-commit install' to install pre-commit to Git."
+            )
 
         tool.update_bitbucket_steps()
         if is_bitbucket_used():
@@ -220,7 +222,7 @@ def use_pre_commit(*, remove: bool = False, how: bool = False) -> None:
         try:
             uninstall_pre_commit_hooks()
         except PreCommitInstallationError:
-            box_print(
+            instruct_print(
                 "Run 'uv run pre-commit uninstall' to uninstall pre-commit from Git."
             )
 

diff --git a/src/usethis/_deps.py b/src/usethis/_deps.py
@@ -6,7 +6,7 @@
 from typing_extensions import assert_never
 
 from usethis._config import usethis_config
-from usethis._console import box_print, tick_print
+from usethis._console import instruct_print, tick_print
 from usethis._integrations.backend.dispatch import get_backend
 from usethis._integrations.backend.uv.call import add_default_groups_via_uv
 from usethis._integrations.backend.uv.deps import (
@@ -188,7 +188,7 @@ def remove_deps_from_group(deps: list[Dependency], group: str) -> None:
         for dep in _deps:
             remove_dep_from_group_via_uv(dep, group)
     elif backend is BackendEnum.none:
-        box_print(f"Remove the {group} dependenc{ies} {deps_str}.")
+        instruct_print(f"Remove the {group} dependenc{ies} {deps_str}.")
     else:
         assert_never(backend)
 
@@ -220,14 +220,14 @@ def add_deps_to_group(deps: list[Dependency], group: str) -> None:
             f"Adding dependenc{ies} {deps_str} to the '{group}' group in 'pyproject.toml'."
         )
     elif backend is BackendEnum.none:
-        box_print(f"Add the {group} dependenc{ies} {deps_str}.")
+        instruct_print(f"Add the {group} dependenc{ies} {deps_str}.")
     else:
         assert_never(backend)
 
     # Installation of the dependencies, and declaration if the package manager supports
     # a combined workflow.
     if usethis_config.frozen:
-        box_print(f"Install the dependenc{ies} {deps_str}.")
+        instruct_print(f"Install the dependenc{ies} {deps_str}.")
     for dep in to_add_deps:
         if backend is BackendEnum.uv:
             add_dep_to_group_via_uv(dep, group)

diff --git a/src/usethis/_init.py b/src/usethis/_init.py
@@ -25,7 +25,7 @@ def project_init():
         opinionated_uv_init()
     elif backend is BackendEnum.none:
         # pyproject.toml
-        with usethis_config.set(alert_only=True):
+        with usethis_config.set(instruct_only=True):
             ensure_pyproject_toml()
 
         # README.md

diff --git a/src/usethis/_integrations/ci/bitbucket/steps.py b/src/usethis/_integrations/ci/bitbucket/steps.py
@@ -9,7 +9,7 @@
 
 import usethis._pipeweld.func
 from usethis._config import usethis_config
-from usethis._console import box_print, tick_print
+from usethis._console import instruct_print, tick_print
 from usethis._integrations.backend.dispatch import get_backend
 from usethis._integrations.ci.bitbucket.anchor import (
     ScriptItemAnchor,
@@ -469,9 +469,11 @@ def add_placeholder_step_in_default(report_placeholder: bool = True) -> None:
         tick_print(
             "Adding placeholder step to default pipeline in 'bitbucket-pipelines.yml'."
         )
-        box_print("Remove the placeholder pipeline step in 'bitbucket-pipelines.yml'.")
-        box_print("Replace it with your own pipeline steps.")
-        box_print(
+        instruct_print(
+            "Remove the placeholder pipeline step in 'bitbucket-pipelines.yml'."
+        )
+        instruct_print("Replace it with your own pipeline steps.")
+        instruct_print(
             "Alternatively, use 'usethis tool' to add other tools and their steps."
         )
 

diff --git a/src/usethis/_integrations/pre_commit/core.py b/src/usethis/_integrations/pre_commit/core.py
@@ -3,7 +3,7 @@
 from typing_extensions import assert_never
 
 from usethis._config import usethis_config
-from usethis._console import box_print, info_print, tick_print
+from usethis._console import info_print, instruct_print, tick_print
 from usethis._integrations.backend.dispatch import get_backend
 from usethis._integrations.backend.uv.call import call_uv_subprocess
 from usethis._integrations.backend.uv.errors import UVSubprocessFailedError
@@ -32,10 +32,10 @@ def install_pre_commit_hooks() -> None:
 
     if usethis_config.frozen:
         if backend is BackendEnum.uv and is_uv_used():
-            box_print("Run 'uv run pre-commit install' to register pre-commit.")
+            instruct_print("Run 'uv run pre-commit install' to register pre-commit.")
         else:
             assert backend in (BackendEnum.none, BackendEnum.uv)
-            box_print("Run 'pre-commit install' to register pre-commit.")
+            instruct_print("Run 'pre-commit install' to register pre-commit.")
         return
 
     if backend is BackendEnum.uv:
@@ -58,7 +58,7 @@ def install_pre_commit_hooks() -> None:
             msg = f"Failed to install pre-commit hooks:\n{err}"
             raise PreCommitInstallationError(msg) from None
     elif backend is BackendEnum.none:
-        box_print("Run 'pre-commit install' to install pre-commit to Git.")
+        instruct_print("Run 'pre-commit install' to install pre-commit to Git.")
     else:
         assert_never(backend)
 
@@ -69,7 +69,7 @@ def uninstall_pre_commit_hooks() -> None:
     Note that this requires the user to be in a git repo.
     """
     if usethis_config.frozen:
-        box_print(
+        instruct_print(
             "Run 'uv run --with pre-commit pre-commit uninstall' to deregister pre-commit."
         )
         return
@@ -86,6 +86,6 @@ def uninstall_pre_commit_hooks() -> None:
             msg = f"Failed to uninstall pre-commit hooks:\n{err}"
             raise PreCommitInstallationError(msg) from None
     elif backend is BackendEnum.none:
-        box_print("Run 'pre-commit uninstall' to deregister pre-commit.")
+        instruct_print("Run 'pre-commit uninstall' to deregister pre-commit.")
     else:
         assert_never(backend)
diff --git a/src/usethis/_integrations/pre_commit/hooks.py b/src/usethis/_integrations/pre_commit/hooks.py
@@ -3,7 +3,7 @@
 from typing import TYPE_CHECKING
 
 from usethis._config import usethis_config
-from usethis._console import box_print, tick_print
+from usethis._console import instruct_print, tick_print
 from usethis._integrations.file.yaml.update import update_ruamel_yaml_map
 from usethis._integrations.pre_commit.dump import pre_commit_fancy_dump
 from usethis._integrations.pre_commit.io_ import (
@@ -179,9 +179,11 @@ def _report_adding_repo(repo: LocalRepo | UriRepo | MetaRepo) -> None:
 
 def add_placeholder_hook() -> None:
     add_repo(_get_placeholder_repo_config())
-    box_print("Remove the placeholder hook in '.pre-commit-config.yaml'.")
-    box_print("Replace it with your own hooks.")
-    box_print("Alternatively, use 'usethis tool' to add other tools and their hooks.")
+    instruct_print("Remove the placeholder hook in '.pre-commit-config.yaml'.")
+    instruct_print("Replace it with your own hooks.")
+    instruct_print(
+        "Alternatively, use 'usethis tool' to add other tools and their hooks."
+    )
 
 
 def _get_placeholder_repo_config() -> LocalRepo:

diff --git a/src/usethis/_integrations/pytest/core.py b/src/usethis/_integrations/pytest/core.py
@@ -3,7 +3,7 @@
 import shutil
 
 from usethis._config import usethis_config
-from usethis._console import box_print, tick_print
+from usethis._console import instruct_print, tick_print
 
 
 def add_pytest_dir() -> None:
@@ -35,5 +35,5 @@ def remove_pytest_dir() -> None:
         tick_print("Removing '/tests'.")
         shutil.rmtree(tests_dir)
     else:
-        box_print("Reconfigure the '/tests' directory to run without pytest.")
+        instruct_print("Reconfigure the '/tests' directory to run without pytest.")
         # Note we don't actually remove the directory, just explain what needs to be done.
diff --git a/src/usethis/_tool/base.py b/src/usethis/_tool/base.py
@@ -399,7 +399,8 @@ def add_configs(self) -> None:
         already_added = False  # Only print messages for the first added config item.
         for config_item in self.get_config_spec().config_items:
             with usethis_config.set(
-                alert_only=already_added or usethis_config.alert_only
+                alert_only=already_added or usethis_config.alert_only,
+                instruct_only=already_added or usethis_config.instruct_only,
             ):
                 added = self._add_config_item(
                     config_item, file_managers=active_config_file_managers

diff --git a/src/usethis/_tool/impl/codespell.py b/src/usethis/_tool/impl/codespell.py
@@ -7,7 +7,7 @@
 
 from usethis._config import usethis_config
 from usethis._config_file import CodespellRCManager
-from usethis._console import box_print
+from usethis._console import how_print
 from usethis._integrations.backend.dispatch import get_backend
 from usethis._integrations.backend.uv.used import is_uv_used
 from usethis._integrations.ci.bitbucket.anchor import (
@@ -41,20 +41,20 @@ def print_how_to_use(self) -> None:
         install_method = self.get_install_method()
         if install_method == "pre-commit":
             if backend is BackendEnum.uv and is_uv_used():
-                box_print(
+                how_print(
                     "Run 'uv run pre-commit run codespell --all-files' to run the Codespell spellchecker."
                 )
             else:
                 assert backend in (BackendEnum.none, BackendEnum.uv)
-                box_print(
+                how_print(
                     "Run 'pre-commit run codespell --all-files' to run the Codespell spellchecker."
                 )
         elif install_method == "devdep" or install_method is None:
             if backend is BackendEnum.uv and is_uv_used():
-                box_print("Run 'uv run codespell' to run the Codespell spellchecker.")
+                how_print("Run 'uv run codespell' to run the Codespell spellchecker.")
             else:
                 assert backend in (BackendEnum.none, BackendEnum.uv)
-                box_print("Run 'codespell' to run the Codespell spellchecker.")
+                how_print("Run 'codespell' to run the Codespell spellchecker.")
         else:
             assert_never(install_method)