usethis-python · nathanjmcdougall · Sep 14, 2025 · Aug 17, 2025 · Sep 14, 2025 · Sep 14, 2025
diff --git a/src/usethis/_tool/base.py b/src/usethis/_tool/base.py
@@ -30,9 +30,7 @@
 if TYPE_CHECKING:
     from pathlib import Path
 
-    from usethis._integrations.backend.uv.deps import (
-        Dependency,
-    )
+    from usethis._integrations.backend.uv.deps import Dependency
     from usethis._integrations.ci.bitbucket.schema import Step as BitbucketStep
     from usethis._integrations.pre_commit.schema import LocalRepo, UriRepo
     from usethis._io import KeyValueFileManager
@@ -409,7 +407,11 @@ def add_configs(self) -> None:
     def _add_config_item(
         self, config_item: ConfigItem, *, file_managers: set[KeyValueFileManager]
     ) -> bool:
-        """Add a specific configuration item using specified file managers."""
+        """Add a specific configuration item using specified file managers.
+
+        Returns whether any config was added. Config might not be added in some cases
+        where it's conditional and not applicable based on the current project state.
+        """
         # This is mostly a helper method for `add_configs`.
 
         # Filter to just those active config file managers which can manage this
@@ -425,15 +427,10 @@ def _add_config_item(
                 msg = f"No active config file managers found for one of the '{self.name}' config items."
                 raise NotImplementedError(msg)
             else:
-                # Early exist; this config item is not managed by any active files
+                # Early exit; this config item is not managed by any active files
                 # so it's optional, effectively.
                 return False
 
-        for file_manager in used_file_managers:
-            if not (file_manager.path.exists() and file_manager.path.is_file()):
-                tick_print(f"Writing '{file_manager.relative_path}'.")
-                file_manager.path.touch(exist_ok=True)
-
         config_entries = [
             config_item
             for relative_path, config_item in config_item.root.items()
@@ -456,6 +453,13 @@ def _add_config_item(
             # No value to add, so skip this config item.
             return False
 
+        # N.B. we wait to create files until after all `return False` lines to avoid
+        # creating empty files unnecessarily.
+        for file_manager in used_file_managers:
+            if not (file_manager.path.exists() and file_manager.path.is_file()):
+                tick_print(f"Writing '{file_manager.relative_path}'.")
+                file_manager.path.touch(exist_ok=True)
+
         shared_keys = []
         for key in entry.keys:
             shared_keys.append(key)

diff --git a/src/usethis/_tool/impl/codespell.py b/src/usethis/_tool/impl/codespell.py
@@ -1,9 +1,11 @@
 from __future__ import annotations
 
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 from typing_extensions import assert_never
 
+from usethis._config import usethis_config
 from usethis._config_file import CodespellRCManager
 from usethis._console import box_print
 from usethis._integrations.backend.dispatch import get_backend
@@ -22,6 +24,9 @@
 from usethis._types.backend import BackendEnum
 from usethis._types.deps import Dependency
 
+if TYPE_CHECKING:
+    from usethis._io import KeyValueFileManager
+
 
 class CodespellTool(Tool):
     # https://github.com/codespell-project/codespell
@@ -54,6 +59,11 @@ def print_how_to_use(self) -> None:
     def get_dev_deps(self, *, unconditional: bool = False) -> list[Dependency]:
         return [Dependency(name="codespell")]
 
+    def preferred_file_manager(self) -> KeyValueFileManager:
+        if (usethis_config.cpd() / "pyproject.toml").exists():
+            return PyprojectTOMLManager()
+        return CodespellRCManager()
+
     def get_config_spec(self) -> ConfigSpec:
         # https://github.com/codespell-project/codespell?tab=readme-ov-file#using-a-config-file
 

diff --git a/src/usethis/_tool/impl/coverage_py.py b/src/usethis/_tool/impl/coverage_py.py
@@ -1,7 +1,9 @@
 from __future__ import annotations
 
 from pathlib import Path
+from typing import TYPE_CHECKING
 
+from usethis._config import usethis_config
 from usethis._config_file import (
     CoverageRCManager,
     ToxINIManager,
@@ -17,6 +19,9 @@
 from usethis._types.backend import BackendEnum
 from usethis._types.deps import Dependency
 
+if TYPE_CHECKING:
+    from usethis._io import KeyValueFileManager
+
 
 class CoveragePyTool(Tool):
     # https://github.com/nedbat/coveragepy
@@ -54,6 +59,11 @@ def get_test_deps(self, *, unconditional: bool = False) -> list[Dependency]:
             deps += [Dependency(name="pytest-cov")]
         return deps
 
+    def preferred_file_manager(self) -> KeyValueFileManager:
+        if (usethis_config.cpd() / "pyproject.toml").exists():
+            return PyprojectTOMLManager()
+        return CoverageRCManager()
+
     def get_config_spec(self) -> ConfigSpec:
         # https://coverage.readthedocs.io/en/latest/config.html#configuration-reference
 

diff --git a/src/usethis/_tool/impl/import_linter.py b/src/usethis/_tool/impl/import_linter.py
@@ -92,6 +92,11 @@ def get_dev_deps(self, *, unconditional: bool = False) -> list[Dependency]:
         # This is because it needs to run from within the virtual environment.
         return [Dependency(name="import-linter")]
 
+    def preferred_file_manager(self) -> KeyValueFileManager:
+        if (usethis_config.cpd() / "pyproject.toml").exists():
+            return PyprojectTOMLManager()
+        return DotImportLinterManager()
+
     def get_config_spec(self) -> ConfigSpec:
         # https://import-linter.readthedocs.io/en/stable/usage.html
 

diff --git a/src/usethis/_tool/impl/pytest.py b/src/usethis/_tool/impl/pytest.py
@@ -67,6 +67,11 @@ def get_test_deps(self, *, unconditional: bool = False) -> list[Dependency]:
             deps += [Dependency(name="pytest-cov")]
         return deps
 
+    def preferred_file_manager(self) -> KeyValueFileManager:
+        if (usethis_config.cpd() / "pyproject.toml").exists():
+            return PyprojectTOMLManager()
+        return PytestINIManager()
+
     def get_config_spec(self) -> ConfigSpec:
         # https://docs.pytest.org/en/stable/reference/customize.html#configuration-file-formats
         # "Options from multiple configfiles candidates are never merged - the first match wins."

diff --git a/src/usethis/_tool/impl/ruff.py b/src/usethis/_tool/impl/ruff.py
@@ -130,6 +130,11 @@ def print_how_to_use_formatter(self) -> None:
     def get_dev_deps(self, *, unconditional: bool = False) -> list[Dependency]:
         return [Dependency(name="ruff")]
 
+    def preferred_file_manager(self) -> KeyValueFileManager:
+        if (usethis_config.cpd() / "pyproject.toml").exists():
+            return PyprojectTOMLManager()
+        return RuffTOMLManager()
+
     def get_config_spec(self) -> ConfigSpec:
         # https://docs.astral.sh/ruff/configuration/#config-file-discovery
 

diff --git a/src/usethis/_toolset/format_.py b/src/usethis/_toolset/format_.py
@@ -1,6 +1,8 @@
 from usethis._core.tool import use_pyproject_fmt, use_ruff
+from usethis._tool.impl.pyproject_toml import PyprojectTOMLTool
 
 
 def use_formatters(remove: bool = False, how: bool = False):
     use_ruff(linter=False, formatter=True, remove=remove, how=how)
-    use_pyproject_fmt(remove=remove, how=how)
+    if PyprojectTOMLTool().is_used() and (not remove or how):
+        use_pyproject_fmt(remove=remove, how=how)
diff --git a/tests/usethis/_core/test_core_tool.py b/tests/usethis/_core/test_core_tool.py
@@ -236,12 +236,17 @@ def test_setup_cfg_empty(self, uv_init_dir: Path):
             assert (uv_init_dir / "setup.cfg").read_text() == ""
             assert "[tool.codespell]" in (uv_init_dir / "pyproject.toml").read_text()
 
-        def test_none_backend(self, tmp_path: Path, capfd: pytest.CaptureFixture[str]):
+        def test_none_backend_pyproject_toml(
+            self, tmp_path: Path, capfd: pytest.CaptureFixture[str]
+        ):
+            # Arrange
+            (tmp_path / "pyproject.toml").touch()
+
             # Act
             with (
                 change_cwd(tmp_path),
                 usethis_config.set(backend=BackendEnum.none),
-                PyprojectTOMLManager(),
+                files_manager(),
             ):
                 use_codespell()
 
@@ -250,11 +255,31 @@ def test_none_backend(self, tmp_path: Path, capfd: pytest.CaptureFixture[str]):
             assert not err
             assert out == (
                 "☐ Add the dev dependency 'codespell'.\n"
-                "✔ Writing 'pyproject.toml'.\n"
                 "✔ Adding Codespell config to 'pyproject.toml'.\n"
                 "☐ Run 'codespell' to run the Codespell spellchecker.\n"
             )
 
+        def test_none_backend_no_pyproject_toml(
+            self, tmp_path: Path, capfd: pytest.CaptureFixture[str]
+        ):
+            # Act
+            with (
+                change_cwd(tmp_path),
+                usethis_config.set(backend=BackendEnum.none),
+                files_manager(),
+            ):
+                use_codespell()
+
+            # Assert
+            out, err = capfd.readouterr()
+            assert not err
+            assert out == (
+                "☐ Add the dev dependency 'codespell'.\n"
+                "✔ Writing '.codespellrc'.\n"
+                "✔ Adding Codespell config to '.codespellrc'.\n"
+                "☐ Run 'codespell' to run the Codespell spellchecker.\n"
+            )
+
     class TestRemove:
         @pytest.mark.usefixtures("_vary_network_conn")
         def test_config_file(
@@ -2318,7 +2343,9 @@ def test_doesnt_invoke_ensure_dep_declaration_file(self, tmp_path: Path):
 class TestPytest:
     class TestAdd:
         @pytest.mark.usefixtures("_vary_network_conn")
-        def test_no_pyproject(self, tmp_path: Path, capfd: pytest.CaptureFixture[str]):
+        def test_no_pyproject_toml(
+            self, tmp_path: Path, capfd: pytest.CaptureFixture[str]
+        ):
             with change_cwd(tmp_path), files_manager():
                 # Act
                 use_pytest()

diff --git a/tests/usethis/_integrations/backend/uv/test_python.py b/tests/usethis/_integrations/backend/uv/test_python.py
@@ -55,7 +55,7 @@ def test_upper_bound(self, tmp_path: Path):
         # Assert
         assert supported_major_python == [9, 10, 11]
 
-    def test_no_pyproject(self, tmp_path: Path):
+    def test_no_pyproject_toml(self, tmp_path: Path):
         with change_cwd(tmp_path), PyprojectTOMLManager():
             assert get_supported_uv_major_python_versions() == [
                 extract_major_version(get_python_version())

diff --git a/tests/usethis/_integrations/file/pyproject_toml/test_requires_python.py b/tests/usethis/_integrations/file/pyproject_toml/test_requires_python.py
@@ -28,7 +28,7 @@ def test_lower_bound(self, tmp_path: Path):
         # Assert
         assert requires_python == SpecifierSet(">=3.7")
 
-    def test_no_pyproject(self, tmp_path: Path):
+    def test_no_pyproject_toml(self, tmp_path: Path):
         with (
             change_cwd(tmp_path),
             PyprojectTOMLManager(),

diff --git a/tests/usethis/_tool/impl/test_codespell.py b/tests/usethis/_tool/impl/test_codespell.py
@@ -118,3 +118,29 @@ def test_latest_version(self):
                     "Failed to fetch GitHub tags (connection issues); skipping test"
                 )
             raise err
+
+    class TestAddConfig:
+        def test_empty_dir(self, tmp_path: Path):
+            # Expect ruff.toml to be preferred
+
+            # Act
+            with change_cwd(tmp_path), files_manager():
+                CodespellTool().add_configs()
+
+            # Assert
+            assert (tmp_path / ".codespellrc").exists()
+            assert not (tmp_path / "setup.cfg").exists()
+            assert not (tmp_path / "pyproject.toml").exists()
+
+        def test_pyproject_toml_exists(self, tmp_path: Path):
+            # Arrange
+            (tmp_path / "pyproject.toml").touch()
+
+            # Act
+            with change_cwd(tmp_path), files_manager():
+                CodespellTool().add_configs()
+
+            # Assert
+            assert not (tmp_path / ".codespellrc").exists()
+            assert not (tmp_path / "setup.cfg").exists()
+            assert (tmp_path / "pyproject.toml").exists()
diff --git a/tests/usethis/_tool/impl/test_coverage_py.py b/tests/usethis/_tool/impl/test_coverage_py.py
@@ -36,3 +36,27 @@ def test_after_codespell(self, tmp_path: Path):
             with change_cwd(tmp_path), files_manager():
                 assert ["tool", "coverage"] in PyprojectTOMLManager()
             assert "[tool.coverage]" in (tmp_path / "pyproject.toml").read_text()
+
+    class TestAddConfig:
+        def test_empty_dir(self, tmp_path: Path):
+            # Expect .coveragerc to be preferred
+
+            # Act
+            with change_cwd(tmp_path), files_manager():
+                CoveragePyTool().add_configs()
+
+            # Assert
+            assert (tmp_path / ".coveragerc").exists()
+            assert not (tmp_path / "pyproject.toml").exists()
+
+        def test_pyproject_toml_exists(self, tmp_path: Path):
+            # Arrange
+            (tmp_path / "pyproject.toml").touch()
+
+            # Act
+            with change_cwd(tmp_path), files_manager():
+                CoveragePyTool().add_configs()
+
+            # Assert
+            assert not (tmp_path / ".coveragerc").exists()
+            assert (tmp_path / "pyproject.toml").exists()
diff --git a/tests/usethis/_tool/impl/test_deptry.py b/tests/usethis/_tool/impl/test_deptry.py
@@ -2,6 +2,7 @@
 
 import pytest
 
+from usethis._config_file import files_manager
 from usethis._integrations.file.pyproject_toml.io_ import PyprojectTOMLManager
 from usethis._test import change_cwd
 from usethis._tool.config import ConfigEntry, ConfigItem
@@ -247,3 +248,23 @@ def test_with_rule(self, tmp_path: Path):
 
                 # Assert
                 assert result == ["DEP003"]
+
+    class TestAddConfig:
+        def test_empty_dir(self, tmp_path: Path):
+            # Act
+            with change_cwd(tmp_path), files_manager():
+                DeptryTool().add_configs()
+
+            # Assert
+            assert not (tmp_path / "pyproject.toml").exists()
+
+        def test_pyproject_toml_exists(self, tmp_path: Path):
+            # Arrange
+            (tmp_path / "pyproject.toml").touch()
+
+            # Act
+            with change_cwd(tmp_path), files_manager():
+                DeptryTool().add_configs()
+
+            # Assert
+            assert (tmp_path / "pyproject.toml").exists()
diff --git a/tests/usethis/_tool/impl/test_import_linter.py b/tests/usethis/_tool/impl/test_import_linter.py
@@ -132,6 +132,30 @@ def test_ruff_is_used_without_inp_rules(
                 "☐ Run 'lint-imports' to run Import Linter.\n"
             )
 
+    class TestAddConfig:
+        def test_empty_dir(self, tmp_path: Path):
+            # Expect .importlinter to be preferred
+
+            # Act
+            with change_cwd(tmp_path), files_manager():
+                ImportLinterTool().add_configs()
+
+            # Assert
+            assert (tmp_path / ".importlinter").exists()
+            assert not (tmp_path / "pyproject.toml").exists()
+
+        def test_pyproject_toml_exists(self, tmp_path: Path):
+            # Arrange
+            (tmp_path / "pyproject.toml").touch()
+
+            # Act
+            with change_cwd(tmp_path), files_manager():
+                ImportLinterTool().add_configs()
+
+            # Assert
+            assert not (tmp_path / ".importlinter").exists()
+            assert (tmp_path / "pyproject.toml").exists()
+
 
 class TestIsINPRule:
     def test_inp_rule(self):

diff --git a/tests/usethis/_tool/impl/test_pytest.py b/tests/usethis/_tool/impl/test_pytest.py
@@ -233,3 +233,27 @@ def test_one_step(self, uv_init_dir: Path):
               - echo 'Hello, world!'
 """
             )
+
+    class TestAddConfig:
+        def test_empty_dir(self, tmp_path: Path):
+            # Expect pytest.ini to be preferred
+
+            # Act
+            with change_cwd(tmp_path), files_manager():
+                PytestTool().add_configs()
+
+            # Assert
+            assert (tmp_path / "pytest.ini").exists()
+            assert not (tmp_path / "pyproject.toml").exists()
+
+        def test_pyproject_toml_exists(self, tmp_path: Path):
+            # Arrange
+            (tmp_path / "pyproject.toml").touch()
+
+            # Act
+            with change_cwd(tmp_path), files_manager():
+                PytestTool().add_configs()
+
+            # Assert
+            assert not (tmp_path / "pytest.ini").exists()
+            assert (tmp_path / "pyproject.toml").exists()