import-surgeon 3.0.2

Precision import refactoring tool — rewrite, migrate, and sanitize Python imports project-wide with safety and accuracy.

---

import-surgeon 🩺⚙️

Precision Python import refactoring — safe, atomic, AST-exact, rollback-friendly.

---

🧠 Overview

import-surgeon is an Elite import refactoring engine for Python codebases.

It precisely updates imports and moves symbols across modules without breaking your code, using full LibCST AST guarantees, backup files, atomic writes, and optional auto-formatting.

Think of it as libcst + git-protection + atomic rollback-safe refactor surgery

Use it for:

✅ Package restructures ✅ Module renames ✅ Moving functions/classes between files ✅ Gradual API migrations ✅ Org-wide import cleanup ✅ CI-safe automated refactors

No regex. No AST guessing. No broken imports.

---

✨ Features

Capability Description

Accurate import rewrites LibCST powered symbol movement (AST-exact) Dotted name rewrites old.module.Foo → new.module.Foo if --rewrite-dotted Atomic file updates Guaranteed atomic writes + metadata restore Auto backup & rollback --no-backup optional; --rollback supported Supports aliases from A import Foo as Bar handled correctly Respects relative imports --force-relative + auto base-package detection Batch migrations YAML config for multi-module migrations Safe in CI --require-clean-git to prevent dirty changes Git auto-commit --auto-commit "msg" Optional format Black + isort applied after changes Warnings for risky spots Wildcards, dotted patterns, skipped rel imports Progress bar tqdm fallback built-in

---

📦 Installation

pip install import-surgeon

Optional but recommended for improved encoding detection:

pip install chardet

---

🛠 Usage

Basic dry-run (default)

import-surgeon --old-module utils --new-module core.utils --symbols load,save

Apply changes

import-surgeon --old-module old.pkg --new-module new.pkg --symbols Foo,Bar --apply

Rewrite dotted usages too

import-surgeon --apply --rewrite-dotted
--old-module old.mod --new-module new.mod --symbols Client

Use YAML migrations file

migrate.yml

migrations:

• old_module: old.auth new_module: services.auth symbols: [User, Token]

Run:

import-surgeon --config migrate.yml --apply

Rollback a refactor

import-surgeon --rollback --summary-json summary.json

---

🧪 Example Output

✔️ New imports inserted ✔️ Old imports removed ✔️ Diff preview in dry-run ✔️ JSON report with file list, change lines & risks

---

🔒 Safety Guarantees

Dry run by default

File backups by default

Atomic writes (no corruption)

Git-clean check option

Per-file encoding detection

Refuses unsafe wildcard rewrites unless configured

---

🧠 CLI Options

Flag	Description	Default
target	The target file or directory to scan.	.
--old-module	The fully qualified module path to move symbols from.	Required¹
--new-module	The fully qualified module path to move symbols to.	Required¹
--symbols	A comma-separated list of symbols to move.	Required¹
--apply	Apply changes to files instead of showing a dry-run.	False
--config	Path to a YAML file for batch migrations.	None
--rewrite-dotted	Rewrite direct module.symbol usages in code.	False
--format	Apply black and isort formatting after changes.	False
--rollback	Roll back a previous migration using a summary file.	False
--summary-json	Path to write a JSON summary of all changes.	None
--auto-commit	Git commit message to auto-commit changes.	None
--require-clean-git	Abort if the Git repository has uncommitted changes.	False
--no-backup	Disable creation of .bak files for changed modules.	False
--base-package	Specify the base package for resolving relative imports.	Auto-detected from Git root
--force-relative	Force the use of relative imports where possible.	False
--exclude	Comma-separated glob patterns to exclude from scan.	None
--max-files	Maximum number of files to scan.	10000
--strict-warnings	Exit with a non-zero code if any warnings occur.	False
--quiet	Set the logging level (none, errors, all).	none
-v, --verbose	Increase logging verbosity.	0 (Warning)
--version	Show the program's version number and exit.	N/A
--symbol	Deprecated alias for --symbols.	None

¹ Required if not using a --config file.

---

🚦 Exit Codes

Code Meaning

0 Success 1 Changes had errors 2 CLI/config error

---

🏗️ Architecture

The core logic resides in the src/import_surgeon/ directory.

src/import_surgeon/
├── cli.py             # Main CLI entry point and argument parsing
├── banner.py          # ASCII art banner
└── modules/           # Core logic modules
    ├── __init__.py
    ├── analysis.py    # AST analysis and symbol detection
    ├── config.py      # YAML configuration loading
    ├── cst_utils.py   # LibCST helper functions
    ├── encoding.py    # File encoding detection
    ├── file_ops.py    # File read/write operations
    ├── git_ops.py     # Git repository interactions
    └── process.py     # Main file processing and orchestration

The tool works by parsing Python files into an Abstract Syntax Tree (AST) using LibCST, identifying import statements, and then surgically replacing them based on the migration rules. It ensures safety through backups, atomic writes, and optional Git integration.

---

🧩 Roadmap

Symbol dependency graph warnings

VSCode / PyCharm integration

Preview UI with selectable edits

Interactive TUI surgeon console

NeoVim LSP hooks

---

🤝 Contributing

PRs welcome, especially for:

Editor plugins

Safety analyzers

Batch migration assistants

Code mod multi-tool integration

---

📜 License

MIT — commercial and open use welcome.

---

⭐ Support

Star the repo — every ⭐ funds more time for DevTools research 🙏

https://github.com/dhruv13x/import-surgeon

---

🩺 Your imports deserve precision surgery — not blind search-replace. Run import-surgeon and refactor with confidence.

---