Python: полный мануал с примерами и справочником функций

Глава 18 · средний

Аннотации и typing: описать контракт и проверить данные

Используйте типы для понимания и статической проверки, сохраняя отдельную валидацию реального ввода.

Подсказка о типе и настоящая проверка

Когда функция принимает количество и возвращает итог, аннотация помогает увидеть договорённость сразу: какие значения предполагаются и какой результат ожидается. Редактор или отдельный анализатор может найти несовместимый вызов до выполнения. Но интерпретатор обычно не проверяет эти договорённости автоматически.

Запись def double(value: int) -> int описывает контракт. Если передать строку и тело выполнит value * 2, Python может получить повторённый текст. Аннотация не превратит его в int. Следующий пример намеренно показывает ошибочное использование: статический анализ должен обратить на него внимание, а runtime демонстрирует действительное поведение.

Для входа из формы, файла или сети нужен отдельный парсер и проверка. На этой границе можно превратить строку в число, отвергнуть недопустимое значение и создать объект нужной структуры. После успешной проверки аннотации помогают последующим функциям пользоваться понятным контрактом без повторения одного и того же разбора.

def double(value: int) -> int:
    return value * 2

result = double("4")
print(result)
print(type(result).__name__)

44
str

Контейнеры, объединения и отсутствие значения

В Python 3.9+ стандартные контейнеры можно записывать как list[str] и dict[str, int]. Такая запись описывает элементы, а не проверяет их при append. Для объединения типов с Python 3.10 используется вертикальная черта: int | str. Возможность None обозначают как T | None или Optional[T].

Optional не означает, что аргумент разрешено не передавать. Необязательность вызова определяется наличием default в сигнатуре. Например, value: int | None без значения по умолчанию остаётся обязательным аргументом. Отдельно объясняйте тип значения и форму вызова, чтобы посетитель не смешивал эти правила.

Object означает самый общий объект с доступными общими операциями; анализатор всё равно потребует проверку перед специфичным действием. Any разрешает анализу меньше проверять операции, поэтому большое число Any может спрятать полезные ошибки. Cast сообщает предположение анализатору, а не выполняет преобразование или валидацию. Для строки из файла используйте действительный int(text), если нужен int.

TypedDict описывает структуру словаря

TypedDict подходит для записи с известными именами ключей. Внешне это обычный dict; модель типов объясняет, что у quantity ожидается int, а у title — str. Required и NotRequired позволяют описать обязательность отдельных ключей. Это тоже договорённость статического анализа, а не автоматически запускаемый валидатор.

Проверьте внешние данные перед возвратом TypedDict из функции. Ни наличие ключа, ни isinstance(raw, dict) не подтверждают тип каждого значения. Для количества отдельный вопрос — допустим ли bool, ведь bool является подтипом int. В данном примере требуется обычное неотрицательное целое число, и проверка намеренно использует точный тип.

В Python 3.15 появились возможности TypedDict для описания дополнительных полей, включая typed extra items. Это помогает точнее задать открытость структуры. При этом runtime-парсер всё равно должен решить, игнорирует он неизвестные поля или отвергает их. Поддержка нового правила конкретным анализатором проверяется отдельно от версии интерпретатора.

from typing import TypedDict

class Row(TypedDict):
    title: str
    quantity: int

def parse_row(raw: dict[str, object]) -> Row:
    title = raw.get("title")
    quantity = raw.get("quantity")
    if not isinstance(title, str) or not title.strip():
        raise ValueError("Нужен заголовок")
    if type(quantity) is not int or quantity < 0:
        raise ValueError("Нужно неотрицательное целое количество")
    return {"title": title.strip(), "quantity": quantity}

row = parse_row({"title": " Кабель ", "quantity": 2})
print(row["title"], row["quantity"])
try:
    parse_row({"title": "Кабель", "quantity": True})
except ValueError:
    print("Ввод отклонён")

Кабель 2
Ввод отклонён

Protocol и границы runtime-проверки

