assert-python-definition-is-used 20260829003639__tar.gz → 20260830020719__tar.gz

assert_python_definition_is_used-20260830020719/.claude/memories/pylint-refactor-messages-are-hard-failures.md

@@ -0,0 +1,9 @@
+# pylint refactor messages are hard failures
+
+`--fail-on=C,R,W` means pylint's R messages fail the job, so its default
+limits are hard limits here: 5 arguments, 15 locals, 12 branches, 50
+statements per function. Inline directives are banned, so the only route
+is to split the function.
+
+That is why `main` hands its work to `_findings_for` rather than growing
+another local for each mode it grew.

{assert_python_definition_is_used-20260829003639 → assert_python_definition_is_used-20260830020719}/.github/workflows/documentation.yml

@@ -7,9 +7,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Set up Node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7
         with:
           node-version: "20"
       - name: Install dependencies

{assert_python_definition_is_used-20260829003639 → assert_python_definition_is_used-20260830020719}/.github/workflows/release.yml

@@ -7,9 +7,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.13"
       - name: Install dependencies
@@ -23,9 +23,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.13"
       - name: Install dependencies
@@ -40,9 +40,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.13"
       - name: Install dependencies
@@ -57,9 +57,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.13"
       - name: Install dependencies
@@ -73,9 +73,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.13"
       - name: Install dependencies
@@ -91,9 +91,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.13"
       - name: Install dependencies
@@ -104,9 +104,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.13"
       - name: Install dependencies
@@ -123,9 +123,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Set up Node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7
         with:
           node-version: "20"
       - name: Install dependencies
@@ -136,9 +136,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Set up Node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7
         with:
           node-version: "20"
       - name: Install dependencies
@@ -149,9 +149,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.13"
       - name: Install dependencies
@@ -162,9 +162,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.13"
       - name: Install dependencies
@@ -175,9 +175,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.13"
       - name: Install dependencies
@@ -194,9 +194,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.13"
       - name: Install dependencies
@@ -233,11 +233,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.13"
       - id: version
@@ -267,9 +267,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.13"
       - name: Install dependencies
@@ -286,9 +286,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.13"
       - name: Install dependencies

{assert_python_definition_is_used-20260829003639/src/assert_python_definition_is_used.egg-info → assert_python_definition_is_used-20260830020719}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assert-python-definition-is-used
-Version: 20260829003639
+Version: 20260830020719
 Summary: CLI tool to assert that every public Python definition in a tree is used somewhere else
 Author-email: 10U Labs <dev@10ulabs.com>
 License-Expression: Apache-2.0
@@ -76,6 +76,7 @@ tests written for it, which is what a coverage gate hides.
 | `--exclude PATTERNS` | Comma-separated globs to leave out of both trees. |
 | `--assume-used-matching PATTERNS` | Globs of names a runtime invokes. |
 | `--assume-used-decorated-with PATHS` | Decorators a runtime invokes. |
+| `--unimported-packages` | Report packages nothing imports, not definitions. |
 | `--quiet` | Print nothing; report through the exit code. |
 | `--count` | Print only how many findings there were. |
 | `--verbose` | Print each file scanned, each one read as text, and a summary. |
@@ -120,7 +121,8 @@ file rather than failing, and `--verbose` names each file that fell back.
 
 Reading a name is still not resolving it. A file that calls its own
 unrelated function of the same name counts as a use, so the count is a
-lower bound rather than an exact figure.
+lower bound rather than an exact figure. `--unimported-packages` below
+asks a question that survives that, one package at a time.
 
 Two dead functions in one file that call each other still read as used,
 because those calls are real code. Finding those needs reachability from
@@ -192,6 +194,53 @@ the run altogether, so its own definitions go unchecked too. A file left
 out of the search is still read for the definitions it holds; it just
 does not get a vote on whether anything else is used.
 
