| name | python-refactor |
| description | Perform AST-aware Python refactors using the rope library. Handles parameter annotations, import management, rename, move, module-to-package conversion, de-re-export, relative-to-absolute import conversion, and custom source transformations with precise offset edits. Triggers: 'add type annotations', 'refactor with rope', 'python refactor skill', 'add imports', 'rename across files', 'rename package', 'annotate parameters', 'remove re-exports', 'de-export', 'absolutize imports', 'relative to absolute', 'module to package', 'split module', or needs AST-aware Python source code transformation. |
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
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
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
