usethis-python · nathanjmcdougall · Feb 10, 2026 · Jan 8, 2026 · Jan 24, 2026 · Jan 24, 2026
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -252,6 +252,10 @@ Follow the guide in CONTRIBUTING.md:
 - Avoid suppressions unless absolutely necessary
 - Format: `# ruff: noqa: RULE1, RULE2` (not `# ruff noqa:`)
 
+## Reasoning Style
+
+Never use the word "Actually", say "I just realized" or any other meta-language. Instead, clearly state the insight immediately. Similarly, do not use ellipses, e.g. "Unless...". Don't say "Let me check." Be efficient, clear, and direct, not conversational.
+
 ## Trust These Instructions
 
 These instructions have been validated by running actual commands and inspecting the full codebase. Only search for additional information if:

diff --git a/.importlinter b/.importlinter
@@ -14,10 +14,13 @@ layers =
     _core
     _tool
     _init
+    _detect
     _deps
     _config_file
     _integrations
-    _io | _subprocess | _console
+    _backend
+    _file
+    _io | _subprocess | _console | _python
     _config
     _types | errors
     _pipeweld
@@ -65,10 +68,10 @@ containers =
     usethis._tool.impl
 layers =
     pyproject_toml
-    codespell | deptry | import_linter | pyproject_fmt | requirements_txt
+    codespell | deptry | import_linter | mkdocs | pyproject_fmt | requirements_txt
     ruff
     pytest : coverage_py
-    pre_commit | mkdocs
+    pre_commit
 exhaustive = true
 
 [importlinter:contract:integrations]
@@ -79,17 +82,15 @@ containers =
 layers =
     ci | pre_commit
     environ
-    backend | mkdocs | pytest | pydantic | sonarqube
-    project
-    file
-    python
+    mkdocs | pytest | pydantic | sonarqube
+    project | readme
 exhaustive = true
 
-[importlinter:contract:integrations_file]
-name = usethis._integrations.file
+[importlinter:contract:_file]
+name = usethis._file
 type = layers
 containers =
-    usethis._integrations.file
+    usethis._file
 layers =
     pyproject_toml | setup_cfg
     ini | toml | yaml

diff --git a/pyproject.toml b/pyproject.toml
@@ -198,7 +198,7 @@ environment.python-platform = "all"
 rules.type-assertion-failure = "ignore"
 
 [[tool.ty.overrides]]
-include = [ "src/usethis/_integrations/file/**" ]
+include = [ "src/usethis/_file/**" ]
 rules.invalid-argument-type = "ignore"
 rules.invalid-return-type = "ignore"
 rules.invalid-assignment = "ignore"

diff --git a/...usethis/_integrations/backend/__init__.py → src/usethis/_backend/__init__.py b/...usethis/_integrations/backend/__init__.py → src/usethis/_backend/__init__.py
diff --git a/...usethis/_integrations/backend/dispatch.py → src/usethis/_backend/dispatch.py b/...usethis/_integrations/backend/dispatch.py → src/usethis/_backend/dispatch.py
@@ -2,11 +2,11 @@
 
 from typing import Literal
 
+from usethis._backend.poetry.detect import is_poetry_used
+from usethis._backend.uv.available import is_uv_available
+from usethis._backend.uv.detect import is_uv_used
 from usethis._config import usethis_config
 from usethis._console import warn_print
-from usethis._integrations.backend.poetry.used import is_poetry_used
-from usethis._integrations.backend.uv.available import is_uv_available
-from usethis._integrations.backend.uv.used import is_uv_used
 from usethis._types.backend import BackendEnum
 
 

diff --git a/.../_integrations/backend/poetry/__init__.py → src/usethis/_backend/poetry/__init__.py b/.../_integrations/backend/poetry/__init__.py → src/usethis/_backend/poetry/__init__.py
diff --git a/...this/_integrations/backend/poetry/used.py → src/usethis/_backend/poetry/detect.py b/...this/_integrations/backend/poetry/used.py → src/usethis/_backend/poetry/detect.py
@@ -1,5 +1,5 @@
 from usethis._config import usethis_config
