Типизация переменных: полное руководство по Python Type Hints

Как указать, что переменная может быть None или иметь другой тип?

Используйте Union из модуля typing или оператор | (Python 3.10+). Для краткого обозначения Optional[X] равнозначно Union[X, None].

from typing import Union, Optional

# Python 3.10+
result: int | None = None
# Старый синтаксис
result2: Union[int, None] = None
result3: Optional[int] = None

Как аннотировать список чисел или словарь строк?

Для универсальных контейнеров используйте Generic типы. В Python 3.9+ можно писать list[int], dict[str, float]. В более старых версиях импортируйте List, Dict из typing.

from typing import List, Dict, Tuple

# Python 3.9+
names: list[str] = ["Anna", "Bob"]
stats: dict[str, float] = {"avg": 3.5}
pair: tuple[str, int] = ("key", 42)

# Старый синтаксис
names_old: List[str] = ["Anna"]
stats_old: Dict[str, float] = {"avg": 3.5}

Как создать функцию, работающую с любым типом, но возвращающую тот же тип?

Примените TypeVar – переменную типа, которая связывает тип входа и выхода. Определите одну или несколько таких переменных.

from typing import TypeVar

T = TypeVar('T')

def first(items: list[T]) -> T:
    return items[0]

# Пример использования
first([1, 2, 3])  # mypy выводит int
first(["a", "b"])  # mypy выводит str

Как описать поведение объекта без явного наследования?

Используйте Protocol (структурная типизация). Определите класс, наследующий от Protocol, и перечислите требуемые методы/атрибуты. Любой объект, имеющий их, будет совместим.

from typing import Protocol

class SupportsClose(Protocol):
    def close(self) -> None: ...

def cleanup(obj: SupportsClose) -> None:
    obj.close()

# mypy не выдаст ошибку, если передан объект с методом close
cleanup(open("file.txt"))  # file object has close
cleanup(42)  # ошибка: int не имеет close

Как задать строгие типы для словаря с известными ключами?

Применяйте TypedDict. Определите класс, где каждый ключ аннотирован. По умолчанию все ключи обязательны; для необязательных используйте total=False.

from typing import TypedDict

class Movie(TypedDict):
    title: str
    year: int
    rating: float | None  # Python 3.10+

# Обязательные ключи: title, year; rating может отсутствовать
film: Movie = {"title": "Inception", "year": 2010, "rating": 8.8}

Как ограничить переменную только определёнными литералами?

Тип Literal из модуля typing позволяет указать точные значения (строки, числа, булевы).

from typing import Literal

def open_file(mode: Literal["r", "w", "a"]) -> str:
    # реализация
    return mode

open_file("r")  # OK
open_file("x")  # ошибка mypy: Argument 1 has incompatible type "x"

Как пометить константу, чтобы mypy не разрешал её переопределение?

Примените аннотацию Final. Переменная с ней не может быть переприсвоена (с точки зрения статической проверки).

from typing import Final

MAX_SIZE: Final = 100
# mypy: Final name cannot be reassigned
MAX_SIZE = 200  # ошибка

Как описать разное возвращаемое значение в зависимости от аргументов?

Используйте декоратор @overload. Несколько копий сигнатуры функции, а затем одна реализация без аннотаций типа (или с Any).

from typing import overload

@overload
def parse(data: str) -> dict: ...
@overload
def parse(data: bytes) -> list: ...
def parse(data):
    if isinstance(data, str):
        return {"source": data}
    else:
        return [b for b in data]

Mypy подберёт нужную сигнатуру в зависимости от типа аргумента.

Как добавить типы в код, не используя синтаксис Python 3?

В унаследованных проектах на Python 2 или для обратной совместимости применялись комментарии-аннотации вида # type: тип.

x = 10  # type: int
def greet(name):  # type: (str) -> str
    return "Hello " + name

Современные анализаторы (mypy) всё ещё поддерживают этот стиль с флагом --no-site-packages.