usethis-python · nathanjmcdougall · Mar 20, 2026 · Mar 20, 2026 · Mar 20, 2026 · Mar 20, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -140,8 +140,9 @@ Tool implementations are defined in classes in the `usethis._tool.impl` module.
 - Declare this new submodule in the `.importlinter` configuration to architecturally describe its dependency relationships with other tools' submodules. For example, does your tool integrate with pre-commit? It should be in a higher layer module than the `pre-commit` submodule.
 - Define a `usethis._tool.base.ToolSpec` subclass, e.g. for a tool named Xyz, define a class `XyzToolSpec(ToolSpec)`.
 - Start by implementing its `name` property method, then work through the other methods. Most method have default implementations, but even in those cases you will need to consider them individually and determine an appropriate implementation. For example, methods which specify the tool's dependencies default to empty dependencies, but you shouldn't rely on this.
+- Mark all methods in your `ToolSpec` subclass with the `@typing.final` decorator. This prevents the methods from being accidentally overridden in the `Tool` subclass.
 - Then, define a subclass of the `ToolSpec` subclass you just created, which also subclasses `usethis._tool.base.Tool`, e.g. for a tool named Xyz, define a class `XyzTool(XyzToolSpec, Tool)`. The only method this usually requires a non-default implementation for is `config_spec` to specify which configuration sections should be set up for the tool (and which sections the tool manages). However, you may find it helpful to provide custom implementations for other methods as well, e.g. `print_how_to_use`.
-- Include a comment with a URL linking to the tool's source repo for reference.
+- Mark all methods in your `Tool` subclass with `@final` as well, to prevent further subclassing from overriding them.
 
 #### Register your `Tool` subclass
 

diff --git a/src/usethis/_tool/impl/base/codespell.py b/src/usethis/_tool/impl/base/codespell.py
@@ -1,10 +1,13 @@
 from __future__ import annotations
 
+from typing import final
+
 from usethis._console import how_print
 from usethis._tool.base import Tool
 from usethis._tool.impl.spec.codespell import CodespellToolSpec
 
 
 class CodespellTool(CodespellToolSpec, Tool):
+    @final
     def print_how_to_use(self) -> None:
         how_print(f"Run '{self.how_to_use_cmd()}' to run the {self.name} spellchecker.")
diff --git a/src/usethis/_tool/impl/base/coverage_py.py b/src/usethis/_tool/impl/base/coverage_py.py
@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from typing import final
+
 from typing_extensions import assert_never
 
 from usethis._backend.dispatch import get_backend
@@ -12,6 +14,7 @@
 
 
 class CoveragePyTool(CoveragePyToolSpec, Tool):
