python

Python Patterns

Iron Law

EXPLICIT IS BETTER THAN IMPLICIT [3]

Type-hint every function signature. Name every exception. Use dataclasses over raw dicts. Python's flexibility is a strength only when boundaries are explicit.

When This Skill Activates

Working with Python codebases, designing typed APIs, modeling data with dataclasses or Pydantic, implementing async code, structuring Python packages.

---

Type Safety

Type Hint Everything [4][17][18]

# BAD: def process(data, config): ...
def process(data: list[dict[str, Any]], config: AppConfig) -> ProcessResult: ...

Dropbox's 4M-line mypy migration eliminated entire bug classes [18]. Use from __future__ import annotations for forward references [22].

Protocols for Structural Typing [5][1]

from typing import Protocol

class Repository(Protocol):
    def find_by_id(self, id: str) -> User | None: ...
    def save(self, entity: User) -> User: ...

PEP 544 formalizes duck typing as "static duck typing" — no implements required [5]. Any class with matching methods satisfies the Protocol [1].

Strict Optional Handling [4][23]

PEP 604 X | Y syntax replaces verbose Optional[X] [23]:

def get_name(user: User | None) -> str:
    return "Anonymous" if user is None else user.name

---

Error Handling [2][8][9]

class AppError(Exception): ...

class NotFoundError(AppError):
    def __init__(self, entity: str, id: str) -> None:
        super().__init__(f"{entity} {id} not found")
        self.entity, self.id = entity, id

@contextmanager
def database_transaction(conn: Connection):
    try:
        yield conn; conn.commit()
    except Exception:
        conn.rollback(); raise

Google Style Guide prohibits bare except: — catches SystemExit [8]. Cosmic Python wraps the unit-of-work in a context manager [9].

---

Data Modeling [6][12][14]

# Internal value objects — frozen enforces immutability [6][14]
@dataclass(frozen=True)
class User:
    name: str
    email: str
    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))

# API boundary models — Pydantic validates on instantiation [12]
class CreateUserRequest(BaseModel):
    name: str
    email: EmailStr
    age: int = Field(ge=0, le=150)