python-patterns

Python Patterns Skill

Idiomatic Python for production-grade code. Covers modern Python 3.10+ practices.

When to Activate

Activate when:

• Writing new Python modules or packages
• Reviewing Python code for correctness and idiom
• Deciding between data modeling approaches (dataclass vs TypedDict vs Pydantic)
• Designing async services or background workers
• Setting up testing infrastructure

Type Hints

Python's type system (PEP 484, 526, 544) makes code self-documenting and enables static analysis with mypy or pyright.

Basic Annotations

# Variables (PEP 526)
count: int = 0
names: list[str] = []
mapping: dict[str, int] = {}

# Functions — always annotate public API
def greet(name: str, times: int = 1) -> str:
    return (f"Hello, {name}!\n" * times).rstrip()

# Optional and Union (Python 3.10+ union syntax preferred)
def find_user(user_id: int) -> "User | None":
    ...

# Use TypeAlias for reused complex types
type UserId = int          # Python 3.12+
UserId = NewType("UserId", int)  # pre-3.12

Protocols (PEP 544) — Structural Subtyping

Prefer Protocol over ABC when you don't control the implementor.

from typing import Protocol, runtime_checkable

@runtime_checkable
class Serializable(Protocol):
    def to_dict(self) -> dict[str, object]: ...

def save(obj: Serializable) -> None:
    data = obj.to_dict()
    ...

# Any class with to_dict() satisfies Serializable — no inheritance required

Generics

from typing import TypeVar, Generic

T = TypeVar("T")

class Stack(Generic[T]):
    def __init__(self) -> None:
        self._items: list[T] = []

    def push(self, item: T) -> None:
        self._items.append(item)

    def pop(self) -> T:
        return self._items.pop()

Data Modeling: Dataclass vs TypedDict vs Pydantic

Choose based on where the data lives and what guarantees you need.

Dataclass — in-memory objects with behavior

from dataclasses import dataclass, field

@dataclass
class Order:
    id: str
    items: list[str] = field(default_factory=list)
    total: float = 0.0

    def add_item(self, item: str, price: float) -> None:
        self.items.append(item)
        self.total += price

# Use @dataclass(frozen=True) for immutable value objects
@dataclass(frozen=True)
class Money:
    amount: int   # stored in cents
    currency: str = "USD"