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.

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