python-typing

Python Typing Standards

This project maintains STRICT typing standards. NO Any, NO untyped dict/list, NO object unless absolutely necessary.

Core Principles

❌ NEVER Use These

# ❌ BAD - No Any types
def process(data: Any) -> Any:
    pass

# ❌ BAD - No untyped collections
def get_data() -> dict:
    pass

def process_items(items: list) -> None:
    pass

# ❌ BAD - No implicit Any
def transform(callback):  # callback is implicitly Any
    pass

✅ ALWAYS Use These

# ✅ GOOD - Specific types
from typing import Literal
from collections.abc import Callable, Sequence, Mapping
from pydantic import BaseModel

class UserData(BaseModel):
    id: str
    name: str
    age: int

def process(data: UserData) -> UserData:
    pass

# ✅ GOOD - Typed collections (Python 3.10+ syntax)
def get_data() -> dict[str, int]:
    pass

def process_items(items: list[str]) -> None:
    pass

# ✅ GOOD - Typed callbacks
def transform(callback: Callable[[str], int]) -> int:
    pass

Modern Python Syntax (3.10+)

Use Built-in Generics

# ❌ OLD - Don't import from typing
from typing import List, Dict, Tuple, Optional, Union

def process(data: List[str]) -> Dict[str, int]:
    pass

# ✅ NEW - Use built-in types directly
def process(data: list[str]) -> dict[str, int]:
    pass

Use Union Shorthand

# ❌ 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

# ✅ IMPORTANT - Always put None last
result: str | int | None  # ✅ Correct
result: None | str | int  # ❌ Wrong order

Pydantic Models, Not TypedDict, for Structured Data

This project uses Pydantic BaseModel for every tool input/output - not TypedDict. TypedDict gives static-only checking with zero runtime validation; Pydantic validates at the API boundary, where a shape mismatch actually matters. See pydantic-models.mdc for the full inbound/outbound convention (DatadogModel vs ToolResponse/PaginatedListResponse).