Menu
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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| 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. |
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.
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 | 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"}
]
}
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.
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