Перейти к содержимому
Учи.Онлайн Выбрать школу
Статья

Pydantic: проверка данных и настройки в Python — модели, ошибки валидации и FastAPI

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

Автор: редакция Учи.ОнлайнОтветственный редактор: Дмитрий Игнатьев
Содержание
Иллюстрация к статье: Pydantic: проверка данных и настройки в Python — модели, ошибки валидации и FastAPI

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. Порядок ниже идёт от того, что вы увидите в первый час, к тому, что понадобится в проекте и в чужом коде.

  1. BaseModel, типы полей, значения по умолчанию, Field.
  2. ValidationError: errors(), путь loc, коды ошибок.
  3. Строгий и нестрогий режим, вложенные модели.
  4. Валидаторы field_validator и model_validator, режимы before и after.
  5. Сериализация: model_dump, exclude, псевдонимы, mode="json".
  6. pydantic-settings и сверка старого кода с руководством по миграции.

Первые пять шагов проходятся за несколько вечеров по документации с проверкой примеров в консоли. В веб-разработке Pydantic почти всегда идёт вместе с FastAPI. На курсе Skillbox «FastAPI» Pydantic прямо назван в стеке рядом с PostgreSQL, SQLAlchemy и pytest, а главный из трёх проектов — API интернет-магазина с авторизацией, тестами и Docker. На входе ждут Python, ООП, асинхронность и SQL.

Открыть курс «Обучение FastAPI»

Упражнения и как проверить себя

Возьмите настоящий файл: выгрузку 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, поэтому его объём стоит уточнить у школы.

Открыть курс «Профессия Фулстек-разработчик 3.0»

Как навык влияет на доход

Отдельной надбавки за Pydantic не бывает: в вакансиях он идёт в стеке вместе с FastAPI, SQLAlchemy и PostgreSQL, а платят за умение сделать и поддерживать сервис целиком. Открытых данных о зарплатах именно по этому навыку найти не удалось: калькулятор зарплат Хабр Карьеры по фильтру «pydantic» в октябре 2026 года показывает цифры только после того, как пользователь добавит свои данные.

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

Как выбрать обучение

Проверьте, есть ли в программе проверка данных и обработка ошибок на практике, а не только строчка в списке технологий: задания с тестами, разбор кода человеком, проект с внешними данными.

Новичку подойдёт онлайн-курс Eduson Academy «Python-разработчик + ИИ»: самостоятельный формат с наставником, восемь месяцев по карточке. FastAPI входит в модуль «Серверная разработка» вместе с Linux, базами данных, асинхронностью и Django, итоговый проект — сервис аренды вещей с экспертной проверкой кода. Pydantic в описании не упомянут, глубину темы уточните у школы.

Открыть курс «Python-разработчик»

Если вы уже пишете на Python для работы, длинная программа избыточна: хватит документации и одного проекта с внешними данными, тестами и настройками.

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