Типизация (type hints)

Аннотации функций

def greet(name: str) -> str:
    return f"Привет, {name}"  # возврат значения

def add(a: int, b: int) -> int:
    return a + b  # возврат значения

def process(data: list[int]) -> dict[str, int]:
    return {str(x): x for x in data}  # возврат значения

Аннотации переменных

name: str = "Анна"
age: int = 30
items: list[int] = [1, 2, 3]
user: dict[str, str | int] = {"name": "Анна", "age": 30}

Базовые типы из typing

from typing import (  # импорт аннотаций типов
    List, Dict, Tuple, Set, Optional, Union, Any,
    Callable, Iterable, Iterator, Sequence, Mapping,
    TypeVar, Generic, Protocol  # структурный протокол
)

# До 3.9: List[int], Dict[str, int]
# С 3.9: list[int], dict[str, int]

# Optional — может быть None
def find_user(id: int) -> Optional[dict]:  # тип может быть None
    ...

# Union — один из типов
def format(value: Union[str, int, float]) -> str:  # объединение типов
    ...

# Union с |
def format(value: str | int | float) -> str:  # 3.10+
    ...

# Any — любой тип
def log(value: Any) -> None: ...

Generic — обобщённые типы

T = TypeVar("T")  # переменная типа

def first(items: list[T]) -> T | None:
    return items[0] if items else None  # возврат значения

# Generic класс
class Stack(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()  # возврат значения

# Использование
stack = Stack[int]()  # присваивание
stack.push(1)
value = stack.pop()  # type: int

Protocol — структурная типизация (3.8+)

from typing import Protocol  # импорт модуля

class Flyable(Protocol):  # структурный протокол
    def fly(self) -> str: ...

class Bird:
    def fly(self) -> str:
        return "Птица летит"  # возврат значения

class Plane:
    def fly(self) -> str:
        return "Самолёт летит"  # возврат значения

def travel(obj: Flyable) -> None:
    print(obj.fly())  # вывод в консоль

travel(Bird())   # OK
travel(Plane())  # OK (duck typing)

Callable — тип функции

from typing import Callable  # импорт модуля

# Функция с int → str
def apply(func: Callable[[int], str], value: int) -> str:  # тип функции
    return func(value)  # возврат значения

# Функция без параметров
def run(callback: Callable[[], None]) -> None:  # тип функции
    callback()

Literal — конкретные значения

from typing import Literal  # импорт модуля

def set_mode(mode: Literal["read", "write", "append"]) -> None:  # литеральный тип (конкретные значения)
    ...

set_mode("read")   # OK
set_mode("delete")

TypedDict — типизированный словарь

from typing import TypedDict  # импорт модуля

class User(TypedDict):  # типизированный словарь
    name: str
    age: int
    email: str | None

user: User = {"name": "Анна", "age": 30, "email": None}

Мой любимый инструмент: mypy

# Установка
pip install mypy

# Запуск
mypy script.py

# mypy находит ошибки типов без запуска кода