import-updater

Update import statements across the codebase when modules are moved or renamed. This skill should be used after refactoring operations to ensure all imports remain functional and properly organized.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

The Import Updater skill automates the tedious and error-prone process of updating import statements across a codebase during refactoring. It ensures project integrity by systematically identifying moved or renamed modules and correcting their references, supporting complex patterns like relative/absolute imports and TYPE_CHECKING blocks to maintain a clean, functional development environment.

Use Cases

  • Large-scale Refactoring: Automatically fix broken imports across hundreds of files after moving core modules to a new directory structure.
  • Codebase Standardization: Converting inconsistent relative imports to absolute imports (or vice versa) to comply with project-wide style guides.
  • Technical Debt Reduction: Identifying and removing unused imports and consolidating redundant import statements to improve code maintainability.
  • Circular Dependency Resolution: Implementing the TYPE_CHECKING pattern with string annotations to resolve import loops while preserving type safety.
nameimport-updater
descriptionUpdate import statements across the codebase when modules are moved or renamed. This skill should be used after refactoring operations to ensure all imports remain functional and properly organized.

Import Updater

Overview

Systematically update import statements throughout a codebase when modules are moved, renamed, or reorganized during refactoring.

When to Use

Use this skill when:

  • Modules have been moved to new locations
  • Classes or functions have been extracted to different files
  • Package structure has changed
  • Converting between relative and absolute imports
  • Reorganizing import statements for consistency

Workflow

Step 1: Identify the Change

Document what moved:

  • Old location: optics.py
  • New location: prism/core/telescope.py
  • Items moved: Telescope, TelescopeAgg

Step 2: Find All Import Usages

Search for all files importing the moved items:

# Find direct imports
grep -r "from optics import" .
grep -r "import optics" .

# Find specific class imports
grep -r "Telescope" --include="*.py" .

Create a list of files that need updating.

Step 3: Update Each File

For each file found, update imports systematically:

Pattern 1: Update import statement

# Old
from optics import Telescope

# New
from prism.core.telescope import Telescope

Pattern 2: Update with alias

# Old
import optics

# New
from prism.core import telescope

Pattern 3: Multiple imports

# Old
from optics import Telescope, TelescopeAgg, Grid

# New
from prism.core.telescope import Telescope, TelescopeAgg
from prism.core.grid import Grid

Step 4: Handle Relative Imports

Within same package, use relative imports:

# In prism/core/aggregator.py importing from prism/core/telescope.py
from .telescope import Telescope  # Preferred

# Cross-package imports use absolute
from prism.models.networks import ProgressiveDecoder

Step 5: Organize Imports

Follow standard Python import organization:

# Standard library imports
import os
import sys
from pathlib import Path

# Third-party imports
import torch
import numpy as np
from torch import nn

# Local application imports
from .telescope import Telescope
from ..models.networks import ProgressiveDecoder

Step 6: Remove Unused Imports

After updating, check for unused imports:

  • Imports that are no longer needed
  • Duplicate imports
  • Imports that can be consolidated

Step 7: Verify Functionality

Test that updates work:

# Check syntax
python -m py_compile file.py

# Run tests if available
pytest tests/

# Try importing manually
python -c "from prism.core.telescope import Telescope"

Import Patterns

Absolute vs Relative

Use absolute imports when:

  • Importing from different packages
  • In scripts or main files
  • When import path is short and clear

Use relative imports when:

  • Within the same package
  • Refactoring might change package name
  • Avoiding repetition of package name

TYPE_CHECKING Pattern

Avoid circular imports with type hints:

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from .telescope import Telescope

def process_telescope(tel: 'Telescope') -> None:
    # String annotation avoids runtime import
    pass

Validation Checklist

After updating imports:

  • All files compile without import errors
  • No circular import warnings
  • Imports follow project conventions
  • Unused imports removed
  • Import organization consistent (isort style)
  • Tests pass
  • No "module not found" errors