zaripych Python Refactor
Use python-rope for AST-aware Python refactoring. Rope provides precise offset editing, import management, and cross-file rename/move — safer than regex for source code transformation.
Script location
All scripts live in this skill's scripts/ directory — not in the target project. Commands in the docs use relative paths like scripts/move_module.py for brevity. When running them, resolve relative to this skill's base directory:
SKILL_DIR=<this skill's base directory>
uv run python "$SKILL_DIR/scripts/move_module.py" ...
Prerequisites
Rope must be a dev dependency: uv add --dev rope
When to use rope vs direct edits
Use rope scripts when the refactor touches imports or symbols across multiple files — rope resolves references and rewrites all callers automatically. Use direct Edit tool or regex when changes are localized (≤3 files, confirm with grep!) or non-Python.
Project structure and rope configuration
Rope auto-detects source folders. A folder containing a package (subfolder with __init__.py) or .py files is a source folder. For src/ layouts, src/ is auto-detected — no config needed.
Set preferred_import_style in pyproject.toml:
[tool.rope.imports]
preferred_import_style = "from-global"
Important: source folder roots (like src/) must never contain an __init__.py.
Available scripts
Each script has a companion .md file with the exact workflow to follow. Read the companion doc before running a script.
| Script | What it does | Doc |
|---|---|---|
move_module.py |
Move a module/package to a new directory | move_module.md |
rename_module.py |
Rename a module/package in place | rename_module.md |
rename_symbol.py |
Rename a symbol (requires line number — read file first) | rename_symbol.md |
move_globals.py |
Move globals between modules | move_globals.md |
module_to_package.py |
Convert module to package, split globals into submodules | module_to_package.md |
deexport.py |
Remove re-exports from __init__.py |
deexport.md |
absolutize.py |
Convert relative imports to absolute | absolutize.md |
add_param_annotations |
Add type annotations to parameters in bulk | add_param_annotations.md |
add_imports |
Add imports to files matching a predicate | add_imports.md |
refactor_history.py |
List refactor history, undo/redo | See below |
Refactor history
uv run python scripts/refactor_history.py list # show history and undo/redo usage
Custom refactoring scripts
If none of the existing scripts fit, write a custom one. See custom_scripts.md — MANDATORY when writing any refactor script.
References
| File | Load |
|---|---|
| custom_scripts.md | MANDATORY when writing any refactor script |
| annotations.md | MANDATORY when writing custom annotation logic |
| imports.md | MANDATORY when writing custom import logic |
| rope-api.md | Optional — for built-in rope refactorings |
Keywords
rope, refactor, python, AST, annotations, type annotations, imports, rename, rename module, rename package, move, module to package, split module, source transformation, code modification, re-export, deexport, absolutize, relative imports, lazy imports, init.py