437 add a how flag for tools (#593)

* Add --how option

* Document --how option

* Add more testing for --how

* Add further tests for --how

Author: nathanjmcdougall

README.md

@@ -152,6 +152,7 @@ Add a new tool to a Python project, including:
 Supported options:
 
 - `--remove` to remove the tool instead of adding it
+- `--how` to only print how to use the tool, with no other side effects
 - `--offline` to disable network access and rely on caches
 - `--frozen` to leave the virtual environment and lockfile unchanged
 - `--quiet` to suppress output

src/usethis/_core/tool.py

@@ -36,9 +36,13 @@
     from usethis._tool.base import Tool
 
 
-def use_codespell(*, remove: bool = False) -> None:
+def use_codespell(*, remove: bool = False, how: bool = False) -> None:
     tool = CodespellTool()
 
+    if how:
+        tool.print_how_to_use()
+        return
+
     ensure_pyproject_toml()
 
     if not remove:
@@ -58,9 +62,13 @@ def use_codespell(*, remove: bool = False) -> None:
         tool.remove_managed_files()
 
 
-def use_coverage(*, remove: bool = False) -> None:
+def use_coverage(*, remove: bool = False, how: bool = False) -> None:
     tool = CoverageTool()
 
+    if how:
+        tool.print_how_to_use()
+        return
+
     ensure_pyproject_toml()
 
     if not remove:
@@ -73,9 +81,13 @@ def use_coverage(*, remove: bool = False) -> None:
         tool.remove_managed_files()
 
 
-def use_deptry(*, remove: bool = False) -> None:
+def use_deptry(*, remove: bool = False, how: bool = False) -> None:
     tool = DeptryTool()
 
+    if how:
+        tool.print_how_to_use()
+        return
+
     ensure_pyproject_toml()
 
     if not remove:
@@ -94,9 +106,13 @@ def use_deptry(*, remove: bool = False) -> None:
         tool.remove_managed_files()
 
 
-def use_import_linter(*, remove: bool = False) -> None:
+def use_import_linter(*, remove: bool = False, how: bool = False) -> None:
     tool = ImportLinterTool()
 
+    if how:
+        tool.print_how_to_use()
+        return
+
     ensure_pyproject_toml()
 
     if not remove:
@@ -116,8 +132,13 @@ def use_import_linter(*, remove: bool = False) -> None:
         tool.remove_managed_files()
 
 
-def use_pre_commit(*, remove: bool = False) -> None:
+def use_pre_commit(*, remove: bool = False, how: bool = False) -> None:
     tool = PreCommitTool()
+
+    if how:
+        tool.print_how_to_use()
+        return
+
     pyproject_fmt_tool = PyprojectFmtTool()
     codespell_tool = CodespellTool()
     requirements_txt_tool = RequirementsTxtTool()
@@ -201,9 +222,13 @@ def _remove_bitbucket_linter_steps_from_default() -> None:
     RuffTool().remove_bitbucket_steps()
 
 
-def use_pyproject_fmt(*, remove: bool = False) -> None:
+def use_pyproject_fmt(*, remove: bool = False, how: bool = False) -> None:
     tool = PyprojectFmtTool()
 
+    if how:
+        tool.print_how_to_use()
+        return
+
     ensure_pyproject_toml()
 
     if not remove:
@@ -223,9 +248,13 @@ def use_pyproject_fmt(*, remove: bool = False) -> None:
         tool.remove_managed_files()
 
 
-def use_pyproject_toml(*, remove: bool = False) -> None:
+def use_pyproject_toml(*, remove: bool = False, how: bool = False) -> None:
     tool = PyprojectTOMLTool()
 
+    if how:
+        tool.print_how_to_use()
+        return
+
     ensure_pyproject_toml()
 
     if not remove:
@@ -236,9 +265,13 @@ def use_pyproject_toml(*, remove: bool = False) -> None:
         tool.remove_managed_files()
 
 
-def use_pytest(*, remove: bool = False) -> None:
+def use_pytest(*, remove: bool = False, how: bool = False) -> None:
     tool = PytestTool()
 
+    if how:
+        tool.print_how_to_use()
+        return
+
     ensure_pyproject_toml()
 
     rule_config = tool.get_rule_config()
@@ -273,9 +306,13 @@ def use_pytest(*, remove: bool = False) -> None:
         tool.remove_managed_files()
 
 
-def use_requirements_txt(*, remove: bool = False) -> None:
+def use_requirements_txt(*, remove: bool = False, how: bool = False) -> None:
     tool = RequirementsTxtTool()
 
+    if how:
+        tool.print_how_to_use()
+        return
+
     ensure_pyproject_toml()
 
     path = Path.cwd() / "requirements.txt"
@@ -311,7 +348,7 @@ def use_requirements_txt(*, remove: bool = False) -> None:
         tool.remove_managed_files()
 
 
-def use_ruff(*, remove: bool = False, minimal: bool = False) -> None:
+def use_ruff(*, remove: bool = False, how: bool = False, minimal: bool = False) -> None:
     """Add Ruff to the project.
 
     By default, sensible default rules are selected. If rules are already selected, the
@@ -322,6 +359,10 @@ def use_ruff(*, remove: bool = False, minimal: bool = False) -> None:
 
     tool = RuffTool()
 
+    if how:
+        tool.print_how_to_use()
+        return
+
     ensure_pyproject_toml()
 
     # Only add ruff rules if the user doesn't already have a select/ignore list.

src/usethis/_interface/tool.py

@@ -23,10 +23,12 @@
     help="Add and configure development tools, e.g. linters.", add_completion=False
 )
 
+how_opt = typer.Option(
+    False, "--how", help="Only print how to use the tool, do not add or remove it."
+)
 remove_opt = typer.Option(
     False, "--remove", help="Remove the tool instead of adding it."
 )
-
 frozen_opt = typer.Option(False, "--frozen", help="Use the frozen dependencies.")
 
 
@@ -37,6 +39,7 @@
 )
 def codespell(
     remove: bool = remove_opt,
+    how: bool = how_opt,
     offline: bool = offline_opt,
     quiet: bool = quiet_opt,
     frozen: bool = frozen_opt,
@@ -45,7 +48,7 @@ def codespell(
         usethis_config.set(offline=offline, quiet=quiet, frozen=frozen),
         files_manager(),
     ):
-        _run_tool(use_codespell, remove=remove)
+        _run_tool(use_codespell, remove=remove, how=how)
 
 
 @app.command(
@@ -55,6 +58,7 @@ def codespell(
 )
 def coverage(
     remove: bool = remove_opt,
+    how: bool = how_opt,
     offline: bool = offline_opt,
     quiet: bool = quiet_opt,
     frozen: bool = frozen_opt,
@@ -63,7 +67,7 @@ def coverage(
         usethis_config.set(offline=offline, quiet=quiet, frozen=frozen),
         files_manager(),
     ):
-        _run_tool(use_coverage, remove=remove)
+        _run_tool(use_coverage, remove=remove, how=how)
 
 
 @app.command(
@@ -73,6 +77,7 @@ def coverage(
 )
 def deptry(
     remove: bool = remove_opt,
+    how: bool = how_opt,
     offline: bool = offline_opt,
     quiet: bool = quiet_opt,
     frozen: bool = frozen_opt,
@@ -81,7 +86,7 @@ def deptry(
         usethis_config.set(offline=offline, quiet=quiet, frozen=frozen),
         files_manager(),
     ):
-        _run_tool(use_deptry, remove=remove)
+        _run_tool(use_deptry, remove=remove, how=how)
 
 
 @app.command(
@@ -91,6 +96,7 @@ def deptry(
 )
 def import_linter(
     remove: bool = remove_opt,
+    how: bool = how_opt,
     offline: bool = offline_opt,
     quiet: bool = quiet_opt,
     frozen: bool = frozen_opt,
@@ -99,7 +105,7 @@ def import_linter(
         usethis_config.set(offline=offline, quiet=quiet, frozen=frozen),
         files_manager(),
     ):
-        _run_tool(use_import_linter, remove=remove)
+        _run_tool(use_import_linter, remove=remove, how=how)
 
 
 @app.command(
@@ -109,6 +115,7 @@ def import_linter(
 )
 def pre_commit(
     remove: bool = remove_opt,
+    how: bool = how_opt,
     offline: bool = offline_opt,
     quiet: bool = quiet_opt,
     frozen: bool = frozen_opt,
@@ -117,7 +124,7 @@ def pre_commit(
         usethis_config.set(offline=offline, quiet=quiet, frozen=frozen),
         files_manager(),
     ):
-        _run_tool(use_pre_commit, remove=remove)
+        _run_tool(use_pre_commit, remove=remove, how=how)
 
 
 @app.command(
@@ -127,6 +134,7 @@ def pre_commit(
 )
 def pyproject_fmt(
     remove: bool = remove_opt,
+    how: bool = how_opt,
     offline: bool = offline_opt,
     quiet: bool = quiet_opt,
     frozen: bool = frozen_opt,
@@ -135,7 +143,7 @@ def pyproject_fmt(
         usethis_config.set(offline=offline, quiet=quiet, frozen=frozen),
         files_manager(),
     ):
-        _run_tool(use_pyproject_fmt, remove=remove)
+        _run_tool(use_pyproject_fmt, remove=remove, how=how)
 
 
 @app.command(
@@ -145,6 +153,7 @@ def pyproject_fmt(
 )
 def pyproject_toml(
     remove: bool = remove_opt,
+    how: bool = how_opt,
     offline: bool = offline_opt,
     quiet: bool = quiet_opt,
     frozen: bool = frozen_opt,
@@ -153,14 +162,15 @@ def pyproject_toml(
         usethis_config.set(offline=offline, quiet=quiet, frozen=frozen),
         files_manager(),
     ):
-        _run_tool(use_pyproject_toml, remove=remove)
+        _run_tool(use_pyproject_toml, remove=remove, how=how)
 
 
 @app.command(
     name="pytest", help="Use the pytest testing framework.", rich_help_panel="Testing"
 )
 def pytest(
     remove: bool = remove_opt,
+    how: bool = how_opt,
     offline: bool = offline_opt,
     quiet: bool = quiet_opt,
     frozen: bool = frozen_opt,
@@ -169,7 +179,7 @@ def pytest(
         usethis_config.set(offline=offline, quiet=quiet, frozen=frozen),
         files_manager(),
     ):
-        _run_tool(use_pytest, remove=remove)
+        _run_tool(use_pytest, remove=remove, how=how)
 
 
 @app.command(
@@ -179,6 +189,7 @@ def pytest(
 )
 def requirements_txt(
     remove: bool = remove_opt,
+    how: bool = how_opt,
     offline: bool = offline_opt,
     quiet: bool = quiet_opt,
     frozen: bool = frozen_opt,
@@ -187,7 +198,7 @@ def requirements_txt(
         usethis_config.set(offline=offline, quiet=quiet, frozen=frozen),
         files_manager(),
     ):
-        _run_tool(use_requirements_txt, remove=remove)
+        _run_tool(use_requirements_txt, remove=remove, how=how)
 
 
 @app.command(
@@ -197,6 +208,7 @@ def requirements_txt(
 )
 def ruff(
     remove: bool = remove_opt,
+    how: bool = how_opt,
     offline: bool = offline_opt,
     quiet: bool = quiet_opt,
     frozen: bool = frozen_opt,
@@ -205,16 +217,16 @@ def ruff(
         usethis_config.set(offline=offline, quiet=quiet, frozen=frozen),
         files_manager(),
     ):
-        _run_tool(use_ruff, remove=remove)
+        _run_tool(use_ruff, remove=remove, how=how)
 
 
 class UseToolFunc(Protocol):
-    def __call__(self, *, remove: bool) -> None: ...
+    def __call__(self, *, remove: bool, how: bool) -> None: ...
 
 
-def _run_tool(caller: UseToolFunc, *, remove: bool):
+def _run_tool(caller: UseToolFunc, *, remove: bool, how: bool):
     try:
-        caller(remove=remove)
+        caller(remove=remove, how=how)
     except UsethisError as err:
         err_print(err)
         raise typer.Exit(code=1) from None