Rename a Python symbol (function, class, method, variable, module-level name) and update every reference across the project — a binding-aware alternative to find-and-replace. Use your LSP to locate the symbol first; pass its file and 0-based line/character Position (character in UTF-16 units, exactly as the LSP returns). Defaults to a Dry Run that previews the full Blast Radius without writing; set apply=true to write. Supply expected_symbol (the identifier you believe is at the Position) when edits may have happened since your LSP answer — a mismatch fails safely instead of renaming the wrong code. Prefer a clean git working tree before applying, since git is the reversal mechanism; use git diff afterwards for exact text. Occurrences that cannot be proven to refer to this symbol are reported as uncertain_occurrences for you to adjudicate, never silently changed. Keep navigation and reading with your LSP, and formatting with black/ruff — this tool only changes code structure.

Move a Python symbol or module and update imports project-wide. Three targets, one tool: a global function/class/variable at a Position moves to another module (pass destination: that module's file path); a method at a Position moves to the class held by an attribute of self (pass destination_attribute, and optionally new_name); a whole module or package moves into a package when you omit line/character entirely (pass destination: the package directory). Coordinates are 0-based LSP line/character (UTF-16 units), exactly as your LSP returns them — locate the symbol with the LSP first. Defaults to a Dry Run preview; set apply=true to write. Prefer a clean git tree before applying, since git is the reversal mechanism. Moved resources report old_path; new files report created.

Extract a selected block of statements (or an expression) into a new method or function, with parameters and return values inferred from the data flow. Pass the file and the selection Range — start_line/start_character to end_line/end_character, 0-based, character in UTF-16 units, exactly as an editor selection. The selection must be complete statements or one complete expression. Options: replace_similar replaces other occurrences of the same pattern; to_global_scope extracts to module level; method_kind makes a classmethod or staticmethod. Defaults to a Dry Run preview; set apply=true to write. Read the code with your LSP first; leave formatting to black/ruff.

Extract a selected expression into a named variable, replacing the expression with the name. Pass the file and the selection Range (start_line/start_character to end_line/end_character, 0-based, UTF-16 units) covering exactly one expression. replace_similar also substitutes other occurrences of the same expression; to_global_scope creates the variable at module level. Defaults to a Dry Run preview; set apply=true to write. Read the code with your LSP first; leave formatting to black/ruff.

Inline the method, variable, or parameter at a Position — the server detects which kind, so just point at the name (0-based LSP line/character, UTF-16 units). Methods and variables: every certain use is replaced by the body or value; remove_definition=false keeps the definition; only_current_occurrence=true inlines just the occurrence at the Position. Parameters: the default value is written into call sites that omit it. Defaults to a Dry Run preview; set apply=true to write. Supply expected_symbol when edits may have intervened since your LSP answer, so a stale Position fails safely instead of inlining the wrong thing. Locate the definition with your LSP first; this tool only changes code.

Change a function or method signature — add, remove, or reorder parameters — updating every certain call site across the project. Point at the function name (0-based LSP line/character, UTF-16 units) and pass operations, a list applied in order: {action:'add', name, index?, default?, value?} (default is the parameter's default expression; value is what existing call sites should pass), {action:'remove', name or index}, {action:'reorder', order:[names or indices covering every parameter]}. For methods, parameter lists include self (index 0). across_class_hierarchy applies the change to matching overrides. Defaults to a Dry Run preview; set apply=true to write. Uncertain call sites are reported as uncertain_occurrences, never silently edited. Locate the function with your LSP first; this tool only changes code.

Convert a Python module file into a package: creates a directory of the module's name and moves the module to its init.py, rewriting relative imports to absolute. Pass the module's file path alone; no Position needed. Defaults to a Dry Run preview (created and moved entries appear in the Blast Radius); set apply=true to write. Use your LSP for navigation and reading; this tool only restructures.

Tidy a module's import block structurally (not formatting — black/ruff own that). Pass the file alone; no Position. One mode per call: 'organize' (default) sorts, deduplicates, and drops unused imports; 'expand_star_imports' replaces from m import * with explicit names (follow with 'organize' to prune unused ones); 'relatives_to_absolutes' rewrites relative imports as absolute; 'froms_to_imports' converts from-imports to plain imports; 'handle_long_imports' shortens deep module paths. Defaults to a Dry Run preview; set apply=true to write. An empty blast_radius means the module already conforms.

Turn a value used inside a function into a new parameter, with the original expression becoming the parameter's default. Select the expression — a name or attribute access such as a module constant or self. — with a Range (start_line/start_character to end_line/end_character, 0-based, character in UTF-16 units) inside the function body and give the parameter a name. Defaults to a Dry Run preview; set apply=true to write. Read the code with your LSP first; this tool only changes code.

Encapsulate a class attribute behind getter/setter methods, rewriting reads to the getter and writes to the setter across the project. Point at the attribute name (0-based LSP line/character, UTF-16 units), exactly as your LSP returns it. getter_name and setter_name override the default get_/set_ names. Defaults to a Dry Run preview; set apply=true to write. Accesses that cannot be proven to be this attribute are reported as uncertain_occurrences, never silently rewritten. Supply expected_symbol when edits may have intervened since your LSP answer. Locate the attribute with your LSP first; this tool only changes code.

Introduce a factory for a class and route instantiations through it. Point at the class name (0-based LSP line/character, UTF-16 units). By default the factory is a static method named factory_name on the class; global_factory=true creates a module-level function instead. Existing constructor calls across the project are rewritten to the factory. Defaults to a Dry Run preview; set apply=true to write. Supply expected_symbol when edits may have intervened since your LSP answer, so a stale Position fails safely. Locate the class with your LSP first; this tool only changes code.

Convert a method into a method object: a new class whose call holds the method body, with the original method delegating to it — a stepping stone for decomposing a complex method. Point at the method name (0-based LSP line/character, UTF-16 units) and name the new class. Defaults to a Dry Run preview; set apply=true to write. Supply expected_symbol when edits may have intervened since your LSP answer, so a stale Position fails safely. Read the method with your LSP first; this tool only changes code.

Promote a local variable inside a method to an instance field: the local becomes self. everywhere in the class. Point at the local variable's name (0-based LSP line/character, UTF-16 units). Defaults to a Dry Run preview; set apply=true to write. Supply expected_symbol when edits may have intervened since your LSP answer, so a stale Position fails safely. Locate the variable with your LSP first; this tool only changes code.

Replace code that duplicates a function's body with calls to that function, across the whole project. Point at the name of a module-level function (0-based LSP line/character, UTF-16 units); statements matching its body pattern are rewritten into calls. Defaults to a Dry Run preview; set apply=true to write. Sites that cannot be proven to match are reported as uncertain_occurrences for you to adjudicate, never silently rewritten. Supply expected_symbol when edits may have intervened since your LSP answer, so a stale Position fails safely. Locate the function with your LSP first; this tool only changes code.

Rewrite every site matching a structural Pattern into a Goal, project-wide — for transformations no dedicated refactoring expresses, such as migrating a deprecated call form (${obj}.get_attribute(${key}) -> ${obj}[${key}]) or collapsing an idiom. The Pattern is Python source with ${wildcard} placeholders; the Goal is the replacement template reusing those Wildcards. Prefer a dedicated behaviour-preserving tool (rename, inline, change_signature, move, use_function) whenever one fits; use rewrite only when none does, because a Rewrite is not behaviour-preserving: you assert that Pattern and Goal are equivalent, and the tool guarantees only that it rewrites exactly the Match Sites it reports. Control over-matching with per-Wildcard Match Constraints, e.g. constraints={"obj": {"type": "myapp.models.User"}}: name / type / object / instance narrow by a symbol's dotted path (one per Wildcard), and exact: true narrows to the Wildcard's literal name. type matches instances of exactly that class; instance matches instances of its subclasses (not the base class's own) — to cover a class and its subclasses, run once with each. A constrained run reports only the sites the constraint engages (matched or unsure), not every textual match. Each Match Site reports its certainty: matched (constraints satisfied) or unsure (a constraint that cannot be established at that site, common in dynamically typed code). Unsure sites are surfaced but not rewritten, so nothing is silently skipped; add unsure: true to a Wildcard's constraints to rewrite them too — they stay flagged unsure in the result for you to audit. When the Goal introduces a name the target modules do not import, pass imports (a list of import statements, added to each changed module, deduplicated); the tool never infers imports — checking for missing names is your LSP's job, so an omitted import leaves broken code. A rewrite that would produce unparsable Python fails safely in either mode, naming the file and parse location, with nothing written. Defaults to a Dry Run that previews without writing; review every Match Site for over-matching before setting apply=true. A truncated Match Site list ('showing N of M', unsure sites first) means the audit is incomplete — tighten the Pattern or Match Constraints and preview again before a Live Run. Both modes report the file-level Blast Radius and every Match Site (file + Range in 0-based UTF-16 LSP coordinates, against the pre-apply text — live targets for your LSP on a Dry Run, audit records after a Live Run). Start from a clean git tree, since git is the reversal mechanism, and run git diff after a Live Run to verify the equivalence you asserted. Pass root (the project directory) explicitly. Keep navigation and reading with your LSP; this tool only changes code.