Refactoring Checklist

# Measure current state
wc -l src/**/*.py                    # Line counts
grep -r "Dict\[str" src/             # Raw dict usage
grep -r "Any" src/                   # Any type usage
grep -r "except:" src/               # Bare excepts
pytest --cov=src --cov-report=term   # Current coverage

git checkout -b refactor/module-name

# BEFORE
def process(data: dict) -> dict:
    return {"status": "ok", "result": data["value"]}
 
# AFTER
class ProcessInput(BaseModel):
    value: str
    count: int = Field(ge=0)
 
class ProcessOutput(BaseModel):
    status: str
    result: str
 
def process(data: ProcessInput) -> ProcessOutput:
    return ProcessOutput(status="ok", result=data.value)

# BEFORE
try:
    result = api_call()
except Exception as e:
    return {"error": str(e)}
 
# AFTER
try:
    result = api_call()
except httpx.HTTPStatusError as e:
    raise NetworkError(f"API call failed: {e}") from e

large_module.py (800 lines)
├── Validation (150 lines) → validators/user.py
├── Repository (200 lines) → repositories/user.py
├── Service (250 lines)    → services/user.py
├── Helpers (100 lines)    → utils/helpers.py
└── Constants (100 lines)  → _constants.py

# BEFORE — hidden dependencies
class UserService:
    def __init__(self):
        self.db = get_database()
        self.cache = get_cache()
 
# AFTER — explicit injection
class UserService:
    def __init__(self, db: DatabaseProtocol, cache: CacheProtocol) -> None:
        self._db = db
        self._cache = cache

# BEFORE — blocking
async def process():
    response = requests.get(url)     # BLOCKING!
    data = json.load(open(path))     # BLOCKING!
 
# AFTER — async
async def process():
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
    async with aiofiles.open(path) as f:
        data = json.loads(await f.read())

@pytest.mark.asyncio
async def test_get_user_success(mock_repo, service):
    mock_repo.find_by_id.return_value = sample_user
    result = await service.get_user(1)
    assert result == sample_user
 
@pytest.mark.asyncio
async def test_get_user_not_found(mock_repo, service):
    mock_repo.find_by_id.return_value = None
    with pytest.raises(NotFoundError):
        await service.get_user(999)

def create_user(self, data: UserCreate) -> User:
    """Create a new user.
 
    Args:
        data: User creation data.
 
    Returns:
        Created user with assigned ID.
 
    Raises:
        ValidationError: If data fails validation.
        ConflictError: If email exists.
    """

# Format
black src/ tests/
isort src/ tests/
 
# Lint
flake8 src/ tests/
mypy src/ --strict
 
# Test
pytest --cov=src --cov-fail-under=95
 
# Security
bandit -r src/

git commit -m "refactor(models): extract Pydantic v2 models"
git commit -m "refactor(exceptions): implement exception hierarchy"
git commit -m "refactor(services): decompose with DI"
git commit -m "refactor(async): convert I/O to async"
git commit -m "test: add tests for refactored module"
git commit -m "docs: update docstrings and README"

# Feature flag for gradual migration
if config.use_new_models:
    return new_process(NewInput.model_validate(data))
else:
    return legacy_process(data)