Typing Cheatsheet by Python Version

def greet(name: str, excited: bool = False) -> str:
    return f"Hello {name}{'!' if excited else '.'}"

count: int = 0                    # variable annotation (rarely needed: inference works)
hits: list[str] = []              # needed: empty container has no element type
model_name: str | None = None     # needed: None alone would infer as None

class Settings:
    api_key: str                  # declared, assigned in __init__
    timeout_s: float = 30.0

from collections.abc import Iterable, Iterator, Mapping, MutableMapping, Sequence

def total_tokens(counts: Iterable[int]) -> int:           # any iterable, single pass
    return sum(counts)

def window(xs: Sequence[float], size: int) -> list[list[float]]:   # needs len + indexing
    return [list(xs[i:i + size]) for i in range(0, len(xs), size)]

def merge(base: Mapping[str, object], extra: Mapping[str, object]) -> dict[str, object]:
    return {**base, **extra}

def bump(stats: MutableMapping[str, int], key: str) -> None:       # mutates the argument
    stats[key] = stats.get(key, 0) + 1

# 3.10+
def lookup(doc_id: str, cache: dict[str, str] | None = None) -> str | None: ...

# 3.9 with deferred annotations (annotations only, not runtime expressions)
from __future__ import annotations
def lookup(doc_id: str, cache: dict[str, str] | None = None) -> str | None: ...

# 3.9 without the future import
from typing import Optional, Union
def lookup(doc_id: str, cache: Optional[dict[str, str]] = None) -> Optional[str]: ...
Number = Union[int, float]          # runtime alias: must use Union on 3.9

from collections.abc import Awaitable, Callable

OnToken = Callable[[str], None]                       # one str arg, returns None
Scorer = Callable[[str, str], float]
AnyArgs = Callable[..., str]                          # any arguments
AsyncHandler = Callable[[dict[str, object]], Awaitable[str]]
Factory = Callable[[], "Embedder"]                    # zero args (forward ref in a runtime alias)

from typing import Protocol

class Completion(Protocol):
    def __call__(self, prompt: str, *, max_tokens: int = 256, temperature: float = 0.0) -> str: ...

from enum import StrEnum                 # 3.11
from typing import ClassVar, Final, Literal

Provider = Literal["openai", "anthropic", "local"]
MAX_CONTEXT: Final = 128_000             # inferred Final[int]; reassignment is an error

class Role(StrEnum):
    SYSTEM = "system"
    USER = "user"

class Model:
    registry: ClassVar[dict[str, type["Model"]]] = {}     # class-level, not per instance
    name: str                                              # instance attribute

def set_mode(mode: Literal["chat", "completion"]) -> None: ...
set_mode("chat")          # ok
m = "chat"
set_mode(m)               # pyright: ok (narrowed to Literal["chat"]); mypy: error (m is inferred as str)
M: Final = "chat"
set_mode(M)               # ok in both: Final keeps the literal type

# 3.12+: lazy, supports forward references and type parameters
type JSON = dict[str, JSON] | list[JSON] | str | int | float | bool | None
type Pair[T] = tuple[T, T]

# 3.10–3.11: explicit alias
from typing import TypeAlias
JSON: TypeAlias = "dict[str, JSON] | list[JSON] | str | int | float | bool | None"

# 3.9: implicit alias (any module-level assignment of a type)
from typing import Dict, List, Union
JSON = Union[Dict[str, "JSON"], List["JSON"], str, int, float, bool, None]

# 3.12+
def first[T](items: Sequence[T]) -> T:
    return items[0]

def longest[S: (str, bytes)](a: S, b: S) -> S:          # constrained: S is exactly str or bytes
    return a if len(a) >= len(b) else b

def top_k[N: float](scores: Sequence[N], k: int) -> list[N]:   # bounded: any subtype of float
    return sorted(scores, reverse=True)[:k]

class Cache[K, V]:
    def __init__(self) -> None:
        self._data: dict[K, V] = {}
    def get(self, key: K) -> V | None:
        return self._data.get(key)

# 3.13+: defaults
class Response[T = str]:
    def __init__(self, body: T) -> None:
        self.body = body

# 3.9–3.11
from typing import Generic, TypeVar
T = TypeVar("T")
K = TypeVar("K")
V = TypeVar("V")
N = TypeVar("N", bound=float)
S = TypeVar("S", str, bytes)

class Cache(Generic[K, V]): ...

from dataclasses import dataclass, field
from typing import NamedTuple, NotRequired, ReadOnly, Required, TypedDict

class Usage(TypedDict):
    prompt_tokens: int
    completion_tokens: int

class Message(TypedDict, total=False):      # every key optional...
    role: Required[str]                     # ...except these (3.11)
    content: str

class ToolCall(TypedDict):
    id: ReadOnly[str]                       # 3.13: cannot be assigned through this type
    name: str
    arguments: str
    index: NotRequired[int]                 # 3.11

class Hit(NamedTuple):
    doc_id: str
    score: float

@dataclass(frozen=True, slots=True)         # slots=: 3.10
class Chunk:
    text: str
    source: str
    tags: list[str] = field(default_factory=list)

from collections.abc import AsyncGenerator, AsyncIterable, AsyncIterator, Awaitable, Coroutine

async def complete(prompt: str) -> str: ...                     # annotate the awaited result
# complete is Callable[[str], Coroutine[Any, Any, str]]; calling it gives an awaitable

async def stream(prompt: str) -> AsyncIterator[str]:            # async generator
    for token in prompt.split():
        yield token

async def consume(tokens: AsyncIterable[str]) -> str:
    return "".join([t async for t in tokens])

def schedule(job: Awaitable[str]) -> None: ...                  # accepts coroutines, tasks, futures

from __future__ import annotations

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from numpy.typing import NDArray          # import only for the checker
    import numpy as np

def normalize(v: NDArray[np.float32]) -> NDArray[np.float32]: ...