Как обрабатывать forward references и циклические зависимости моделей в Pydantic?

Базовый случай: ссылка на класс, определённый ниже

from __future__ import annotations
from pydantic import BaseModel

class Department(BaseModel):
    name: str
    manager: Employee | None = None  # Employee ещё не определён

class Employee(BaseModel):
    name: str
    department: Department

# После определения обоих классов — обновляем схемы
Department.model_rebuild()
Employee.model_rebuild()

Forward references и циклические зависимости в Pydantic

Forward reference — это строковая аннотация типа, ссылающаяся на класс, который ещё не определён в момент объявления модели. В Python это делается через строку "ClassName" или через from __future__ import annotations. Циклические зависимости возникают когда модель A ссылается на модель B, а B — на A.

Явные строковые аннотации без from __future__

from pydantic import BaseModel
from typing import Optional

class TreeNode(BaseModel):
    value: int
    left: Optional["TreeNode"] = None   # строковая форма
    right: Optional["TreeNode"] = None

TreeNode.model_rebuild()  # разрешить self-reference

root = TreeNode(value=1, left=TreeNode(value=2), right=TreeNode(value=3))
print(root.model_dump())
# {'value': 1, 'left': {'value': 2, 'left': None, 'right': None}, ...}

Настоящие циклические зависимости между двумя модулями

Когда модели в разных файлах ссылаются друг на друга, используйте TYPE_CHECKING:

# models/user.py
from __future__ import annotations
from typing import TYPE_CHECKING
from pydantic import BaseModel

if TYPE_CHECKING:
    from models.post import Post  # только для mypy/pyright, не выполняется в runtime

class User(BaseModel):
    id: int
    name: str
    posts: list[Post] = []  # строка из-за from __future__ import annotations

# models/post.py
from __future__ import annotations
from typing import TYPE_CHECKING
from pydantic import BaseModel

if TYPE_CHECKING:
    from models.user import User

class Post(BaseModel):
    id: int
    title: str
    author: User

# main.py — после импорта обоих модулей
from models.user import User
from models.post import Post

User.model_rebuild()
Post.model_rebuild()

model_rebuild() с явным пространством имён

Если автоматическое разрешение типов не работает, можно передать namespace явно:

from pydantic import BaseModel

class Node(BaseModel):
    value: str
    children: list["Node"] = []

# _types_namespace позволяет указать, где искать 'Node'
Node.model_rebuild(_types_namespace={"Node": Node})

# Проверка: schema должна корректно показывать рекурсию
import json
print(json.dumps(Node.model_json_schema(), indent=2))

Update_forward_refs в Pydantic v1 (legacy)

# Pydantic v1 API
from pydantic import BaseModel

class Category(BaseModel):
    name: str
    subcategories: list["Category"] = []

Category.update_forward_refs()  # v1 эквивалент model_rebuild()

Подводные камни

• Забыть вызвать model_rebuild() — Pydantic не выбросит ошибку при определении класса, но при первом создании экземпляра или при вызове model_json_schema() возникнет PydanticUserError: A non-annotated attribute was detected или NameError.
• from __future__ import annotations меняет ВСЕ аннотации на строки — включая те, где это не нужно. Это влияет на get_type_hints() и может ломать другие инструменты интроспекции.
• TYPE_CHECKING блок не выполняется в runtime — если случайно поместить туда не только импорт, но и логику, она будет недоступна.
• model_rebuild() нужно вызывать после определения ВСЕХ задействованных классов — если вызвать слишком рано, часть форвард-референсов не разрешится.
• Бесконечная рекурсия при сериализации — модели с двунаправленными ссылками (User → Post → User) могут уйти в бесконечный цикл при model_dump(). Используйте model_dump(exclude={"posts": {"__all__": {"author"}}}) или отдельные Response-схемы без обратных ссылок.
• JSON Schema с циклами — Pydantic генерирует $defs для рекурсивных моделей, но некоторые OpenAPI-клиенты не поддерживают $ref на вложенные структуры корректно.
• Миграция v1 → v2 — update_forward_refs() заменяется на model_rebuild(); параметры namespace передаются иначе.

• Описывать forward references только как термин и не показывать механизм на минимальном примере.
• Игнорировать ошибки, пустые данные, конкурентный доступ или границы транзакции.
• Не связывать поведение с официальным контрактом Pydantic и реальной эксплуатацией.

• Объясняет forward references через последовательность действий, а не через набор ключевых слов.
• Приводит короткий кодовый пример или production-сценарий с ожидаемым поведением.
• Называет хотя бы один риск: производительность, безопасность, транзакции, память или сопровождение.
• Умеет обсудить отказ, наблюдаемость и rollback без изменения публичного контракта.