tools-python

name

tools-python

description

Gather Python architecture evidence with import-linter, pydeps, pyright/basedpyright, ruff, deptry, pipdeptree, uv tree, radon/lizard, and vulture. Use when a Python repo needs import contracts, module graphs, layer-boundary checks, type state, complexity hotspots, dead code, or dependency health for modularity and coupling review. NOT for TS/JS (use tools-typescript), Go (use tools-go), exact text discovery (use tools-code-search), or generic structural patterns (use tools-ast-grep).

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.

# 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.