Продвинутая типизация: Generic, Protocol, TypedDict

from collections.abc import Sequence

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

name = first(["Анна", "Боря"])     # mypy знает: name — str
num = first((1, 2, 3))             # num — int
print(name.upper(), num + 1, first.__type_params__)

from dataclasses import dataclass

@dataclass
class Page[T]:
    items: list[T]
    page: int
    total: int

    def has_next(self, size: int) -> bool:
        return self.page * size < self.total

@dataclass
class User:
    name: str

page: Page[User] = Page([User("Анна"), User("Боря")], page=1, total=5)
print(page.items[0].name, page.has_next(size=2))
print(Page[int]([1, 2], 1, 2))

from typing import TypedDict, NotRequired, Required

class Address(TypedDict):
    city: str
    street: str

class UserPayload(TypedDict, total=False):     # по умолчанию все ключи необязательны
    id: Required[int]                          # кроме этого
    name: str
    address: Address
    tags: NotRequired[list[str]]

payload: UserPayload = {"id": 1, "name": "Анна", "address": {"city": "Казань", "street": "Баумана"}}
print(payload["address"]["city"], UserPayload.__required_keys__)

import functools, time
from collections.abc import Callable

def timed[**P, R](func: Callable[P, R]) -> Callable[P, R]:   # P — параметры, R — результат
    @functools.wraps(func)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        start = time.perf_counter()
        try:
            return func(*args, **kwargs)
        finally:
            print(f"  {func.__name__}: {(time.perf_counter() - start) * 1000:.2f} мс")
    return wrapper

@timed
def power(base: int, exp: int = 2) -> int:
    return base ** exp

print(power(3, exp=4))      # mypy проверит аргументы: power("3") — ошибка

from enum import Enum
from typing import assert_never, TypeGuard

class Status(Enum):
    NEW = "new"
    PAID = "paid"
    CANCELLED = "cancelled"

def label(status: Status) -> str:
    match status:
        case Status.NEW:
            return "Новый"
        case Status.PAID:
            return "Оплачен"
        case Status.CANCELLED:
            return "Отменён"
        case _:
            assert_never(status)      # добавят Status.REFUNDED — mypy укажет сюда

def is_str_list(values: list[object]) -> TypeGuard[list[str]]:   # своя функция-сужатель
    return all(isinstance(v, str) for v in values)

print([label(s) for s in Status])
print(is_str_list(["a", "b"]), is_str_list(["a", 1]))
# В Python 3.13+ есть более точный TypeIs — он сужает тип и в ветке else.