98 implement usethis tool import linter (#528)

* Add module finding function

* Renaming import-linter contracts for simplicity

* Add `usethis tool import-linter` implementation

* Add import-linter to ALL_TOOL_COMMANDS

* Add ImportLinterTool to ALL_TOOLS

* Use `force=True` argument for merged config sections

* Don't check for tool use if no associated ruff rules

* Update syncer test

* Handle case of failed graph build

* Include .importlinter in files_manager()

* Add import-linter to _HOOK_ORDER

* Update `usethis list` tests

* Implement `get_project_name` function

* Refactor uses of `get_name` to use `get_project_name`
Cope with FileNotFoundError

* update test to use new fallback project name

* Broaden exception handling for pyproject.toml project section being missing

* Update test to reflect new fallback case

* Upate test to reflect new fallback case

* Add tests

* Add test for removal case

* Add tests, new fallback method for get_project_name

* Protect INI section and option removal with exchandler
Update test

* Add _vary_network_conn decorator to tests

* Add xfail test for case of pre-commit with uv

* Add unit tests for ImportLinterTool.print_how_to_use

* Fix monkeypatching of sys.path in tests
Add test that small contracts are dropped

* Add test for cyclic imports

* Add test for Bitbucket integration

* Remove package-name-based fallback for get_project_name

* Add tests for print_how_to_use for PyprojectFmtTool and RequirementsTxtTool

* Update test to reflect inclusion of empty architectures

* Remove unnecessary error handling

* Add regex-based config keys for INI Import Linter configuration

* Properly configure INI Import Linter contracts

* Test adding to an existing INI file

* Fix pre-commit usage name

* Force the source dir onto Python path for grimp delegation, add tests, tweak contract name to only include final key

* Fix capfd in test_pre_commit_and_uv

* Fix 'TestPrintHowToUse' for Import Linter

* Fix test regex

* Fix match condition in test_config for Import Linter

* Revert change to capfd in test_uv_only

* Don't add INI contracts if they already exist

* Add failing tests

* Don't check INI keys if file doesn't exist

* Reflect new section newline behaviour in INI files for import-linter tests

* Handle root_packages vs. root_package

* Only display warning message once for no-packages-found in Import Linter config

* Calculate min depth across all root packages

* Remove unused function

* Test a more nested case

* Use full import name as contract name

Author: nathanjmcdougall

pyproject.toml

@@ -157,7 +157,7 @@ default-groups = [ "test", "dev", "doc" ]
 root_packages = [ "usethis" ]
 
 [[tool.importlinter.contracts]]
-name = "Modular Design"
+name = "usethis"
 type = "layers"
 layers = [
   "_test | __main__",
@@ -175,7 +175,7 @@ exhaustive = true
 exhaustive_ignores = [ "_version" ]
 
 [[tool.importlinter.contracts]]
-name = "Interface Independence"
+name = "usethis._interface"
 type = "layers"
 layers = [
   # Note; if you're adding an interface, make sure it's in the README too.
@@ -185,7 +185,7 @@ containers = [ "usethis._interface" ]
 exhaustive = true
 
 [[tool.importlinter.contracts]]
-name = "Core Modular Design"
+name = "usethis._core"
 type = "layers"
 layers = [
   # docstyle uses (Ruff) tool, badge uses readme
@@ -196,28 +196,37 @@ containers = [ "usethis._core" ]
 exhaustive = true
 
 [[tool.importlinter.contracts]]
-name = "Integrations Modular Design"
+name = "usethis._integrations"
 type = "layers"
 layers = [
   "ci | pre_commit",
   "uv | pytest | pydantic | sonarqube",
-  "project | file | python",
+  "project | python",
+  "file",
 ]
 containers = [ "usethis._integrations" ]
 exhaustive = true
 
 [[tool.importlinter.contracts]]
-name = "File Integrations Modular Design"
+name = "usethis._integrations.file"
 type = "layers"
 layers = [
   "pyproject_toml | setup_cfg",
   "ini | toml | yaml",
+  "dir",
 ]
 containers = [ "usethis._integrations.file" ]
 exhaustive = true
 
 [[tool.importlinter.contracts]]
-name = "CI Integrations Modular Design"
+name = "usethis._pipeweld"
+type = "layers"
+layers = [ "func", "result", "containers | ops" ]
+containers = [ "usethis._pipeweld" ]
+exhaustive = true
+
+[[tool.importlinter.contracts]]
+name = "usethis._integrations.ci"
 type = "layers"
 layers = [
   "bitbucket | github",

src/usethis/_config_file.py

@@ -22,6 +22,7 @@ def files_manager() -> Iterator[None]:
         CoverageRCManager(),
         DotRuffTOMLManager(),
         DotPytestINIManager(),
+        DotImportLinterManager(),
         PytestINIManager(),
         RuffTOMLManager(),
         ToxINIManager(),
@@ -45,12 +46,12 @@ def relative_path(self) -> Path:
         return Path(".coveragerc")
 
 
-class DotRuffTOMLManager(TOMLFileManager):
-    """Class to manage the .ruff.toml file."""
+class DotImportLinterManager(INIFileManager):
+    """Class to manage the .importlinter file."""
 
     @property
     def relative_path(self) -> Path:
-        return Path(".ruff.toml")
+        return Path(".importlinter")
 
 
 class DotPytestINIManager(INIFileManager):
@@ -61,6 +62,14 @@ def relative_path(self) -> Path:
         return Path(".pytest.ini")
 
 
+class DotRuffTOMLManager(TOMLFileManager):
+    """Class to manage the .ruff.toml file."""
+
+    @property
+    def relative_path(self) -> Path:
+        return Path(".ruff.toml")
+
+
 class PytestINIManager(INIFileManager):
     """Class to manage the pytest.ini file."""
 

src/usethis/_core/badge.py

@@ -9,8 +9,7 @@
 
 from usethis._console import tick_print, warn_print
 from usethis._core.readme import add_readme, get_readme_path
-from usethis._integrations.file.pyproject_toml.errors import PyprojectTOMLError
-from usethis._integrations.file.pyproject_toml.name import get_name
+from usethis._integrations.project.name import get_project_name
 
 if TYPE_CHECKING:
     from typing_extensions import Self
@@ -40,15 +39,7 @@ def get_pre_commit_badge() -> Badge:
 
 
 def get_pypi_badge() -> Badge:
-    try:
-        name = get_name()
-    except PyprojectTOMLError:
-        # Note; we don't want to create pyproject.toml because if it doesn't exist,
-        # the package is unlikely to be on PyPI. They could be using setup.py etc.
-        # So a second-best heuristic is the name of the current directory.
-        # Note that we need to filter out invalid characters
-        # https://packaging.python.org/en/latest/specifications/name-normalization/#name-format
-        name = re.sub(r"[^a-zA-Z0-9._-]", "", Path.cwd().stem)
+    name = get_project_name()
     return Badge(
         markdown=f"[![PyPI Version](https://img.shields.io/pypi/v/{name}.svg)](<https://pypi.python.org/pypi/{name})"
     )

src/usethis/_core/readme.py

@@ -4,7 +4,8 @@
 
 from usethis._console import box_print, tick_print
 from usethis._integrations.file.pyproject_toml.errors import PyprojectTOMLError
-from usethis._integrations.file.pyproject_toml.name import get_description, get_name
+from usethis._integrations.file.pyproject_toml.name import get_description
+from usethis._integrations.project.name import get_project_name
 from usethis._integrations.uv.init import ensure_pyproject_toml
 
 
@@ -21,10 +22,7 @@ def add_readme() -> None:
 
     ensure_pyproject_toml()
 
-    try:
-        project_name = get_name()
-    except PyprojectTOMLError:
-        project_name = None
+    project_name = get_project_name()
 
     try:
         project_description = get_description()

src/usethis/_core/show.py

@@ -1,15 +1,13 @@
 from __future__ import annotations
 
 from usethis._config import usethis_config
-from usethis._integrations.file.pyproject_toml.name import get_name
+from usethis._integrations.project.name import get_project_name
 from usethis._integrations.sonarqube.config import get_sonar_project_properties
 from usethis._integrations.uv.init import ensure_pyproject_toml
 
 
 def show_name() -> None:
-    with usethis_config.set(quiet=True):
-        ensure_pyproject_toml()
-    print(get_name())
+    print(get_project_name())
 
 
 def show_sonarqube_config() -> None:

src/usethis/_core/tool.py

@@ -24,6 +24,7 @@
     CodespellTool,
     CoverageTool,
     DeptryTool,
+    ImportLinterTool,
     PreCommitTool,
     PyprojectFmtTool,
     PyprojectTOMLTool,
@@ -94,6 +95,28 @@ def use_deptry(*, remove: bool = False) -> None:
         tool.remove_managed_files()
 
 
+def use_import_linter(*, remove: bool = False) -> None:
+    tool = ImportLinterTool()
+
+    ensure_pyproject_toml()
+
+    if not remove:
+        tool.add_dev_deps()
+        tool.add_configs()
+        if PreCommitTool().is_used():
+            tool.add_pre_commit_repo_configs()
+        else:
+            tool.update_bitbucket_steps()
+
+        tool.print_how_to_use()
+    else:
+        tool.remove_pre_commit_repo_configs()
+        tool.remove_bitbucket_steps()
+        tool.remove_configs()
+        tool.remove_dev_deps()
+        tool.remove_managed_files()
+
+
 def use_pre_commit(*, remove: bool = False) -> None:
     tool = PreCommitTool()
     pyproject_fmt_tool = PyprojectFmtTool()
@@ -331,8 +354,9 @@ def use_ruff(*, remove: bool = False, minimal: bool = False) -> None:
             "UP",
         ]
         for _tool in ALL_TOOLS:
-            if _tool.is_used():
-                rules += _tool.get_associated_ruff_rules()
+            associated_rules = _tool.get_associated_ruff_rules()
+            if associated_rules and _tool.is_used():
+                rules += associated_rules
         ignored_rules = [
             "PLR2004",  # https://github.com/nathanjmcdougall/usethis-python/issues/105
             "SIM108",  # https://github.com/nathanjmcdougall/usethis-python/issues/118

src/usethis/_integrations/file/dir.py

@@ -0,0 +1,16 @@
+from pathlib import Path
+
+
+def get_project_name_from_dir() -> str:
+    # Use the name of the parent directory
+    # Names must start and end with a letter or digit and may only contain -, _, ., and
+    # alphanumeric characters. Any other characters will be dropped. If there are no
+    # valid characters, the name will be "hello_world".
+    # https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#name
+    # https://packaging.python.org/en/latest/specifications/name-normalization/#name-format
+    dir_name = Path.cwd().name
+    name = "".join(c for c in dir_name if c.isalnum() or c in {"-", "_", "."})
+    if not name:
+        name = "hello_world"
+
+    return name

src/usethis/_integrations/file/ini/io_.py

@@ -99,20 +99,17 @@ def __contains__(self, keys: Sequence[Key]) -> bool:
             return False
 
         if len(keys) == 0:
-            # The root level exists if the file exists
             return True
         elif len(keys) == 1:
             (section_key,) = keys
-            return section_key in root
+            for _ in _itermatches(root.sections(), key=section_key):
+                return True
         elif len(keys) == 2:
-            section_key, option_key = keys
-            try:
-                return option_key in root[section_key]
-            except KeyError:
-                return False
-        else:
-            # Nested keys can't exist in INI files.
-            return False
+            (section_key, option_key) = keys
+            for section_strkey in _itermatches(root.sections(), key=section_key):
+                for _ in _itermatches(root[section_strkey].options(), key=option_key):
+                    return True
+        return False
 
     def __getitem__(self, item: Sequence[Key]) -> Any:
         keys = item
@@ -194,7 +191,7 @@ def _set_value_in_root(
         # We don't want to remove existing ones to keep their positions.
         for section_key in root.sections():
             if section_key not in root_dict:
-                root.remove_section(name=section_key)
+                _remove_section(updater=root, section_key=section_key)
 
         TypeAdapter(dict).validate_python(root_dict)
         assert isinstance(root_dict, dict)
@@ -208,7 +205,9 @@ def _set_value_in_root(
                     # We need to remove options that are not in the new dict
                     # We don't want to remove existing ones to keep their positions.
                     if option_key not in section_dict:
-                        root.remove_option(section=section_key, option=option_key)
+                        _remove_option(
+                            updater=root, section_key=section_key, option_key=option_key
+                        )
             else:
                 root.add_section(section_key)
 
@@ -249,7 +248,9 @@ def _set_value_in_section(
                 # We need to remove options that are not in the new dict
                 # We don't want to remove existing ones to keep their positions.
                 if option_key not in section_dict:
-                    root.remove_option(section=section_key, option=option_key)
+                    _remove_option(
+                        updater=root, section_key=section_key, option_key=option_key
+                    )
 
         for option_key, option in section_dict.items():
             INIFileManager._validated_set(
@@ -392,17 +393,19 @@ def _delete_strkeys(self, strkeys: Sequence[str]) -> None:
         if len(strkeys) == 0:
             removed = False
             for section_key in root.sections():
-                removed |= root.remove_section(name=section_key)
+                removed |= _remove_section(updater=root, section_key=section_key)
         elif len(strkeys) == 1:
             (section_key,) = strkeys
-            removed = root.remove_section(name=section_key)
+            removed = _remove_section(updater=root, section_key=section_key)
         elif len(strkeys) == 2:
             section_key, option_key = strkeys
-            removed = root.remove_option(section=section_key, option=option_key)
+            removed = _remove_option(
+                updater=root, section_key=section_key, option_key=option_key
+            )
 
             # Cleanup section if empty
             if not root[section_key].options():
-                removed = root.remove_section(name=section_key)
+                _remove_section(updater=root, section_key=section_key)
         else:
             msg = (
                 f"INI files do not support nested config, whereas access to "
@@ -481,11 +484,11 @@ def _remove_from_list_in_option(
 
         if len(new_values) == 0:
             # Remove the option if empty
-            root.remove_option(section=section_key, option=option_key)
+            _remove_option(updater=root, section_key=section_key, option_key=option_key)
 
             # Remove the section if empty
             if not root[section_key].options():
-                root.remove_section(name=section_key)
+                _remove_section(updater=root, section_key=section_key)
 
         elif len(new_values) == 1:
             # If only one value left, set it directly
@@ -544,6 +547,17 @@ def _(value: Section) -> dict[str, Any]:
     return {option.key: option.value for option in value.iter_options()}
 
 
+def _remove_option(updater: INIDocument, section_key: str, option_key: str) -> bool:
+    try:
+        return updater.remove_option(section=section_key, option=option_key)
+    except configparser.NoSectionError as err:
+        raise INIValueMissingError(err) from None
+
+
+def _remove_section(updater: INIDocument, section_key: str) -> bool:
+    return updater.remove_section(name=section_key)
+
+
 def _itermatches(values: Iterable[str], /, *, key: Key):
     """Iterate through an iterable and find all matches for a key."""
     for value in values:

src/usethis/_integrations/file/pyproject_toml/errors.py

@@ -34,16 +34,16 @@ class UnexpectedPyprojectTOMLIOError(PyprojectTOMLError, UnexpectedTOMLIOError):
     """Raised when an unexpected attempt is made to read or write the pyproject.toml file."""
 
 
-class PyprojectTOMLProjectNameError(PyprojectTOMLError):
-    """Raised when the 'project.name' key is missing or invalid in 'pyproject.toml'."""
+class PyprojectTOMLProjectSectionError(PyprojectTOMLError):
+    """Raised when the 'project' section is missing or invalid in 'pyproject.toml'."""
 
 
-class PyprojectTOMLProjectDescriptionError(PyprojectTOMLError):
-    """Raised when the 'project.description' key is missing or invalid in 'pyproject.toml'."""
+class PyprojectTOMLProjectNameError(PyprojectTOMLProjectSectionError):
+    """Raised when the 'project.name' key is missing or invalid in 'pyproject.toml'."""
 
 
-class PyprojectTOMLProjectSectionError(PyprojectTOMLError):
-    """Raised when the 'project' section is missing or invalid in 'pyproject.toml'."""
+class PyprojectTOMLProjectDescriptionError(PyprojectTOMLProjectSectionError):
+    """Raised when the 'project.description' key is missing or invalid in 'pyproject.toml'."""
 
 
 class PyprojectTOMLValueAlreadySetError(PyprojectTOMLError, TOMLValueAlreadySetError):