Protocol описывает структурное ожидание: объект должен иметь определённые методы и свойства. Подходящий класс может соответствовать ему без явного наследования. Это удобно для функции, которой нужен читающий объект или источник длины; она зависит от требуемого поведения, а не от одной конкретной реализации.

Декоратор runtime_checkable разрешает некоторые проверки isinstance для такого протокола. Они проверяют предусмотренную структуру, а не полную корректность сигнатур и возвращаемых значений. Если объект имеет __len__, но возвращает строку, проверка структуры может пройти, а реальная операция len завершится TypeError.

Для уверенного интерфейса сочетайте описание протокола, статическую проверку и тест реального поведения. Если операция может завершиться неудачей из-за состояния или ввода, продумайте исключение. Protocol не обещает успешное чтение файла, наличие сети или корректный внутренний алгоритм. Эти условия относятся к конкретной реализации и задаче.

from typing import Protocol, runtime_checkable

@runtime_checkable
class HasLength(Protocol):
    def __len__(self) -> int:
        ...

class WrongLength:
    def __len__(self):
        return "два"

print(isinstance([1, 2], HasLength))
value = WrongLength()
print(isinstance(value, HasLength))
try:
    len(value)
except TypeError:
    print("Структура не гарантирует результат")

True
True
Структура не гарантирует результат

Связанные типы и уточнение после условия

Параметр типа помогает связать вход и выход. Например, функция возвращает элемент той же разновидности, что находится в переданной последовательности. Для старого синтаксиса применяют TypeVar и Generic; с Python 3.12 доступно объявление параметров типов прямо у функции или класса. Обычный type alias с ключевым словом type тоже требует 3.12+.

Overload описывает анализатору несколько форм вызова, но реальное тело функции всё равно должно обработать их. Literal задаёт ограниченные значения, а не только широкий тип str. Не стройте сложный набор overload ради функции, чья обычная сигнатура уже ясно показывает поведение.

TypeGuard и TypeIs помогают уточнить тип после пользовательской проверки. TypeGuard обычно уточняет положительную ветвь; TypeIs, появившийся в 3.13, имеет более строгие требования к совместимости и учитывает также отрицательную. Указанная проверка обязана быть правдивой: аннотация предиката не исправит его неверную реализацию.

Python 3.15 добавляет TypeForm для описания значений, представляющих формы типов, и другие расширения статической системы. Такие возможности уместны в библиотеках, работающих с самими описаниями типов. Для первого проекта достаточно ясных входных значений, контейнеров и результата; расширяйте запись, когда новый контракт действительно требует этого.

Отложенные аннотации и интроспекция

В Python 3.14 обычные аннотации стали вычисляться отложенно. Это меняет работу кода, который читает их во время выполнения. Annotationlib предоставляет форматы чтения: значения, представления с незавершёнными ссылками и строки. Выберите формат под задачу, а не рассчитывайте, что любой ещё не объявленный тип уже существует.

В следующем примере имя Missing намеренно не определено. Описание в строковом формате доступно, но запрос действительных значений требует разрешить это имя. Поэтому ошибка возникает при чтении VALUE. Этот пример рассчитан на Python 3.14+, а не на старый интерпретатор, который может остановиться уже при определении функции.

Декоратор или библиотека, которая исследует аннотации, должна учитывать версию и выбранный формат. Получение runtime-значений может выполнять предусмотренную логику оценки выражений. Не считайте содержимое аннотаций автоматически безопасным и уже проверенным внешним набором данных. Для прикладной валидации используйте отдельный явный контракт.

from annotationlib import Format, get_annotations

def convert(value: Missing) -> int:
    return 1

print(sorted(get_annotations(convert, format=Format.STRING)))
try:
    get_annotations(convert, format=Format.VALUE)
except NameError:
    print("Нужно определить Missing")

['return', 'value']
Нужно определить Missing

Попробуйте самостоятельно. Функция получает JSON с quantity. Достаточно ли написать quantity: int или cast(int, value)?