type-migration

Type Migration Guide

Systematically migrate Python code to strict typing standards with no Any, no untyped collections, and full type safety.

Migration Strategy

Phase 1: Audit Current State

Run type checker to identify issues:

# Install type checkers
uv add --dev mypy pyright

# Check current state
mypy src/
pyright src/

Create a list of files needing migration, prioritizing:

1. Core utilities (auth, response builders)
2. Tool implementations
3. Server routing layer

Phase 2: Configure Strict Type Checking

Add to pyproject.toml:

[tool.mypy]
python_version = "3.10"
strict = true
warn_return_any = true
warn_unused_ignores = true
disallow_any_generics = true
disallow_untyped_defs = true
disallow_incomplete_defs = true
check_untyped_defs = true
no_implicit_optional = true

[[tool.mypy.overrides]]
module = "datadog_api_client.*"
ignore_missing_imports = true

[tool.pyright]
typeCheckingMode = "strict"
pythonVersion = "3.10"
reportMissingImports = true
reportMissingTypeStubs = false

Phase 3: Systematic Migration

Follow this order for each file:

Step 1: Update Imports

# ❌ OLD - Remove these imports
from typing import List, Dict, Tuple, Optional, Union, Any

# ✅ NEW - Add these if needed
from typing import TypedDict, Literal, Final, TypeAlias, NotRequired
from collections.abc import Sequence, Mapping, Iterable, Callable

Step 2: Replace Legacy Generic Types

# ❌ OLD
def process(items: List[str]) -> Dict[str, int]:
    result: Dict[str, int] = {}
    for item in items:
        result[item] = len(item)
    return result

# ✅ NEW
def process(items: list[str]) -> dict[str, int]:
    result: dict[str, int] = {}
    for item in items:
        result[item] = len(item)
    return result

Step 3: Replace Optional and Union

# ❌ OLD
from typing import Optional, Union

def get_user(user_id: str) -> Optional[User]:
    pass

def parse(value: Union[str, int, float]) -> str:
    pass

# ✅ NEW
def get_user(user_id: str) -> User | None:
    pass

def parse(value: str | int | float) -> str:
    pass