python-refactoring

name	python-refactoring
description	Analyze Python code for refactoring opportunities, complexity, dead code, security issues, modernization, test coverage gaps, and package-level structure — before proposing or making refactoring changes to Python code.

Python Refactoring Assistant

This project ships python-refactor-cli, a CLI that wraps rope, radon, vulture, pyrefly, mccabe, complexipy, bandit, pip-audit, and refurb into one set of refactoring-analysis commands. Use it whenever you are about to refactor, review, or assess the health of Python code in this repository.

Primary usage: CLI

Prefer running the CLI directly via subprocess (e.g. the Bash tool) over starting the MCP server for one-off analysis — it's faster and cheaper:

uv run python-refactor-cli <command> --format json ...

Every analysis command supports --format json for machine-parseable output. Run uv run python-refactor-cli <command> --help for full option details.

Command reference

Command	Target	Use it to...
analyze <file>	file	Full refactoring analysis of a single file
find-long-functions <file> [-t N]	file	Find functions at/over N lines (candidates for extraction)
extraction-guidance <file> [-fn NAME]	file	Get step-by-step guidance for extracting a specific function
test-coverage <source> [-t tests/]	file/dir	Find files/functions missing test coverage
tdd-guidance <file> [-fn NAME]	file	Get Red-Green-Refactor guidance for a function
security-scan <file>	file	Scan for security vulnerabilities, vulnerable deps, and outdated patterns
analyze-package <path>	package/dir	Full structural analysis of a package
package-metrics <path>	package/dir	Complexity, cohesion, coupling, health score
package-issues <path>	package/dir	Structural issues (god package, circular deps, etc.)
package-dependencies <path>	package/dir	Dependency graph and circular-dependency detection

Example:

uv run python-refactor-cli find-long-functions src/app.py --line-threshold 30 --format json

{
  "total_functions_analyzed": 12,
  "long_functions_found": 2,
  "line_threshold": 30,
  "functions": [
    {"name": "process_order", "start_line": 40, "end_line": 95, "length": 56, "location": "lines 40-95"}
  ]
}

Secondary/fallback: MCP server

If this environment is already running the tool as an MCP server (uv run python-refactor-cli server), the same underlying analysis is available as MCP tool calls instead of CLI subprocess calls:

CLI command	MCP tool
analyze	analyze_python_file
find-long-functions	find_long_functions
extraction-guidance	get_extraction_guidance
test-coverage	analyze_test_coverage
tdd-guidance	tdd_refactoring_guidance
security-scan	analyze_security_and_patterns
analyze-package	analyze_python_package
package-metrics	get_package_metrics
package-issues	find_package_issues

Only fall back to MCP tool calls when the CLI isn't reachable (e.g. no shell access) — otherwise use the CLI.

Workflow recipes

Find and fix long functions:

uv run python-refactor-cli find-long-functions src/app.py --format json
uv run python-refactor-cli extraction-guidance src/app.py --function-name process_order

Pre-commit security check:

uv run python-refactor-cli security-scan src/app.py --format table

Assess a package before a larger refactor:

uv run python-refactor-cli package-metrics src/mypackage --format json
uv run python-refactor-cli package-issues src/mypackage --format json