Перейти к содержанию

Валидация Pydantic

CI Покрытие
pypi CondaForge загрузки
лицензия llms.txt

v2.14.3.

Pydantic — самая популярная библиотека для валидации данных в Python.

Быстрая и расширяемая, она отлично сочетается с инструментами статического анализа (линтерами), средами разработки (IDE) и — что немаловажно — интуитивно понятна для самого разработчика. Описывайте структуру данных на стандартном Python 3.11+ и используйте Pydantic для их проверки.

Подпишитесь на нашу рассылку The Pydantic Stack, чтобы получать обновления и руководства по Pydantic, Logfire и Pydantic AI:

Почему стоит использовать Pydantic?

  • На основе подсказок типов (type hints) — в Pydantic проверка схемы и сериализация управляются аннотациями типов. Это означает меньше нового материала для изучения, меньше кода для написания, а также отличную интеграцию с вашей IDE и инструментами статического анализа. Узнать больше…
  • Скорость — основная логика проверки данных в Pydantic написана на языке Rust. Благодаря этому Pydantic является одной из самых быстрых библиотек для проверки данных в Python. Узнать больше…
  • JSON Schema — модели Pydantic могут генерировать JSON Schema, что упрощает их интеграцию с другими инструментами. Узнать больше…
  • Строгий (strict) и гибкий (lax) режимы — Pydantic может работать как в строгом режиме (где данные не преобразуются), так и в гибком режиме, в котором Pydantic при необходимости пытается привести данные к нужному типу. Узнать больше…
  • Dataclasses, TypedDict и многое другое — Pydantic поддерживает проверку множества типов из стандартной библиотеки Python, включая dataclass и TypedDict. Узнать больше…
  • Гибкая настройка — Pydantic позволяет создавать собственные валидаторы и сериализаторы, предоставляя широкие возможности для управления процессом обработки данных. Узнать больше…
  • Экосистема — около 8000 пакетов в репозитории PyPI используют Pydantic, включая такие популярные библиотеки, как FastAPI, huggingface, Django Ninja, SQLModel и LangChain. Узнать больше…
  • Проверено в реальных условиях — Pydantic скачивают более 550 миллионов раз в месяц; его используют все компании группы FAANG, а также 20 из 25 крупнейших компаний, представленных на бирже NASDAQ. Если вы пытаетесь решить какую-то задачу с помощью Pydantic, скорее всего, кто-то другой уже это сделал. Узнать больше…

Установить Pydantic очень просто: выполните команду pip install pydantic.

Примеры использования Pydantic

Чтобы увидеть Pydantic в действии, начнем с простого примера: создадим пользовательский класс, который наследуется от BaseModel:

Validation Successful
from datetime import datetime

from pydantic import BaseModel, PositiveInt


class User(BaseModel):
    id: int  # (1)!
    name: str = 'John Doe'  # (2)!
    signup_ts: datetime | None  # (3)!
    tastes: dict[str, PositiveInt]  # (4)!


external_data = {
    'id': 123,
    'signup_ts': '2019-06-01 12:22',  # (5)!
    'tastes': {
        'wine': 9,
        b'cheese': 7,  # (6)!
        'cabbage': '1',  # (7)!
    },
}

user = User(**external_data)  # (8)!

print(user.id)  # (9)!
#> 123
print(user.model_dump())  # (10)!
"""
{
    'id': 123,
    'name': 'John Doe',
    'signup_ts': datetime.datetime(2019, 6, 1, 12, 22),
    'tastes': {'wine': 9, 'cheese': 7, 'cabbage': 1},
}
"""
  1. Поле id имеет тип int; объявление (даже без присвоения значения) указывает Pydantic, что это поле является обязательным. Если возможно, значения типов str, bytes или float будут приведены к int; в противном случае возникнет исключение.
  2. Поле name — строковое; поскольку для него задано значение по умолчанию, оно не является обязательным.
  3. Поле signup_ts имеет тип [datetime][datetime.datetime] и является обязательным, однако для него допустимо передать значение None. Pydantic может обработать как целое число (Unix-метку времени, например 1496498400), так и строку, представляющую дату и время.
  4. Поле tastes представляет собой словарь, где ключи — строки, а значения — положительные целые числа. Тип PositiveInt — это сокращенная запись для Annotated[int, annotated_types.Gt(0)].
  5. В данном примере входные данные представлены в формате ISO 8601, но Pydantic преобразует их в объект [datetime][datetime.datetime].
  6. Хотя ключ здесь передан как bytes, Pydantic автоматически приведет его к строковому типу.
  7. Аналогичным образом Pydantic преобразует строку '1' в целое число 1.
  8. Мы создаем экземпляр класса User, передавая внешние данные в качестве именованных аргументов (keyword arguments).
  9. Доступ к полям модели можно получить через обращение к их атрибутам.
  10. Модель можно преобразовать в словарь с помощью метода [model_dump()][pydantic.BaseModel.model_dump].

Если проверка (валидация) не проходит, Pydantic вызывает ошибку, содержащую подробное описание того, что именно пошло не так:

Validation Error
# continuing the above example...

from datetime import datetime
from pydantic import BaseModel, PositiveInt, ValidationError


class User(BaseModel):
    id: int
    name: str = 'John Doe'
    signup_ts: datetime | None
    tastes: dict[str, PositiveInt]


external_data = {'id': 'not an int', 'tastes': {}}  # (1)!

try:
    User(**external_data)  # (2)!
except ValidationError as e:
    print(e.errors())
    """
    [
        {
            'type': 'int_parsing',
            'loc': ('id',),
            'msg': 'Input should be a valid integer, unable to parse string as an integer',
            'input': 'not an int',
            'url': 'https://errors.pydantic.dev/2/v/int_parsing',
        },
        {
            'type': 'missing',
            'loc': ('signup_ts',),
            'msg': 'Field required',
            'input': {'id': 'not an int', 'tastes': {}},
            'url': 'https://errors.pydantic.dev/2/v/missing',
        },
    ]
    """
  1. Входные данные здесь некорректны: id не является допустимым целым числом, а поле signup_ts отсутствует.
  2. Попытка создать экземпляр User приведет к возникновению исключения [ValidationError][pydantic_core.ValidationError], содержащего список ошибок.

Кто использует Pydantic?

Pydantic используют сотни организаций, а также множество программных пакетов.

Более полный список проектов с открытым исходным кодом, использующих Pydantic, можно найти в разделе зависимых проектов на GitHub. Кроме того, интересные проекты на базе Pydantic собраны в репозитории awesome-pydantic.