-from usethis._integrations.file.pyproject_toml.io_ import PyprojectTOMLManager
+from usethis._file.pyproject_toml.io_ import PyprojectTOMLManager
 
 
 def is_poetry_used() -> bool:

diff --git a/...this/_integrations/backend/uv/__init__.py → src/usethis/_backend/uv/__init__.py b/...this/_integrations/backend/uv/__init__.py → src/usethis/_backend/uv/__init__.py
diff --git a/...his/_integrations/backend/uv/available.py → src/usethis/_backend/uv/available.py b/...his/_integrations/backend/uv/available.py → src/usethis/_backend/uv/available.py
@@ -1,5 +1,5 @@
-from usethis._integrations.backend.uv.call import call_uv_subprocess
-from usethis._integrations.backend.uv.errors import UVSubprocessFailedError
+from usethis._backend.uv.call import call_uv_subprocess
+from usethis._backend.uv.errors import UVSubprocessFailedError
 
 
 def is_uv_available() -> bool:

diff --git a/src/usethis/_integrations/backend/uv/call.py → src/usethis/_backend/uv/call.py b/src/usethis/_integrations/backend/uv/call.py → src/usethis/_backend/uv/call.py
@@ -1,13 +1,13 @@
 from __future__ import annotations
 
+from usethis._backend.uv.errors import UVSubprocessFailedError
+from usethis._backend.uv.link_mode import ensure_symlink_mode
+from usethis._backend.uv.toml import UVTOMLManager
 from usethis._config import usethis_config
