Краткий ответ

В обычном режиме Python аннотации параметров и возвращаемого значения вычисляются при создании объекта функции. Поэтому ссылка на класс, который ещё не объявлен и не представлен доступным именем, обычно вызывает NameError уже при выполнении объявления функции.

Ошибки можно избежать, если использовать строковую аннотацию или включить отложенное хранение аннотаций через from __future__ import annotations. Однако строковая запись откладывает разрешение имени, но не гарантирует, что оно успешно разрешится позже.

Исторический контекст

Аннотации функций появились как универсальное место для метаданных: Python не навязывает им обязательную проверку типов во время выполнения. Это позволило использовать их для статического анализа, документации и библиотек валидации.

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

Постановка проблемы

Класс может ссылаться на другой класс, объявленный ниже по тексту, либо на тип из модуля, который ещё не импортирован. Если аннотация вычисляется немедленно, модуль завершит выполнение с ошибкой и не загрузится.

Отложенная аннотация устраняет ошибку на этапе объявления, но переносит её на момент разрешения типов. Поэтому такая возможность не заменяет корректные импорты и правильную область видимости.

Подробное решение

В обычном режиме выражение аннотации вычисляется в момент выполнения объявления функции, а результат сохраняется в атрибуте __annotations__. Имя класса должно быть доступно в текущем пространстве имён, иначе возникает NameError.

Строковая аннотация не вычисляет имя сразу. Аналогично, from __future__ import annotations заставляет Python сохранять аннотации в отложенном виде, обычно как строки. Это позволяет объявить функцию до класса, на который она ссылается.

from __future__ import annotations

def make_user(user: User) -> User:
    return user

class User:
    pass

print(make_user.__annotations__)

В этом примере объявление функции выполняется до объявления User, потому что аннотация не разрешается немедленно. Для получения фактических объектов типов библиотека typing предоставляет get_type_hints; при вызове он пытается разрешить имена и может завершиться ошибкой, если класс отсутствует или недоступен.

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

Ситуация из практики

В веб-приложении схема ответа ссылается на модель, объявленную ниже в том же модуле. Немедленное вычисление аннотаций приводит к падению импорта приложения.

Можно переставить объявления местами, но это не всегда решает взаимные ссылки между классами. Можно использовать строковые аннотации локально, однако при большом количестве таких ссылок возрастает риск ошибок разрешения имён. Практичным решением становится from __future__ import annotations в модуле с последующей проверкой аннотаций через typing.get_type_hints в точке, где все модели уже импортированы.

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

Что кандидаты часто упускают

Всегда ли аннотация проверяется во время вызова функции?

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

Устраняет ли строковая аннотация проблему отсутствующего класса полностью?

Нет. Она только переносит разрешение имени на более поздний этап. Если typing.get_type_hints или другой инструмент не найдёт класс в доступных пространствах имён, ошибка возникнет тогда.

Почему простая перестановка объявления класса не всегда решает проблему?

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