tools-python

# Python tools Dependency, complexity, and quality evidence for Python targets. These cover the import graph, layering contracts, type state, dead code, and dependency hygiene. Evidence dimensions: **dependency**, **structural**, **semantic** (type checkers), and **complexity** hotspots. ## When to use Use when the system map shows `pyproject.toml` / `setup.py` / `requirements`. Pick to the question: layering contracts (import-linter), module graph (pydeps), types (pyright/basedpyright), lint (ruff), dependency hygiene (deptry, pipdeptree, uv tree), complexity/size (radon, lizard), dead code (vulture). Use the results to judge module boundaries, dependency direction, cohesion, and architecture fitness. ## Commands Redirect caches to `$TMPDIR` (`RUFF_CACHE_DIR=$TMPDIR/ruff`). Prefer `uv run`/`uvx` so the target env is untouched. ```sh # Layering / boundary contracts (config in .importlinter or pyproject) uvx --from import-linter lint-imports # Import/module dependency graph (DOT for the system map) uvx pydeps src/pkg --max-bacon 2 --noshow -T dot # Type errors (semantic) uvx pyright # or: uvx basedpyright # Lint (style + many bug classes) RUFF_CACHE_DIR=$TMPDIR/ruff uvx ruff check . # Declared-vs-used dependency mismatches uvx deptry src # Installed dependency tree uvx pipdeptree # or, for a uv project: uv tree # Cyclomatic complexity / maintainability hotspots uvx radon cc -s src # or: uvx lizard src # Dead code (unused functions/vars — confirm before trusting) uvx vulture src ``` ## Evidence output Record: - `dimension`: dependency, structural, semantic, or complexity hotspot. - `source`: Python command, package path, environment/tool runner, and cache location. - `facts`: import contracts, module edges, cycles, type/lint findings, dead-code hypotheses, or clean scope. - `limits`: missing deps, dynamic imports, optional deps, cache failures, or partial package coverage. ## Confidence impact - import-linter contracts and pydeps cycles are direct dependency/boundary evidence: `tools_used`, raises `dependency_graph_health` and `boundary_integrity` confidence. - An existing import-linter contract run in CI is an enforced fitness check — count it toward `architecture_fitness`. A contract you'd recommend is not. - radon/lizard complexity flags cohesion/size hotspots (god modules); pair with the dependency graph before scoring `cohesion_modularity`. - vulture and deptry have false positives (dynamic imports, optional deps) — treat their output as hypotheses to confirm, not settled findings. ## Failure and missing-tool handling - Tool missing and offline → dependency dimension `tools_missing` + install hint; fall back to ast-grep import scans and the code graph, recording reduced coverage. - pyright failing because deps aren't installed → `tools_failed` (env state), not "no type errors." Note the env and cap confidence. - A tool writing a cache into a read-only target fails on I/O, not on findings — redirect the cache and rerun before recording failure. ## When to stop One graph/contract tool plus one type/lint pass answers the structural and semantic questions for a package. Stop once cycles, contracts, types, and obvious hotspots are recorded — don't run radon and lizard and vulture for the same answer. Dynamic-dispatch reachability that static tools can't resolve is a coverage gap: record it rather than guessing. ## Hard rules - Distinguish an enforced import-linter contract (raises fitness) from a recommended one. - vulture/deptry results are hypotheses until confirmed against dynamic usage. - Tool failure from an uninstalled env is `tools_failed`, not clean. - Use the CLIs; do not reimplement graph or type analysis in package code.