-from usethis._integrations.backend.uv.errors import UVSubprocessFailedError
-from usethis._integrations.backend.uv.link_mode import ensure_symlink_mode
-from usethis._integrations.backend.uv.toml import UVTOMLManager
-from usethis._integrations.file.pyproject_toml.io_ import (
+from usethis._file.pyproject_toml.io_ import (
     PyprojectTOMLManager,
 )
-from usethis._integrations.file.pyproject_toml.valid import ensure_pyproject_validity
+from usethis._file.pyproject_toml.valid import ensure_pyproject_validity
 from usethis._subprocess import SubprocessFailedError, call_subprocess
 from usethis._types.backend import BackendEnum
 from usethis.errors import ForbiddenBackendError
@@ -27,8 +27,6 @@ def call_uv_subprocess(args: list[str], change_toml: bool) -> str:
         msg = f"The '{usethis_config.backend.value}' backend is enabled, but a uv subprocess was invoked."
         raise ForbiddenBackendError(msg)
 
-    is_pyproject_toml = (usethis_config.cpd() / "pyproject.toml").exists()
-
     if change_toml and args[0] in {
         "lock",
         "add",
@@ -40,14 +38,8 @@ def call_uv_subprocess(args: list[str], change_toml: bool) -> str:
     }:
         ensure_symlink_mode()
 
-    if is_pyproject_toml and change_toml:
-        if PyprojectTOMLManager().is_locked():
-            ensure_pyproject_validity()
-            PyprojectTOMLManager().write_file()
-            PyprojectTOMLManager()._content = None
-        else:
-            with PyprojectTOMLManager():
-                ensure_pyproject_validity()
+    if change_toml:
+        _prepare_pyproject_write()
 
     if usethis_config.frozen and args[0] in {
         # Note, not "lock", for which the --frozen flags has quite a different effect
@@ -83,6 +75,22 @@ def call_uv_subprocess(args: list[str], change_toml: bool) -> str:
     return output
 
 
+def _prepare_pyproject_write() -> None:
+    is_pyproject_toml = (usethis_config.cpd() / "pyproject.toml").exists()
+    is_locked = PyprojectTOMLManager().is_locked()
+
+    if is_pyproject_toml and is_locked:
+        ensure_pyproject_validity()
+        PyprojectTOMLManager().write_file()
+        PyprojectTOMLManager()._content = None  # Basically a cache clear
+    elif not is_pyproject_toml and is_locked:
+        # Similarly; cache clear
+        PyprojectTOMLManager()._content = None
+    elif is_pyproject_toml:
+        with PyprojectTOMLManager():
+            ensure_pyproject_validity()
+
+
 def add_default_groups_via_uv(groups: list[str]) -> None:
     """Add default groups using the uv command-line tool."""
     if UVTOMLManager().path.exists():

diff --git a/src/usethis/_integrations/backend/uv/deps.py → src/usethis/_backend/uv/deps.py b/src/usethis/_integrations/backend/uv/deps.py → src/usethis/_backend/uv/deps.py
@@ -2,13 +2,13 @@
 
 from typing import TYPE_CHECKING
 
-from usethis._integrations.backend.uv.call import call_uv_subprocess
-from usethis._integrations.backend.uv.errors import (
+from usethis._backend.uv.call import call_uv_subprocess
+from usethis._backend.uv.errors import (
     UVDepGroupError,
     UVSubprocessFailedError,
 )
-from usethis._integrations.backend.uv.toml import UVTOMLManager
-from usethis._integrations.file.pyproject_toml.io_ import PyprojectTOMLManager
+from usethis._backend.uv.toml import UVTOMLManager
+from usethis._file.pyproject_toml.io_ import PyprojectTOMLManager
 
 if TYPE_CHECKING:
     from usethis._types.deps import Dependency

diff --git a/src/usethis/_integrations/backend/uv/used.py → src/usethis/_backend/uv/detect.py b/src/usethis/_integrations/backend/uv/used.py → src/usethis/_backend/uv/detect.py
@@ -1,5 +1,5 @@
 from usethis._config import usethis_config
-from usethis._integrations.file.pyproject_toml.io_ import PyprojectTOMLManager
+from usethis._file.pyproject_toml.io_ import PyprojectTOMLManager
 
 
 def is_uv_used() -> bool:

diff --git a/...sethis/_integrations/backend/uv/errors.py → src/usethis/_backend/uv/errors.py b/...sethis/_integrations/backend/uv/errors.py → src/usethis/_backend/uv/errors.py
diff --git a/src/usethis/_integrations/backend/uv/init.py → src/usethis/_backend/uv/init.py b/src/usethis/_integrations/backend/uv/init.py → src/usethis/_backend/uv/init.py
@@ -1,11 +1,11 @@
 from __future__ import annotations
 
-from usethis._config import usethis_config
-from usethis._integrations.backend.uv import (  # Use this style to allow test mocking
+from usethis._backend.uv import (  # Use this style to allow test mocking
     call,
 )
-from usethis._integrations.backend.uv.errors import UVInitError, UVSubprocessFailedError
-from usethis._integrations.file.pyproject_toml.errors import PyprojectTOMLInitError
+from usethis._backend.uv.errors import UVInitError, UVSubprocessFailedError
+from usethis._config import usethis_config
+from usethis._file.pyproject_toml.errors import PyprojectTOMLInitError
 
 
 def opinionated_uv_init() -> None:

diff --git a/...his/_integrations/backend/uv/link_mode.py → src/usethis/_backend/uv/link_mode.py b/...his/_integrations/backend/uv/link_mode.py → src/usethis/_backend/uv/link_mode.py
@@ -1,10 +1,10 @@
 import contextlib
 
-from usethis._integrations.backend.uv.toml import UVTOMLManager
-from usethis._integrations.file.pyproject_toml.errors import (
+from usethis._backend.uv.toml import UVTOMLManager
+from usethis._file.pyproject_toml.errors import (
     PyprojectTOMLValueAlreadySetError,
 )
-from usethis._integrations.file.pyproject_toml.io_ import PyprojectTOMLManager
+from usethis._file.pyproject_toml.io_ import PyprojectTOMLManager
 
 
 def ensure_symlink_mode() -> None:

diff --git a/...this/_integrations/backend/uv/lockfile.py → src/usethis/_backend/uv/lockfile.py b/...this/_integrations/backend/uv/lockfile.py → src/usethis/_backend/uv/lockfile.py
@@ -1,6 +1,6 @@
+from usethis._backend.uv.call import call_uv_subprocess
 from usethis._config import usethis_config
 from usethis._console import tick_print
-from usethis._integrations.backend.uv.call import call_uv_subprocess
 
 
 def ensure_uv_lock() -> None:

diff --git a/...sethis/_integrations/backend/uv/python.py → src/usethis/_backend/uv/python.py b/...sethis/_integrations/backend/uv/python.py → src/usethis/_backend/uv/python.py
@@ -2,14 +2,14 @@
 
 import re
 
-from usethis._integrations.backend.uv.call import call_uv_subprocess
-from usethis._integrations.backend.uv.errors import UVUnparsedPythonVersionError
-from usethis._integrations.file.pyproject_toml.errors import PyprojectTOMLNotFoundError
-from usethis._integrations.file.pyproject_toml.requires_python import (
+from usethis._backend.uv.call import call_uv_subprocess
+from usethis._backend.uv.errors import UVUnparsedPythonVersionError
+from usethis._file.pyproject_toml.errors import PyprojectTOMLNotFoundError
+from usethis._file.pyproject_toml.requires_python import (
     MissingRequiresPythonError,
     get_requires_python,
 )
-from usethis._integrations.python.version import PythonVersion
+from usethis._python.version import PythonVersion
 
 
 def get_available_uv_python_versions() -> set[str]:

diff --git a/src/usethis/_integrations/backend/uv/toml.py → src/usethis/_backend/uv/toml.py b/src/usethis/_integrations/backend/uv/toml.py → src/usethis/_backend/uv/toml.py
@@ -1,6 +1,6 @@
 from pathlib import Path
 
-from usethis._integrations.file.toml.io_ import TOMLFileManager
+from usethis._file.toml.io_ import TOMLFileManager
 
 
 class UVTOMLManager(TOMLFileManager):

diff --git a/...ethis/_integrations/backend/uv/version.py → src/usethis/_backend/uv/version.py b/...ethis/_integrations/backend/uv/version.py → src/usethis/_backend/uv/version.py
@@ -1,9 +1,9 @@
 import json
 
-from usethis._integrations.backend.uv.call import call_uv_subprocess
-from usethis._integrations.backend.uv.errors import UVSubprocessFailedError
+from usethis._backend.uv.call import call_uv_subprocess
+from usethis._backend.uv.errors import UVSubprocessFailedError
 
-FALLBACK_UV_VERSION = "0.9.21"
+FALLBACK_UV_VERSION = "0.10.0"
 
 
 def get_uv_version() -> str:

diff --git a/src/usethis/_config_file.py b/src/usethis/_config_file.py
@@ -4,13 +4,13 @@
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from usethis._integrations.backend.uv.toml import UVTOMLManager
+from usethis._backend.uv.toml import UVTOMLManager
+from usethis._file.ini.io_ import INIFileManager
+from usethis._file.pyproject_toml.io_ import PyprojectTOMLManager
+from usethis._file.setup_cfg.io_ import SetupCFGManager
+from usethis._file.toml.io_ import TOMLFileManager
+from usethis._file.yaml.io_ import YAMLFileManager
 from usethis._integrations.ci.bitbucket.yaml import BitbucketPipelinesYAMLManager
-from usethis._integrations.file.ini.io_ import INIFileManager
-from usethis._integrations.file.pyproject_toml.io_ import PyprojectTOMLManager
-from usethis._integrations.file.setup_cfg.io_ import SetupCFGManager
-from usethis._integrations.file.toml.io_ import TOMLFileManager
-from usethis._integrations.file.yaml.io_ import YAMLFileManager
 from usethis._integrations.pre_commit.yaml import PreCommitConfigYAMLManager
 
 if TYPE_CHECKING:

diff --git a/src/usethis/_core/author.py b/src/usethis/_core/author.py
@@ -1,6 +1,6 @@
 from usethis._console import tick_print
+from usethis._file.pyproject_toml.io_ import PyprojectTOMLManager
 from usethis._init import ensure_pyproject_toml
-from usethis._integrations.file.pyproject_toml.io_ import PyprojectTOMLManager
 
 
 def add_author(

diff --git a/src/usethis/_core/badge.py b/src/usethis/_core/badge.py
@@ -8,12 +8,12 @@
 
 from usethis._config import usethis_config
 from usethis._console import plain_print, tick_print, warn_print
-from usethis._core.readme import (
+from usethis._core.readme import add_readme
+from usethis._integrations.project.name import get_project_name
+from usethis._integrations.readme.path import (
     NonMarkdownREADMEError,
-    add_readme,
     get_markdown_readme_path,
 )
-from usethis._integrations.project.name import get_project_name
 
 if TYPE_CHECKING:
     from typing_extensions import Self

diff --git a/src/usethis/_core/ci.py b/src/usethis/_core/ci.py
@@ -1,12 +1,11 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
-
 from usethis._console import how_print, info_print
 from usethis._integrations.ci.bitbucket.config import (
     add_bitbucket_pipelines_config,
     remove_bitbucket_pipelines_config,
 )
+from usethis._tool.all_ import ALL_TOOLS
 from usethis._tool.impl.codespell import CodespellTool
 from usethis._tool.impl.deptry import DeptryTool
 from usethis._tool.impl.import_linter import ImportLinterTool
@@ -15,13 +14,10 @@
 from usethis._tool.impl.pytest import PytestTool
 from usethis._tool.impl.ruff import RuffTool
 
-if TYPE_CHECKING:
-    from usethis._tool.base import Tool
-
-# These are tools would run via pre-commit if available
-_CI_QA_TOOLS: list[type[Tool]] = [  # Not including pytest and pre-commit
-    # This order should match the canonical order in the function which adds
-    # steps
+# Ordered list of QA tools that should run in CI (matches canonical step order)
+# These tools run via pre-commit if available, otherwise directly in CI
+_CI_QA_TOOL_TYPES = [
+    PreCommitTool,
     PyprojectFmtTool,
     RuffTool,
     DeptryTool,
@@ -38,18 +34,17 @@ def use_ci_bitbucket(
         return
 
     if not remove:
-        use_pre_commit = PreCommitTool().is_used()
-        use_any_tool = (
-            use_pre_commit or PytestTool().is_used() or _using_any_ci_qa_tools()
-        )
+        use_any_tool = any(tool.is_used() for tool in ALL_TOOLS)
 
         add_bitbucket_pipelines_config(report_placeholder=not use_any_tool)
 
-        if use_pre_commit:
-            PreCommitTool().update_bitbucket_steps()
-        else:
-            for tool in _CI_QA_TOOLS:
-                tool().update_bitbucket_steps()
+        # Add steps for QA tools in canonical order
+        for tool_type in _CI_QA_TOOL_TYPES:
+            # Find the matching tool instance in ALL_TOOLS
+            for tool in ALL_TOOLS:
+                if isinstance(tool, tool_type):
+                    tool.update_bitbucket_steps()
+                    break
 
         PytestTool().update_bitbucket_steps(matrix_python=matrix_python)
 
@@ -58,10 +53,6 @@ def use_ci_bitbucket(
         remove_bitbucket_pipelines_config()
 
 
-def _using_any_ci_qa_tools():
-    return any(tool().is_used() for tool in _CI_QA_TOOLS)
-
-
 def print_how_to_use_ci_bitbucket() -> None:
     """Print how to use the Bitbucket CI service."""
     _suggest_pytest()

diff --git a/src/usethis/_core/list.py b/src/usethis/_core/list.py
@@ -5,8 +5,8 @@
 from typing_extensions import assert_never
 
 from usethis._console import table_print
-from usethis._core.readme import is_readme_used
-from usethis._integrations.ci.bitbucket.used import is_bitbucket_used
+from usethis._detect.ci.bitbucket import is_bitbucket_used
+from usethis._detect.readme import is_readme_used
 from usethis._tool.all_ import ALL_TOOLS
 from usethis._tool.impl.ruff import RuffTool