+## Packages nothing imports
+
+A function is reached by being named, so asking what names it is the
+right question. A package is reached by being imported, which is a
+different question with a different answer. A package can be entirely
+dead while every one of its names still appears somewhere, because the
+caller that reimplemented it picked the same ordinary words.
+
+The name search is blind in proportion to how ordinary a package's names
+are. A package of `get_client`, `set_client` and `reset_clients` is
+nearly invisible to it, those words appearing everywhere; a package of
+`resolve_terraform_interpolation` is fully visible, that word appearing
+nowhere else. That is backwards, because the packages most likely to be
+quietly reimplemented are exactly the ones whose names are ordinary
+enough for a caller to pick the same ones.
+
+`--unimported-packages` asks the other question. It reads every directory
+directly below a definition tree that holds an `__init__.py`, collects
+the top-level module of every `import` and `from ... import` in the
+searched files, and reports each package nothing imports. The finding is
+anchored on the package's `__init__.py` at line 1, in the same
+`path:line:name` form as the rest:
+
+```text
+lib/python/aws_clients/__init__.py:1:aws_clients
+```
+
+`--dont-search-in` applies here as it does elsewhere, so a package
+imported only by its own tests is reported:
+
+```bash
+assert-python-definition-is-used lib/python \
+  --search-in lib/python --search-in src --search-in test \
+  --dont-search-in 'test/lib/python/test_{package}' \
+  --unimported-packages
+```
+
+It is a mode rather than a check folded into every run, because the two
+questions have different answers for a directory with no `__init__.py`,
+and because a repository may want one without the other. Run it as a
+second job beside the definition run.
+
+A relative import names no top-level module, so `from . import helper`
+inside a package does not make that package imported. A file that will
+not parse credits nothing here either: a bare word in text is not an
+import, and guessing one from text would be worse than staying quiet.
+
 ## GitHub Actions
 
 ```yaml
@@ -204,6 +253,19 @@ does not get a vote on whether anything else is used.
     verbose: true
 ```
 
+Beside it, ask whether the packages are imported at all:
+
+```yaml
+- name: Assert every package is imported outside its own tests
+  uses: 10U-Labs/assert-python-definition-is-used@latest
+  with:
+    dont-search-in: test/lib/python/test_{package}
+    search-in: lib/python scripts src test
+    trees: lib/python
+    unimported-packages: true
+    verbose: true
+```
+
 Over a test tree, name what pytest invokes:
 
 ```yaml

{assert_python_definition_is_used-20260829003639 → assert_python_definition_is_used-20260830020719}/README.md

@@ -52,6 +52,7 @@ tests written for it, which is what a coverage gate hides.
 | `--exclude PATTERNS` | Comma-separated globs to leave out of both trees. |
 | `--assume-used-matching PATTERNS` | Globs of names a runtime invokes. |
 | `--assume-used-decorated-with PATHS` | Decorators a runtime invokes. |
+| `--unimported-packages` | Report packages nothing imports, not definitions. |
 | `--quiet` | Print nothing; report through the exit code. |
 | `--count` | Print only how many findings there were. |
 | `--verbose` | Print each file scanned, each one read as text, and a summary. |
@@ -96,7 +97,8 @@ file rather than failing, and `--verbose` names each file that fell back.
 
 Reading a name is still not resolving it. A file that calls its own
 unrelated function of the same name counts as a use, so the count is a
-lower bound rather than an exact figure.
+lower bound rather than an exact figure. `--unimported-packages` below
+asks a question that survives that, one package at a time.
 
 Two dead functions in one file that call each other still read as used,
 because those calls are real code. Finding those needs reachability from
@@ -168,6 +170,53 @@ the run altogether, so its own definitions go unchecked too. A file left
 out of the search is still read for the definitions it holds; it just
 does not get a vote on whether anything else is used.
 
+## Packages nothing imports
+
+A function is reached by being named, so asking what names it is the
+right question. A package is reached by being imported, which is a
+different question with a different answer. A package can be entirely
+dead while every one of its names still appears somewhere, because the
+caller that reimplemented it picked the same ordinary words.
+
+The name search is blind in proportion to how ordinary a package's names
+are. A package of `get_client`, `set_client` and `reset_clients` is
+nearly invisible to it, those words appearing everywhere; a package of
+`resolve_terraform_interpolation` is fully visible, that word appearing
+nowhere else. That is backwards, because the packages most likely to be
+quietly reimplemented are exactly the ones whose names are ordinary
+enough for a caller to pick the same ones.
+
+`--unimported-packages` asks the other question. It reads every directory
+directly below a definition tree that holds an `__init__.py`, collects
+the top-level module of every `import` and `from ... import` in the
+searched files, and reports each package nothing imports. The finding is
+anchored on the package's `__init__.py` at line 1, in the same
+`path:line:name` form as the rest:
+
+```text
+lib/python/aws_clients/__init__.py:1:aws_clients
+```
+
+`--dont-search-in` applies here as it does elsewhere, so a package
+imported only by its own tests is reported:
+
+```bash
+assert-python-definition-is-used lib/python \
+  --search-in lib/python --search-in src --search-in test \
+  --dont-search-in 'test/lib/python/test_{package}' \
+  --unimported-packages
+```
+
+It is a mode rather than a check folded into every run, because the two
+questions have different answers for a directory with no `__init__.py`,
+and because a repository may want one without the other. Run it as a
+second job beside the definition run.
+
+A relative import names no top-level module, so `from . import helper`
+inside a package does not make that package imported. A file that will
+not parse credits nothing here either: a bare word in text is not an
+import, and guessing one from text would be worse than staying quiet.
+
 ## GitHub Actions
 
 ```yaml
