Pydantic: проверка данных и настройки в Python — модели, ошибки валидации и FastAPI
Pydantic — библиотека Python, которая проверяет и приводит к нужному виду данные по описанию класса. Вы перечисляете поля модели с аннотациями типов и ограничениями, передаёте словарь или строку JSON, а библиотека возвращает объект с проверенными значениями или исключение ValidationError со списком всех ошибок сразу. На ней построены проверка запросов в FastAPI, чтение настроек из переменных окружения через pydantic-settings и разбор структурированных ответов языковых моделей. Освоить придётся модели и типы, строгий и нестрогий режим, валидаторы, сериализацию и отличия версии 2 от первой.
Содержание

Pydantic часто считают частью FastAPI, но это отдельная библиотека. Она так же полезна в скрипте, который каждую ночь забирает выгрузку партнёра, в конфигурации сервиса или в обработчике ответов нейросети. Без проверки такой код падает в случайном месте с KeyError, а с моделью сразу видно, какое поле в какой строке не подошло и почему.
Что делает Pydantic и когда он не нужен
Работа сводится к трём действиям. Вы описываете данные классом-наследником BaseModel: у каждого поля тип и при необходимости ограничения через Field. Проверяете вход методом model_validate для словаря или model_validate_json для строки JSON. Отдаёте результат дальше через model_dump или model_dump_json. Из той же модели метод model_json_schema строит JSON Schema для коллег или другой программы.
Если данные создаёт ваш же код, проверять их незачем: для простых внутренних структур хватит стандартных dataclasses. Для таблиц на миллионы строк проверка каждой строки отдельным объектом медленна, там удобнее инструменты, работающие со столбцами.
Учебный пример: выгрузка заказов от партнёра
Ситуация учебная. Партнёр присылает заказы списком в JSON, скрипт кладёт их в базу. Телефон в выгрузке бывает со скобками и пробелами. Плохие строки не должны останавливать загрузку: их нужно отложить с объяснением.
from datetime import datetime
from typing import Literal
from pydantic import BaseModel, Field, ValidationError, field_validator
class Order(BaseModel):
order_id: str = Field(pattern=r"^ZK-\d{6}$")
created: datetime
status: Literal["new", "paid", "cancelled"]
qty: int = Field(gt=0)
phone: str
@field_validator("phone")
@classmethod
def digits_only(cls, v: str) -> str:
digits = "".join(ch for ch in v if ch.isdigit())
if len(digits) != 11:
raise ValueError("ожидается 11 цифр")
return digits
good, bad = [], []
for row in rows:
try:
good.append(Order.model_validate(row))
except ValidationError as e:
bad.append({"row": row, "errors": e.errors(include_url=False)})
Строка "2026-10-01T10:00:00" станет объектом datetime, количество "3" — числом 3, а лишнее поле comment по умолчанию будет отброшено. Если в строке два нарушения, исключение перечислит оба: у каждой ошибки есть путь к полю loc, код type, текст и исходное значение. По коду удобно сортировать отказы: missing — поля нет, string_type — пришла не строка.
Что Pydantic преобразует молча, а что отклоняет
По умолчанию работает нестрогий режим: по документации о строгом режиме строка '123' для поля int становится числом 123. Для выгрузок это удобно, для платёжных данных опасно. Строгость включают для одного вызова (model_validate(row, strict=True)), для поля (Field(strict=True), типы StrictInt и StrictStr) или для всей модели через ConfigDict(strict=True). Для JSON строгий режим мягче: дата строкой "2000-01-01" пройдёт строгую проверку в validate_json, но не в validate_python.
Важнее то, что изменилось во второй версии. В руководстве по миграции сказано: превращение int, float и Decimal в строку по умолчанию выключено, а дробное число принимается в поле int, только если дробная часть равна нулю. В первой версии телефон 79161234567, присланный числом, тихо становился строкой, а количество 2.5 — двойкой. Во второй та же выгрузка даст ошибки string_type и int_from_float, причём валидатор digits_only до телефона не дойдёт: он работает после проверки типа. После обновления часть «рабочих» строк начнёт откладываться, хотя партнёр ничего не менял.
Если числа вместо телефонов — известная особенность источника, их разрешают настройкой coerce_numbers_to_str=True или валидатором с mode="before", который получает сырое значение. А дробное количество — скорее всего, настоящая ошибка, которую округление в первой версии скрывало.
Настройки через pydantic-settings
Класс BaseSettings во второй версии вынесен в пакет pydantic-settings. Значения модель берёт из переменных окружения и файла .env:
from pydantic import SecretStr
from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
model_config = SettingsConfigDict(env_prefix="IMPORT_", env_file=".env")
partner_url: str
api_token: SecretStr
statuses: list[str] = ["new", "paid"]
По документации pydantic-settings имена переменных по умолчанию не зависят от регистра, переменные окружения важнее файла .env, а списки передают строкой JSON: IMPORT_STATUSES='["new","paid"]'. Для вложенных моделей задают env_nested_delimiter. SecretStr не покажет токен в логе, значение достаётся вызовом get_secret_value(). Без обязательной переменной приложение упадёт при старте, а не через час на первом запросе.
Переход с версии 1 и ответы нейросетей
Старый код узнаётся по методам: во второй версии parse_obj заменён на model_validate, dict() — на model_dump(), json() — на model_dump_json(), @validator — на @field_validator, класс Config — на атрибут model_config, orm_mode — на from_attributes. Старый интерфейс доступен через pydantic.v1 для постепенного перехода. На странице пакета в PyPI последняя версия — 2.14.1 от 11 октября 2026 года, ветка 2.14 требует Python 3.10 и новее.
Для ответов языковых моделей схема из model_json_schema() подсказывает, какие поля вернуть, а model_validate_json() проверяет, что они вернулись. Список ошибок можно отправить нейросети обратно с просьбой исправить ответ.
С чего начать и в каком порядке осваивать
Нужен уверенный базовый Python: классы, словари, исключения и аннотации типов вроде list[str] и Literal. Порядок ниже идёт от того, что вы увидите в первый час, к тому, что понадобится в проекте и в чужом коде.
BaseModel, типы полей, значения по умолчанию,Field.- ValidationError:
errors(), путьloc, коды ошибок. - Строгий и нестрогий режим, вложенные модели.
- Валидаторы
field_validatorиmodel_validator, режимыbeforeиafter. - Сериализация:
model_dump,exclude, псевдонимы,mode="json". - pydantic-settings и сверка старого кода с руководством по миграции.
Первые пять шагов проходятся за несколько вечеров по документации с проверкой примеров в консоли. В веб-разработке Pydantic почти всегда идёт вместе с FastAPI. На курсе Skillbox «FastAPI» Pydantic прямо назван в стеке рядом с PostgreSQL, SQLAlchemy и pytest, а главный из трёх проектов — API интернет-магазина с авторизацией, тестами и Docker. На входе ждут Python, ООП, асинхронность и SQL.
Упражнения и как проверить себя
Возьмите настоящий файл: выгрузку CRM, ответ внешнего API, конфигурацию скрипта. Опишите его моделью и прогоните все строки. Затем испортите данные: уберите обязательное поле, подставьте строку вместо числа, добавьте дробное количество. Для каждого случая предскажите код ошибки до запуска. Совпало — вы понимаете, что библиотека делает с вашими данными.
Вторая проверка: выгрузите объект через model_dump_json() и загрузите обратно через model_validate_json(). Результат должен совпасть, а если нет, обычно виноваты часовой пояс или псевдоним поля. На каждую ветку валидатора напишите тест на pytest.
Типичные ошибки новичков такие. Считают поле str | None необязательным, хотя во второй версии без значения по умолчанию оно обязательно и лишь допускает None. Пишут валидатор в режиме after и ждут сырое значение. Включают extra="allow", чтобы «не мешало», и пропускают опечатки в именах полей. Ловят ValidationError общим except Exception и теряют список ошибок.
С какими профессиями связан навык
Pydantic ежедневно нужен бэкенд-разработчику на Python. Им пользуются инженеры данных при проверке выгрузок, ML-специалисты, DevOps-инженеры для конфигураций и автотестировщики, сверяющие ответы API с форматом. О FastAPI и о Python для сисадминов на сайте есть отдельные статьи.
Тем, кто идёт в разработку с нуля, подойдёт длинная программа. На курсе Skillbox «Фулстек-разработчик 3.0» есть Python-траектория: ООП, Flask, SQLAlchemy, PostgreSQL, REST API и Docker, затем тестирование, CI/CD, FastAPI и Django, среди работ — серверная часть социальной сети. Pydantic в описании отдельно не назван и, по всей видимости, идёт в составе FastAPI, поэтому его объём стоит уточнить у школы.
Как навык влияет на доход
Отдельной надбавки за Pydantic не бывает: в вакансиях он идёт в стеке вместе с FastAPI, SQLAlchemy и PostgreSQL, а платят за умение сделать и поддерживать сервис целиком. Открытых данных о зарплатах именно по этому навыку найти не удалось: калькулятор зарплат Хабр Карьеры по фильтру «pydantic» в октябре 2026 года показывает цифры только после того, как пользователь добавит свои данные.
Оценивая рынок сами, смотрите медиану, фильтруйте по городу и уровню и отличайте вакансии от анкет с фактической зарплатой. Аналитику или тестировщику навык даёт другое: возможность самому брать задачи по интеграциям, не дожидаясь разработчиков.
Как выбрать обучение
Проверьте, есть ли в программе проверка данных и обработка ошибок на практике, а не только строчка в списке технологий: задания с тестами, разбор кода человеком, проект с внешними данными.
Новичку подойдёт онлайн-курс Eduson Academy «Python-разработчик + ИИ»: самостоятельный формат с наставником, восемь месяцев по карточке. FastAPI входит в модуль «Серверная разработка» вместе с Linux, базами данных, асинхронностью и Django, итоговый проект — сервис аренды вещей с экспертной проверкой кода. Pydantic в описании не упомянут, глубину темы уточните у школы.
Если вы уже пишете на Python для работы, длинная программа избыточна: хватит документации и одного проекта с внешними данными, тестами и настройками.
Сравнить школы по стоимости, практике и поддержке можно в рейтинге онлайн-школ с обучением Python: он охватывает язык целиком, так что программы с Pydantic придётся отбирать по описанию. А до выбора опишите моделью один реальный файл: если вы заранее знаете, какие строки он отклонит и почему, база у вас уже есть.