import-surgeon 4.0.0

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.

---

🚀 Quick Start

Prerequisites

• Python 3.8+
• Dependencies (installed automatically): rich, tqdm, pyyaml, regex, black, isort, libcst.

Installation

pip install import-surgeon

Usage Examples

1. Interactive Wizard (New! 🌟) launch the TUI to guide you through the refactor:

import-surgeon --interactive

2. Basic dry-run Preview changes without modifying files:

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

3. Apply changes with Formatting Apply the refactor and run black/isort immediately:

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

4. Rewrite dotted usages Also update old.mod.Client to new.mod.Client in code:

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

---

✨ Key Features

• Accurate import rewrites: LibCST powered symbol movement (AST-exact).
• Interactive TUI: Wizard-style guide for safe refactoring (--interactive).
• Dotted name rewrites: old.module.Foo → new.module.Foo if --rewrite-dotted.
• Advanced Alias Handling: Updates usages like import old.pkg as o; o.Symbol() → new.pkg.Symbol().
• Dependency Analysis: Warns if moving a symbol breaks internal module dependencies.
• 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 (--format).
• Progress bar: tqdm fallback built-in.
• Parallel Processing: Multiprocessing support via --jobs N.

---

⚙️ Configuration & Advanced Usage

YAML Migration File (migrate.yml)

Define complex moves in a file for reproducible migrations:

migrations:
  - old_module: old.auth
    new_module: services.auth
    symbols: [User, Token]
  - old_module: utils.db
    new_module: core.database
    symbols: [connect, disconnect]

Run with config:

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

Rollback a Refactor

Made a mistake? Undo strictly the last operation using the summary file:

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

CLI Arguments

Flag	Description	Default
target	The target file or directory to scan.	.
--interactive, -i	Launch the interactive TUI wizard.	False
--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
--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
--version	Show the program's version number and exit.	N/A
--jobs, -j	Number of parallel jobs for processing files.	1
--symbol	Deprecated alias for --symbols.	None

¹ Required if not using a --config file or --interactive mode.

Exit Codes

• 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
    ├── interactive.py # TUI Wizard logic
    ├── process.py     # Main file processing and orchestration
    └── rollback.py    # Rollback logic

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

Phase 1: Foundation (Current)

• ✅ AST-Based Refactoring
• ✅ Robust CLI & Configuration Files
• ✅ File Backups & Git Integration
• ✅ Atomic Rollback Capability

Phase 2: The Standard (Current)

• ✅ Interactive TUI for selecting symbols.
• ✅ Symbol Dependency Analysis warning system.
• ✅ Parallel Processing support.
• ⬜ Enhanced Dry-Run with side-by-side diffs.
• ⬜ "Unused Import" Cleanup.

Phase 3: The Ecosystem

• ⬜ IDE Integration (VSCode / PyCharm plugins).
• ⬜ Pre-Commit Hook automation.
• ⬜ Public API for programmatic use.

Phase 4: The Vision

• ⬜ AI-Powered Refactoring Suggestions.
• ⬜ Automated Code Modernization.

See ROADMAP.md for detailed timeline and "God Level" goals.

---

🤝 Contributing & License

PRs welcome! We are looking for help with:

• Editor plugins
• Safety analyzers
• Batch migration assistants

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.