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