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