@@ -180,6 +229,19 @@ does not get a vote on whether anything else is used.
     verbose: true
 ```
 
+Beside it, ask whether the packages are imported at all:
+
+```yaml
+- name: Assert every package is imported outside its own tests
+  uses: 10U-Labs/assert-python-definition-is-used@latest
+  with:
+    dont-search-in: test/lib/python/test_{package}
+    search-in: lib/python scripts src test
+    trees: lib/python
+    unimported-packages: true
+    verbose: true
+```
+
 Over a test tree, name what pytest invokes:
 
 ```yaml

{assert_python_definition_is_used-20260829003639 → assert_python_definition_is_used-20260830020719}/action.yml

@@ -27,6 +27,10 @@ inputs:
   trees:
     description: Trees holding the definitions to check (space-separated)
     required: true
+  unimported-packages:
+    default: "false"
+    description: Report packages nothing imports, instead of definitions
+    required: false
   verbose:
     default: "false"
     description: Show trees read, definitions found, findings and a summary
@@ -46,6 +50,8 @@ runs:
         [ "${{ inputs.verbose }}" = "true" ] && ARGS="$ARGS --verbose"
         [ "${{ inputs.fail-fast }}" = "true" ] && ARGS="$ARGS --fail-fast"
         [ "${{ inputs.warn-only }}" = "true" ] && ARGS="$ARGS --warn-only"
+        [ "${{ inputs.unimported-packages }}" = "true" ] &&
+          ARGS="$ARGS --unimported-packages"
         if [ -n "${{ inputs.exclude }}" ]; then
           ARGS="$ARGS --exclude '${{ inputs.exclude }}'"
         fi

{assert_python_definition_is_used-20260829003639 → assert_python_definition_is_used-20260830020719}/src/assert_python_definition_is_used/cli.py

@@ -15,6 +15,7 @@ from .scanner import (
     assumed_used,
     public_definitions,
     read_searched,
+    unimported_packages,
     unused_definitions,
 )
 
@@ -106,6 +107,16 @@ def create_parser() -> argparse.ArgumentParser:
         ),
     )
 
