from typing import TypeVar, Protocol, overload, runtime_checkable

# Protocol: structural subtyping (like Go interfaces)
@runtime_checkable
class Serializable(Protocol):
    def to_dict(self) -> dict: ...

class User:
    def to_dict(self) -> dict:
        return {"name": self.name}

def serialize(obj: Serializable) -> str:
    return json.dumps(obj.to_dict())
# User satisfies Serializable without inheriting from it

# Overload: different return types based on input
@overload
def fetch(id: str, many: Literal[False] = ...) -> User: ...
@overload
def fetch(id: str, many: Literal[True] = ...) -> list[User]: ...

def fetch(id: str, many: bool = False) -> User | list[User]:
    if many:
        return db.find_all(id)
    return db.find_one(id)

# TypeVar with bounds
T = TypeVar("T", bound="BaseModel")

def create_and_save(model_cls: type[T], data: dict) -> T:
    instance = model_cls(**data)
    instance.save()
    return instance

# PEP 695 (3.12+): no more explicit TypeVar declarations
class Repository[T]:
    def __init__(self) -> None:
        self._items: dict[str, T] = {}

    def get(self, key: str) -> T | None:
        return self._items.get(key)

def first[T](items: list[T]) -> T | None:
    return items[0] if items else None

# Self (3.11+) for fluent builders -- correct even in subclasses
from typing import Self

class QueryBuilder:
    def where(self, cond: str) -> Self:
        self._conditions.append(cond)
        return self

# TypedDict for structured dict payloads at the boundary
from typing import TypedDict, NotRequired

class UserPayload(TypedDict):
    id: str
    email: str
    nickname: NotRequired[str]   # optional key, not Optional value

# Exhaustiveness checking -- the type checker errors if you miss a case
from typing import assert_never

def area(shape: Circle | Square) -> float:
    match shape:
        case Circle(r): return 3.14159 * r * r
        case Square(s): return s * s
        case _: assert_never(shape)  # adding a new shape becomes a type error