+    @final
     def test_deps(self, *, unconditional: bool = False) -> list[Dependency]:
         from usethis._tool.impl.base.pytest import (  # to avoid circularity;  # noqa: PLC0415
             PytestTool,
@@ -22,6 +25,7 @@ def test_deps(self, *, unconditional: bool = False) -> list[Dependency]:
             deps += [Dependency(name="pytest-cov")]
         return deps
 
+    @final
     def print_how_to_use(self) -> None:
         from usethis._tool.impl.base.pytest import (  # to avoid circularity;  # noqa: PLC0415
             PytestTool,

diff --git a/src/usethis/_tool/impl/base/deptry.py b/src/usethis/_tool/impl/base/deptry.py
@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, final
 
 from usethis._console import info_print
 from usethis._file.pyproject_toml.io_ import PyprojectTOMLManager
@@ -13,12 +13,14 @@
 
 
 class DeptryTool(DeptryToolSpec, Tool):
+    @final
     def select_rules(self, rules: list[Rule]) -> bool:
         """Does nothing for deptry - all rules are automatically enabled by default."""
         if rules:
             info_print(f"All {self.name} rules are always implicitly selected.")
         return False
 
+    @final
     def selected_rules(self) -> list[Rule]:
         """No notion of selection for deptry.
 
@@ -27,10 +29,12 @@ def selected_rules(self) -> list[Rule]:
         """
         return []
 
+    @final
     def deselect_rules(self, rules: list[Rule]) -> bool:
         """Does nothing for deptry - all rules are automatically enabled by default."""
         return False
 
+    @final
     def ignored_rules(self) -> list[Rule]:
         (file_manager,) = self.get_active_config_file_managers()
         keys = self._get_ignore_keys(file_manager)
@@ -41,6 +45,7 @@ def ignored_rules(self) -> list[Rule]:
 
         return rules
 
+    @final
     def _get_ignore_keys(self, file_manager: KeyValueFileManager[object]) -> list[str]:
         """Get the keys for the ignored rules in the given file manager."""
         if isinstance(file_manager, PyprojectTOMLManager):

diff --git a/src/usethis/_tool/impl/base/import_linter.py b/src/usethis/_tool/impl/base/import_linter.py
@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, final
 
 from usethis._config import usethis_config
 from usethis._console import info_print
@@ -13,13 +13,15 @@
 
 
 class ImportLinterTool(ImportLinterToolSpec, Tool):
+    @final
     def is_used(self) -> bool:
         """Check if the Import Linter tool is used in the project."""
         # We suppress the warning about assumptions regarding the package name.
         # See _importlinter_warn_no_packages_found
         with usethis_config.set(quiet=True):
             return super().is_used()
 
+    @final
     def print_how_to_use(self) -> None:
         if not _is_inp_rule_selected():
             # If Ruff is used, we enable the INP rules instead.

diff --git a/src/usethis/_tool/impl/base/mkdocs.py b/src/usethis/_tool/impl/base/mkdocs.py
@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from typing import final
+
 from typing_extensions import assert_never
 
 from usethis._backend.dispatch import get_backend
@@ -11,6 +13,7 @@
 
 
 class MkDocsTool(MkDocsToolSpec, Tool):
+    @final
     def print_how_to_use(self) -> None:
         backend = get_backend()
         if backend is BackendEnum.uv and is_uv_used():

diff --git a/src/usethis/_tool/impl/base/pre_commit.py b/src/usethis/_tool/impl/base/pre_commit.py
@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, final
 
 from typing_extensions import assert_never
 
@@ -20,12 +20,15 @@
 
 
 class PreCommitTool(PreCommitToolSpec, Tool):
+    @final
     def is_used(self) -> bool:
         return is_pre_commit_used()
 
+    @final
     def print_how_to_use(self) -> None:
         how_print(f"Run '{self.how_to_use_cmd()}' to run the hooks manually.")
 
+    @final
     def get_bitbucket_steps(
         self,
         *,
@@ -63,6 +66,7 @@ def get_bitbucket_steps(
         else:
             assert_never(backend)
 
+    @final
     def update_bitbucket_steps(self, *, matrix_python: bool = True) -> None:
         """Add Bitbucket steps associated with pre-commit, and remove outdated ones.
 
@@ -74,8 +78,10 @@ def update_bitbucket_steps(self, *, matrix_python: bool = True) -> None:
         """
         self._unconditional_update_bitbucket_steps(matrix_python=matrix_python)
 
+    @final
     def migrate_config_to_pre_commit(self) -> None:
         pass
 
+    @final
     def migrate_config_from_pre_commit(self) -> None:
         pass
diff --git a/src/usethis/_tool/impl/base/pyproject_toml.py b/src/usethis/_tool/impl/base/pyproject_toml.py
@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from typing import final
+
 from usethis._console import how_print, info_print, instruct_print
 from usethis._file.pyproject_toml.io_ import PyprojectTOMLManager
 from usethis._tool.base import Tool
@@ -30,12 +32,14 @@
 
 
 class PyprojectTOMLTool(PyprojectTOMLToolSpec, Tool):
+    @final
     def print_how_to_use(self) -> None:
         how_print("Populate 'pyproject.toml' with the project configuration.")
         info_print(
             "Learn more at https://packaging.python.org/en/latest/guides/writing-pyproject-toml/"
         )
 
+    @final
     def remove_managed_files(self) -> None:
         # https://github.com/usethis-python/usethis-python/issues/416
         # We need to step through the tools and see if pyproject.toml is the active

diff --git a/src/usethis/_tool/impl/base/pytest.py b/src/usethis/_tool/impl/base/pytest.py
@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import re
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, final
 
 from typing_extensions import assert_never
 
@@ -29,6 +29,7 @@
 
 
 class PytestTool(PytestToolSpec, Tool):
+    @final
     def test_deps(self, *, unconditional: bool = False) -> list[Dependency]:
         from usethis._tool.impl.base.coverage_py import (  # to avoid circularity;  # noqa: PLC0415
             CoveragePyTool,
@@ -39,13 +40,15 @@ def test_deps(self, *, unconditional: bool = False) -> list[Dependency]:
             deps += [Dependency(name="pytest-cov")]
         return deps
 
+    @final
     def print_how_to_use(self) -> None:
         how_print(
             "Add test files to the '/tests' directory with the format 'test_*.py'."
         )
         how_print("Add test functions with the format 'test_*()'.")
         how_print(f"Run '{self.how_to_use_cmd()}' to run the tests.")
 
+    @final
     def get_active_config_file_managers(self) -> set[KeyValueFileManager[object]]:
         # This is a variant of the "first" method
         config_spec = self.config_spec()
@@ -105,6 +108,7 @@ def get_active_config_file_managers(self) -> set[KeyValueFileManager[object]]:
             raise NotImplementedError(msg)
         return {preferred_file_manager}
 
+    @final
     def get_bitbucket_steps(
         self, *, matrix_python: bool = True
     ) -> list[bitbucket_schema.Step]:
@@ -150,6 +154,7 @@ def get_bitbucket_steps(
             steps.append(step)
         return steps
 
+    @final
     def get_managed_bitbucket_step_names(self) -> list[str]:
         names = set()
         for step in get_steps_in_default():
@@ -164,6 +169,7 @@ def get_managed_bitbucket_step_names(self) -> list[str]:
 
         return sorted(names)
 
+    @final
     def update_bitbucket_steps(self, *, matrix_python: bool = True) -> None:
         """Update the pytest-related Bitbucket Pipelines steps.
 

diff --git a/src/usethis/_tool/impl/base/requirements_txt.py b/src/usethis/_tool/impl/base/requirements_txt.py
@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from typing import final
+
 from typing_extensions import assert_never
 
 from usethis._backend.dispatch import get_backend
@@ -11,6 +13,7 @@
 
 
 class RequirementsTxtTool(RequirementsTxtToolSpec, Tool):
+    @final
     def print_how_to_use(self) -> None:
         install_method = self.get_install_method()
         backend = get_backend()