# Dataclasses и Pydantic

> dataclasses — модуль стандартной библиотеки Python для лаконичного описания классов-контейнеров данных; Pydantic — библиотека, которая по тем же аннотациям проверяет и преобразует входные данные.

Источник: https://llmdocs.ru/wiki/dataclasses-pydantic/ · обновлено 2026-11-09 · лицензия CC BY-SA 4.0

- **dataclasses**: стандартная библиотека, PEP 557, Python 3.7 (2018)
- **Автор dataclasses**: Эрик Смит
- **Pydantic**: Сэмюэл Колвин, с 2017
- **Pydantic v2**: 2023, ядро pydantic-core на Rust
- **Лицензия Pydantic**: MIT
- **Предшественник и альтернатива**: attrs (2015), msgspec
- **Используют Pydantic**: FastAPI, LangChain, SDK многих API
**dataclasses** — модуль стандартной библиотеки [Python](https://llmdocs.ru/wiki/python.md), который по аннотациям полей автоматически генерирует для класса конструктор `__init__`, строковое представление `__repr__`, сравнение `__eq__` и другие служебные методы. **Pydantic** — сторонняя библиотека, которая по тем же [аннотациям типов](https://llmdocs.ru/wiki/type-hints.md) **проверяет и преобразует данные во время выполнения**: строку `"42"` из [JSON](https://llmdocs.ru/wiki/json.md) превращает в число, а некорректный email отвергает с понятной ошибкой.

Проще говоря, dataclass описывает структуру данных внутри программы, а Pydantic охраняет границу, через которую в программу приходят данные извне: HTTP-запросы, файлы конфигурации, ответы API и языковых моделей.

## dataclasses

Модуль появился в Python 3.7 (PEP 557, 2018); автор — Эрик Смит, вдохновлялся сторонней библиотекой attrs.[1][6]

```python
from dataclasses import dataclass, field

@dataclass(slots=True, kw_only=True)
class Order:
    id: int
    customer: str
    items: list[str] = field(default_factory=list)   # изменяемое значение — только через фабрику
    paid: bool = False

    @property
    def size(self) -> int:
        return len(self.items)

o = Order(id=1, customer="Алиса", items=["книга"])
print(o)                        # Order(id=1, customer='Алиса', items=['книга'], paid=False)
print(o == Order(id=1, customer="Алиса", items=["книга"]))   # True
```

Основные параметры декоратора:[2]

| Параметр | Действие |
|---|---|
| `frozen=True` | неизменяемые экземпляры, пригодные как ключи словаря |
| `slots=True` | `__slots__`: меньше памяти, быстрее доступ к атрибутам (3.10+) |
| `kw_only=True` | все поля только именованными аргументами (3.10+) |
| `order=True` | сравнение `<`, `>` по полям |

Dataclass **не проверяет типы**: `Order(id="один", customer=None)` создастся без ошибок — несоответствие найдёт только статический анализатор ([mypy и pyright](https://llmdocs.ru/wiki/mypy-pyright.md)). Для валидации есть метод `__post_init__`, но для сложных правил удобнее Pydantic.

## Pydantic

Сэмюэл Колвин выпустил Pydantic в 2017 году. Библиотека стала стандартом валидации данных в Python благодаря [FastAPI](https://llmdocs.ru/wiki/fastapi.md), который построил на ней обработку запросов. Pydantic v2 (2023) переписал ядро на [Rust](https://llmdocs.ru/wiki/rust.md) (pydantic-core), ускорив валидацию в разы; при переходе изменилась часть API.[4]

```python
from datetime import datetime
from pydantic import BaseModel, EmailStr, Field, ValidationError

class User(BaseModel):
    id: int
    email: EmailStr                      # требует пакет email-validator
    name: str = Field(min_length=1, max_length=100)
    tags: list[str] = []
    created_at: datetime

data = {"id": "42", "email": "alice@example.com", "name": "Алиса",
        "created_at": "2026-11-09T10:00:00Z"}
user = User.model_validate(data)         # "42" → 42, строка → datetime
print(user.model_dump_json())            # обратно в JSON

try:
    User.model_validate({"id": "x", "email": "нет", "name": "", "created_at": "вчера"})
except ValidationError as e:
    print(e.error_count(), "ошибки")     # все ошибки сразу, с путями к полям
```

Возможности:[3]

- **Приведение типов** в нестрогом режиме и строгий режим, где `"42"` для `int` — ошибка.
- **Валидаторы** полей и моделей (`@field_validator`, `@model_validator`) для своих правил.
- **Вложенные модели**, списки и словари моделей, объединения типов с дискриминатором.
- **JSON Schema** по модели — основа документации OpenAPI в FastAPI и описаний инструментов для языковых моделей (см. [Tool use / function calling](https://llmdocs.ru/wiki/tool-use.md), [Структурированный вывод (JSON mode)](https://llmdocs.ru/wiki/structured-output.md)).
- **Настройки приложения** — пакет pydantic-settings читает конфигурацию из [переменных окружения](https://llmdocs.ru/wiki/environment-variables.md) и файлов `.env` с проверкой типов.[5]
- **Проверка обычных dataclass** — декоратор `pydantic.dataclasses.dataclass` и `TypeAdapter` для любых типов.

## Сравнение

| | dataclasses | Pydantic | attrs |
|---|---|---|---|
| Где | стандартная библиотека | сторонняя | сторонняя |
| Проверка во время выполнения | нет | да, с приведением типов | по желанию (валидаторы) |
| Сериализация в JSON | вручную (`asdict`) | встроена | через cattrs |
| JSON Schema | нет | да | нет |
| Скорость создания объектов | высокая | ниже (идёт проверка) | высокая |
| Типичное применение | внутренние структуры | данные извне, API, конфигурация | внутренние структуры с расширенными возможностями |

Для максимальной скорости сериализации и проверки существует msgspec, а для схем в базе данных — ORM-модели вроде SQLAlchemy или SQLModel (гибрид SQLAlchemy и Pydantic).

## Как выбирать

- Данные создаёт сам код и им можно доверять — **dataclass**: без зависимостей и накладных расходов.
- Данные приходят снаружи — запросы, JSON, YAML, ответы LLM, переменные окружения — **Pydantic** на границе системы; внутрь передаются уже проверенные объекты.
- Не стоит проверять одни и те же данные на каждом слое: валидация на входе, дальше — обычные типизированные объекты.

## См. также

- [Типизация в Python (type hints, PEP 484)](https://llmdocs.ru/wiki/type-hints.md)
- [FastAPI](https://llmdocs.ru/wiki/fastapi.md)
- [mypy и pyright](https://llmdocs.ru/wiki/mypy-pyright.md)
- [JSON](https://llmdocs.ru/wiki/json.md)
- [Декораторы](https://llmdocs.ru/wiki/decorators.md)

## Источники

1. [PEP 557 — Data Classes](https://peps.python.org/pep-0557/)
2. [Python — dataclasses](https://docs.python.org/3/library/dataclasses.html)
3. [Pydantic — документация](https://docs.pydantic.dev/latest/)
4. [Pydantic — Migration Guide (v1 → v2)](https://docs.pydantic.dev/latest/migration/)
5. [Pydantic — Settings Management](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)
6. [attrs — документация](https://www.attrs.org/)