+    parser.add_argument(
+        "--unimported-packages",
+        action="store_true",
+        help=(
+            "Ask the package question instead: report every package under the trees "
+            "that nothing outside its own tests imports. A package is reached by being "
+            "imported, so a name match says nothing about whether it is still wanted."
+        ),
+    )
+
     output_group = parser.add_mutually_exclusive_group()
     output_group.add_argument(
         "--quiet",
@@ -183,6 +194,14 @@ def package_of(path: str, tree: str) -> str | None:
     return parts[0]
 
 
+def package_root(path: str, tree: str) -> str | None:
+    package = package_of(path, tree)
+    if package is None:
+        return None
+    anchor = os.path.join(os.path.normpath(tree), package, "__init__.py")
+    return package if os.path.normpath(path) == anchor else None
+
+
 def _tree_root(path: str) -> str:
     if os.path.isdir(path):
         return path
@@ -261,6 +280,15 @@ def read_definitions(
     return definitions
 
 
+def read_packages(paths: dict[str, str]) -> list[Definition]:
+    packages: list[Definition] = []
+    for path in sorted(paths):
+        package = package_root(path, paths[path])
+        if package is not None:
+            packages.append(Definition(path=path, line_number=1, name=package, package=package))
+    return packages
+
+
 def report_unparsed(searched: Searched) -> None:
     for path in searched.unparsed:
         print(f"Searching as text (will not parse): {path}")
@@ -316,6 +344,22 @@ def _report(result: ScanResult, args: argparse.Namespace) -> None:
         output_findings(result.findings, args.count)
 
 
+def _findings_for(
+    args: argparse.Namespace,
+    result: ScanResult,
+    definition_paths: dict[str, str],
+    sources: dict[str, str],
+    searched: Searched,
+) -> list[Finding]:
+    if args.unimported_packages:
+        packages = read_packages(definition_paths)
+        result.files_scanned = result.definitions_read = len(packages)
+        return unimported_packages(packages, searched, args.dont_search_in)
+    definitions = read_definitions(definition_paths, sources, result, args.verbose)
+    checked = assume_used(definitions, args, result)
+    return unused_definitions(checked, searched, args.dont_search_in)
+
+
 def main(argv: Sequence[str] | None = None) -> None:
     args = create_parser().parse_args(argv)
     exclude_patterns = parse_patterns(args.exclude)
@@ -340,14 +384,12 @@ def main(argv: Sequence[str] | None = None) -> None:
         print()
 
     sources = read_sources({**search_paths, **definition_paths}, result, args.verbose)
-    definitions = read_definitions(definition_paths, sources, result, args.verbose)
-    definitions = assume_used(definitions, args, result)
     to_search = {path: content for path, content in sources.items() if path in search_paths}
     searched = read_searched(to_search)
     if args.verbose:
         report_unparsed(searched)
 
-    findings = unused_definitions(definitions, searched, args.dont_search_in)
+    findings = _findings_for(args, result, definition_paths, sources, searched)
     result.findings = findings[:1] if (args.fail_fast and findings) else findings
 
     _report(result, args)

{assert_python_definition_is_used-20260829003639 → assert_python_definition_is_used-20260830020719}/src/assert_python_definition_is_used/scanner.py

@@ -8,7 +8,7 @@ from functools import lru_cache
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Callable, Sequence
 
 DEFINITION_NODES = (ast.AsyncFunctionDef, ast.ClassDef, ast.FunctionDef)
 DOCSTRING_HOLDERS = (ast.AsyncFunctionDef, ast.ClassDef, ast.FunctionDef, ast.Module)
@@ -54,6 +54,7 @@ class Finding:
 class Searched:
     uses: dict[str, frozenset[str]]
     unparsed: dict[str, str]
+    imports: dict[str, frozenset[str]]
 
 
 def is_public(name: str) -> bool:
@@ -163,8 +164,19 @@ def names_used(tree: ast.Module) -> frozenset[str]:
     return frozenset(names)
 
 
+def imported_modules(tree: ast.Module) -> frozenset[str]:
+    modules: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            modules.update(alias.name.split(".")[0] for alias in node.names)
+        elif isinstance(node, ast.ImportFrom) and not node.level and node.module:
+            modules.add(node.module.split(".")[0])
+    return frozenset(modules)
+
+
 def read_searched(sources: dict[str, str]) -> Searched:
     uses: dict[str, frozenset[str]] = {}
+    imports: dict[str, frozenset[str]] = {}
     unparsed: dict[str, str] = {}
     for path in sorted(sources):
         try:
@@ -173,7 +185,8 @@ def read_searched(sources: dict[str, str]) -> Searched:
             unparsed[path] = sources[path]
             continue
         uses[path] = names_used(tree)
-    return Searched(uses=uses, unparsed=unparsed)
+        imports[path] = imported_modules(tree)
+    return Searched(uses=uses, unparsed=unparsed, imports=imports)
 
 
 def is_assumed_used_by_name(name: str, patterns: Sequence[str]) -> bool:
@@ -228,14 +241,41 @@ def is_used(
     return False
 
 
-def unused_definitions(
+def is_imported(
+    definition: Definition, searched: Searched, unsearched: str | None = None
+) -> bool:
+    return any(
+        definition.name in imported
+        for path, imported in searched.imports.items()
+        if not _is_unsearched(path, unsearched)
+    )
+
+
+def _findings_over(
     definitions: list[Definition],
     searched: Searched,
-    unsearched_template: str | None = None,
+    unsearched_template: str | None,
+    reached: Callable[[Definition, Searched, str | None], bool],
 ) -> list[Finding]:
     findings = []
     for definition in definitions:
         unsearched = unsearched_directory(unsearched_template, definition.package)
-        if not is_used(definition, searched, unsearched):
+        if not reached(definition, searched, unsearched):
             findings.append(Finding(definition=definition))
     return findings
+
+
+def unused_definitions(
+    definitions: list[Definition],
+    searched: Searched,
+    unsearched_template: str | None = None,
+) -> list[Finding]:
+    return _findings_over(definitions, searched, unsearched_template, is_used)
+
+
+def unimported_packages(
+    packages: list[Definition],
+    searched: Searched,
+    unsearched_template: str | None = None,
+) -> list[Finding]:
+    return _findings_over(packages, searched, unsearched_template, is_imported)