Pydantic

https://pydantic.dev/docs/validation/latest/
Admin
Pydantic is the most widely used data validation library for Python, providing fast and extensible...
Tokens:592,556
Snippets:4,605
Trust Score:9.5
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Run pytest to update documentation examples

Source: https://pydantic.dev/docs/validation/latest/get-started/contributing

Command to run the documentation tests and update code examples. Use this when adding a new code example to ensure it is correct and complete, as Pydantic's unit tests test all documentation code examples.

```bash
# Run tests and update code examples
pytest tests/test_docs.py --update-examples

```

--------------------------------

### Clone repository and install dependencies

Source: https://pydantic.dev/docs/validation/latest/get-started/contributing

Clones your fork of the Pydantic repository, installs uv and pre-commit via pipx, and runs `make install` to set up the environment. Requires Python 3.9-3.12, git, make, and Rust.

```bash
# Clone your fork and cd into the repo directory
git clone git@github.com:<your username>/pydantic.git
cd pydantic

# Install UV and pre-commit
# We use pipx here, for other options see:
# https://docs.astral.sh/uv/getting-started/installation/
# https://pre-commit.com/#install
# To get pipx itself:
# https://pypa.github.io/pipx/
pipx install uv
pipx install pre-commit

# Install pydantic, dependencies, test dependencies and doc dependencies
make install
```

--------------------------------

### Install bump-pydantic

Source: https://pydantic.dev/docs/validation/latest/get-started/migration

Install the bump-pydantic tool from PyPI to help migrate your code.

```bash
pip install bump-pydantic
```

--------------------------------

### Install Logfire SDK and authenticate

Source: https://pydantic.dev/docs/validation/latest/errors/troubleshooting

Install the Logfire SDK and sign in from your project directory. Requires a free Logfire account and a project.

```bash
pip install logfire
logfire auth
```

--------------------------------

### Install pydantic-settings with pip

Source: https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings

Install the pydantic-settings package using pip.

```bash
pip install pydantic-settings
```

--------------------------------

### Install datamodel-code-generator

Source: https://pydantic.dev/docs/validation/latest/integrations/dev-tools/datamodel_code_generator

Installs the datamodel-code-generator library and command-line utility via pip.

```bash
pip install datamodel-code-generator
```

--------------------------------

### Install Pydantic with pip or uv

Source: https://pydantic.dev/docs/validation/latest/get-started/install

Install Pydantic using either pip or uv. Requires Python 3.9+ and pip (or uv) installed.

```bash
pip install pydantic
```

```bash
uv add pydantic
```

--------------------------------

### Example models for next_field

Source: https://pydantic.dev/docs/validation/latest/api/pydantic_settings

Example models used to illustrate how next_field works with nested BaseSettings models.

```python
class SubSubModel(BaseSettings):
    dvals: Dict

class SubModel(BaseSettings):
    vals: list[str]
    sub_sub_model: SubSubModel

class Cfg(BaseSettings):
    sub_model: SubModel
```

--------------------------------

### WrapSerializer example: convert timezones to UTC

Source: https://pydantic.dev/docs/validation/latest/api/pydantic/functional_serializers

Example of a wrap serializer that transforms timezones to UTC while utilizing the existing datetime serialization logic. The handler function is used to get the partial result, which is then modified to convert to UTC. The example shows both model_dump() and model_dump_json() outputs.

```python
from datetime import datetime, timezone
from typing import Annotated, Any

from pydantic import BaseModel, WrapSerializer

class EventDatetime(BaseModel):
    start: datetime
    end: datetime

def convert_to_utc(value: Any, handler, info) -> dict[str, datetime]:
    # Note that `handler` can actually help serialize the `value` for
    # further custom serialization in case it's a subclass.
    partial_result = handler(value, info)
    if info.mode == 'json':
        return {
            k: datetime.fromisoformat(v).astimezone(timezone.utc)
            for k, v in partial_result.items()
        }
    return {k: v.astimezone(timezone.utc) for k, v in partial_result.items()}

UTCEventDatetime = Annotated[EventDatetime, WrapSerializer(convert_to_utc)]

class EventModel(BaseModel):
    event_datetime: UTCEventDatetime

dt = EventDatetime(
    start='2024-01-01T07:00:00-08:00', end='2024-01-03T20:00:00+06:00'
)
event = EventModel(event_datetime=dt)
print(event.model_dump())
'''
{
    'event_datetime': {
        'start': datetime.datetime(
            2024, 1, 1, 15, 0, tzinfo=datetime.timezone.utc
        ),
        'end': datetime.datetime(
            2024, 1, 3, 14, 0, tzinfo=datetime.timezone.utc
        ),
    }
}
'''

print(event.model_dump_json())
'''
{"event_datetime":{"start":"2024-01-01T15:00:00Z","end":"2024-01-03T14:00:00Z"}}
'''
```

--------------------------------

### Build documentation

Source: https://pydantic.dev/docs/validation/latest/get-started/contributing

Builds the documentation with `make docs`. If the imaging plugin causes issues, comment out the `social` plugin line in `mkdocs.yml` and run `make docs` again. Alternatively, use `uv run mkdocs serve` to serve at localhost:8000.

```bash
# Build documentation
make docs
# If you have changed the documentation, make sure it builds successfully.
# You can also use `uv run mkdocs serve` to serve the documentation at localhost:8000
```

--------------------------------

### Print Pydantic version info for issue reports

Source: https://pydantic.dev/docs/validation/latest/get-started/contributing

Run this command in your terminal to get the version information to include in a GitHub issue. It is required unless you cannot install Pydantic or know it is not relevant.

```bash
python -c "import pydantic.version; print(pydantic.version.version_info())"
```

--------------------------------

### Print and format CLI help with CliApp

Source: https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings

Shows how to print or format CLI help using CliApp.print_help and CliApp.format_help. These methods work on both an instance and the class itself. The example sets cli_prog_name='example' and demonstrates the resulting help output.

```python
from pydantic_settings import BaseSettings, CliApp


class Settings(BaseSettings, cli_prog_name='example'):

    def cli_cmd(self) -> None:
        # Will print help for the current command or subcommand instance.
        CliApp.print_help(self)

        # Will return formatted help for the current command or subcommand instance.
        CliApp.format_help(self)


CliApp.run(Settings, cli_args=[])
"""
usage: example [-h]

options:
  -h, --help  show this help message and exit
"""

# You can also print or format help on the class itself.
print(CliApp.format_help(Settings))
"""
usage: example [-h]

options:
  -h, --help  show this help message and exit
"""
```

--------------------------------

### Merging json_schema_extra dictionaries

Source: https://pydantic.dev/docs/validation/latest/concepts/json_schema

Starting in v2.9, json_schema_extra dictionaries from annotated types are merged additively. This example shows merging two dicts from nested Annotated types via TypeAdapter; the output includes both keys.

```python
import json
from typing import Annotated

from typing_extensions import TypeAlias

from pydantic import Field, TypeAdapter

ExternalType: TypeAlias = Annotated[
    int, Field(json_schema_extra={'key1': 'value1'})
]

ta = TypeAdapter(
    Annotated[ExternalType, Field(json_schema_extra={'key2': 'value2'})]
)
print(json.dumps(ta.json_schema(), indent=2))
```

```json
{
  "key1": "value1",
  "key2": "value2",
  "type": "integer"
}
```

--------------------------------

### Pydantic with ARQ job queue example

Source: https://pydantic.dev/docs/validation/latest/examples/queues

Complete ARQ worker and enqueue script. Requires Redis to be installed and running. Defines a Pydantic User model, enqueues two jobs with model_dump(), and processes them with model_validate(). Run as-is to both enqueue and process jobs.

```python
import asyncio
from typing import Any

from arq import create_pool
from arq.connections import RedisSettings

from pydantic import BaseModel, EmailStr


class User(BaseModel):
    id: int
    name: str
    email: EmailStr


REDIS_SETTINGS = RedisSettings()


async def process_user(ctx: dict[str, Any], user_data: dict[str, Any]) -> None:
    user = User.model_validate(user_data)
    print(f'Processing user: {repr(user)}')


async def enqueue_jobs(redis):
    user1 = User(id=1, name='John Doe', email='john@example.com')
    user2 = User(id=2, name='Jane Doe', email='jane@example.com')

    await redis.enqueue_job('process_user', user1.model_dump())
    print(f'Enqueued user: {repr(user1)}')

    await redis.enqueue_job('process_user', user2.model_dump())
    print(f'Enqueued user: {repr(user2)}')


class WorkerSettings:
    functions = [process_user]
    redis_settings = REDIS_SETTINGS


async def main():
    redis = await create_pool(REDIS_SETTINGS)
    await enqueue_jobs(redis)


if __name__ == '__main__':
    asyncio.run(main())
```

--------------------------------

### Flat cli_shortcuts example

Source: https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings

Defines a flat settings model with CLI shortcuts for two fields. Use --option2 to set 'option' and --list_option2 to set 'list_option'.

```python
from pydantic import Field

from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    option: str = Field(default='foo')
    list_option: str = Field(default='fizz')

    model_config = SettingsConfigDict(
        cli_shortcuts={'option': 'option2', 'list_option': ['list_option2']}
    )


# Now you can use the shortcuts on the CLI:
# --option2 sets 'option', --list_option2 sets 'list_option'
```

--------------------------------

### Example .env file

Source: https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings

Example `.env` file showing the typical format for dotenv files. It includes comments, quoted and unquoted values, and demonstrates the general principles of environment variables.

```bash
# ignore comment
ENVIRONMENT="production"
REDIS_ADDRESS=localhost:6379
MEANING_OF_LIFE=42
MY_VAR='Hello world'
```

--------------------------------

### Modify JSON schema with __get_pydantic_json_schema__

Source: https://pydantic.dev/docs/validation/latest/concepts/json_schema

Shows how to implement __get_pydantic_json_schema__ to modify the generated JSON schema. The method calls the handler to get the schema, resolves references, then adds an 'examples' list and sets the title. This only affects the JSON schema, not the core schema used for validation and serialization.

```python
import json
from typing import Any

from pydantic_core import core_schema as cs

from pydantic import GetCoreSchemaHandler, GetJsonSchemaHandler, TypeAdapter
from pydantic.json_schema import JsonSchemaValue


class Person:
    name: str
    age: int

    def __init__(self, name: str, age: int):
        self.name = name
        self.age = age

    @classmethod
    def __get_pydantic_core_schema__(
        cls, source_type: Any, handler: GetCoreSchemaHandler
    ) -> cs.CoreSchema:
        return cs.typed_dict_schema(
            {
                'name': cs.typed_dict_field(cs.str_schema()),
                'age': cs.typed_dict_field(cs.int_schema()),
            },
        )

    @classmethod
    def __get_pydantic_json_schema__(
        cls, core_schema: cs.CoreSchema, handler: GetJsonSchemaHandler
    ) -> JsonSchemaValue:
        json_schema = handler(core_schema)
        json_schema = handler.resolve_ref_schema(json_schema)
        json_schema['examples'] = [
            {
                'name': 'John Doe',
                'age': 25,
            }
        ]
        json_schema['title'] = 'Person'
        return json_schema


print(json.dumps(TypeAdapter(Person).json_schema(), indent=2))
"""
{
  "examples": [
    {
      "age": 25,
      "name": "John Doe"
    }
  ],
  "properties": {
    "name": {
      "title": "Name",
      "type": "string"
    },
    "age": {
      "title": "Age",
      "type": "integer"
    }
  },
  "required": [
    "name",
    "age"
  ],
  "title": "Person",
  "type": "object"
}
"""
```

--------------------------------

### Set default values with assignment or Field(default=...)

Source: https://pydantic.dev/docs/validation/latest/concepts/fields

Provide default values for fields using normal assignment syntax or the `default` argument of `Field`. Both fields in this example are not required. Note that in Pydantic V2, `Any` or `Optional` types no longer get an implicit default of `None`.

```python
from pydantic import BaseModel, Field


class User(BaseModel):
    # Both fields aren't required:
    name: str = 'John Doe'
    age: int = Field(default=20)
```

--------------------------------

### Create a dynamic model with create_model()

Source: https://pydantic.dev/docs/validation/latest/concepts/models

Shows how to create a model dynamically with create_model() using simple field definitions, and the equivalent static class definition.

```python
from pydantic import BaseModel, create_model

DynamicFoobarModel = create_model('DynamicFoobarModel', foo=str, bar=(int, 123))

# Equivalent to:


class StaticFoobarModel(BaseModel):
    foo: str
    bar: int = 123
```

--------------------------------

### Sender script: serialize and publish Pydantic models to RabbitMQ

Source: https://pydantic.dev/docs/validation/latest/examples/queues

Creates a RabbitMQ connection and declares a queue, then defines a function that serializes a Pydantic model to JSON and publishes it. Two example users are pushed, and the output shows the serialized JSON. Requires RabbitMQ installed and running locally.

```python
import pika

from pydantic import BaseModel, EmailStr


class User(BaseModel):
    id: int
    name: str
    email: EmailStr


connection = pika.BlockingConnection(pika.ConnectionParameters('localhost'))
channel = connection.channel()
QUEUE_NAME = 'user_queue'
channel.queue_declare(queue=QUEUE_NAME)


def push_to_queue(user_data: User) -> None:
    serialized_data = user_data.model_dump_json()
    channel.basic_publish(
        exchange='',
        routing_key=QUEUE_NAME,
        body=serialized_data,
    )
    print(f'Added to queue: {serialized_data}')


user1 = User(id=1, name='John Doe', email='john@example.com')
user2 = User(id=2, name='Jane Doe', email='jane@example.com')

push_to_queue(user1)
#> Added to queue: {"id":1,"name":"John Doe","email":"john@example.com"}

push_to_queue(user2)
#> Added to queue: {"id":2,"name":"Jane Doe","email":"jane@example.com"}

connection.close()
```

--------------------------------

### Example debug output for settings sources

Source: https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings

Example DEBUG-level report showing the dictionary collected by every source in priority order (highest first). Sources are merged using a deep update, so higher-priority sources override lower-priority ones, and lower-priority sources may still contribute missing sub-keys for nested structures.

```text
Resolving settings for 'Settings' (sources in priority order, highest first):
  InitSettingsSource: {'port': 9000}
  EnvSettingsSource: {'name': 'from_env'}
  DotEnvSettingsSource: {}
  SecretsSettingsSource: {}
  DefaultSettingsSource: {}
```

--------------------------------

### Using AliasGenerator for validation and serialization aliases

Source: https://pydantic.dev/docs/validation/latest/concepts/alias

Uses AliasGenerator to specify different alias generators for validation (uppercase) and serialization (title case). This is useful when loading and saving data require different naming conventions. The example validates with uppercase keys and dumps with by_alias=True to get title-cased keys.

```python
from pydantic import AliasGenerator, BaseModel, ConfigDict


class Tree(BaseModel):
    model_config = ConfigDict(
        alias_generator=AliasGenerator(
            validation_alias=lambda field_name: field_name.upper(),
            serialization_alias=lambda field_name: field_name.title(),
        )
    )

    age: int
    height: float
    kind: str


t = Tree.model_validate({'AGE': 12, 'HEIGHT': 1.2, 'KIND': 'oak'})
print(t.model_dump(by_alias=True))
#> {'Age': 12, 'Height': 1.2, 'Kind': 'oak'}
```

--------------------------------

### Install Pydantic V2 with pip

Source: https://pydantic.dev/docs/validation/latest/get-started/migration

Installs the latest version of Pydantic V2 from PyPI. Use this command to upgrade an existing installation or install Pydantic V2 for the first time.

```bash
pip install -U pydantic
```

--------------------------------

### Nested cli_shortcuts example

Source: https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings

Defines a nested settings model with CLI shortcuts for nested fields using dot notation. Use --option2 to set nested.option and --twice_nested_option to set nested.twice_nested_option.option.

```python
from pydantic import BaseModel, Field

from pydantic_settings import BaseSettings, SettingsConfigDict


class TwiceNested(BaseModel):
    option: str = Field(default='foo')


class Nested(BaseModel):
    twice_nested_option: TwiceNested = TwiceNested()
    option: str = Field(default='foo')


class Settings(BaseSettings):
    nested: Nested = Nested()
    model_config = SettingsConfigDict(
        cli_shortcuts={
            'nested.option': 'option2',
            'nested.twice_nested_option.option': 'twice_nested_option',
        }
    )


# Now you can use --option2 to set nested.option and --twice_nested_option to set nested.twice_nested_option.option
```

--------------------------------

### Install pydantic for AWS Lambda with pip

Source: https://pydantic.dev/docs/validation/latest/integrations/aws_lambda

Use this command to install pydantic into a local directory for AWS Lambda deployment. The --platform flag should match your Lambda runtime, --target specifies the install directory (often 'python' for Lambda Layers), and --python-version must be compatible with the Lambda runtime. The --only-binary=:all: flag ensures pre-built binary wheels are used, and --upgrade installs the latest pydantic version.

```bash
pip install \
    --platform manylinux2014_x86_64 \  # (1)
    --target=<your_package_dir> \  # (2)
    --implementation cp \  # (3)
    --python-version 3.10 \  # (4)
    --only-binary=:all: \  # (5)
    --upgrade pydantic  # (6)
```

--------------------------------

### Pipeline API example with validate_as and transformations

Source: https://pydantic.dev/docs/validation/latest/concepts/experimental

Shows an exhaustive example of using the pipeline API in a Pydantic model. It demonstrates validation, transformation, constraint, and predicate steps, including combining steps with | and &, using validate_as(...) to infer the field type, and pre/post processing.

```python
from __future__ import annotations

from datetime import datetime
from typing import Annotated

from pydantic import BaseModel
from pydantic.experimental.pipeline import validate_as


class User(BaseModel):
    name: Annotated[str, validate_as(str).str_lower()]  # (1)
    age: Annotated[int, validate_as(int).gt(0)]  # (2)
    username: Annotated[str, validate_as(str).str_pattern(r'[a-z]+')]  # (3)
    password: Annotated[
        str,
        validate_as(str)
        .transform(str.lower)
        .predicate(lambda x: x != 'password'),  # (4)
    ]
    favorite_number: Annotated[  # (5)
        int,
        (validate_as(int) | validate_as(str).str_strip().validate_as(int)).gt(
            0
        ),
    ]
    friends: Annotated[list[User], validate_as(...).len(0, 100)]  # (6)
    bio: Annotated[
        datetime,
        validate_as(int)
        .transform(lambda x: x / 1_000_000)
        .validate_as(...),  # (8)
    ]

```

--------------------------------

### no_info_wrap_validator_function usage example

Source: https://pydantic.dev/docs/validation/latest/api/pydantic-core/pydantic_core_schema

Example of using no_info_wrap_validator_function to create a schema that calls a function with a validator callable. The function appends 'world' to the validated input, and the example asserts the result.

```python
from pydantic_core import SchemaValidator, core_schema

def fn(
    v: str,
    validator: core_schema.ValidatorFunctionWrapHandler,
) -> str:
    return validator(input_value=v) + 'world'

schema = core_schema.no_info_wrap_validator_function(
    function=fn, schema=core_schema.str_schema()
)
v = SchemaValidator(schema)
assert v.validate_python('hello ') == 'hello world'
```

--------------------------------

### Example debug output for file resolution

Source: https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings

Example debug output tracing file resolution, showing which dotenv and secret files were found and loaded. Useful for diagnosing why relative .env paths silently yield defaults when running from a different working directory.

```text
Env file not found, skipping: /home/app/.env.production
Loading env file: /home/app/.env
Secret file not found, skipping: /run/secrets/api_key
```

--------------------------------

### CliApp.format_help

Source: https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings

Returns the formatted help message for the current command or subcommand instance as a string.

```APIDOC
## CliApp.format_help

### Description
Returns the formatted help message for the current command or subcommand instance as a string.

### Method
format_help

### Parameters
- **instance** (type: BaseSettings) - Required - The settings instance for which to format help.

### Returns
- str: The formatted help message.

### Example
```python
CliApp.format_help(self)
```
```

--------------------------------

### Install Pydantic with conda

Source: https://pydantic.dev/docs/validation/latest/get-started/install

Install Pydantic via conda from the conda-forge channel.

```bash
conda install pydantic -c conda-forge
```

--------------------------------

### Create a dynamic model with Field and PrivateAttr

Source: https://pydantic.dev/docs/validation/latest/concepts/models

Advanced example showing field definitions with Field() and PrivateAttr, and the equivalent static model.

```python
from typing import Annotated

from pydantic import BaseModel, Field, PrivateAttr, create_model

DynamicModel = create_model(
    'DynamicModel',
    foo=(str, Field(alias='FOO')),
    bar=Annotated[str, Field(description='Bar field')],
    _private=(int, PrivateAttr(default=1)),
)


class StaticModel(BaseModel):
    foo: str = Field(alias='FOO')
    bar: Annotated[str, Field(description='Bar field')]
    _private: int = PrivateAttr(default=1)
```

--------------------------------

### Namespace management example with a.py and b.py

Source: https://pydantic.dev/docs/validation/latest/api/pydantic/type_adapter

Illustrates a namespace management difference from BaseModel. The forward reference in OuterDict is resolved in the calling module's namespace, not the defining module's, so the example incorrectly succeeds.

```python
IntList = list[int]
OuterDict = dict[str, 'IntList']
```

```python
from a import OuterDict

from pydantic import TypeAdapter

IntList = int  # replaces the symbol the forward reference is looking for
v = TypeAdapter(OuterDict)
v({'x': 1})  # should fail but doesn't
```

--------------------------------

### callable_schema usage example

Source: https://pydantic.dev/docs/validation/latest/api/pydantic-core/pydantic_core_schema

Example usage of callable_schema to validate a callable value (min).

```python
from pydantic_core import SchemaValidator, core_schema

schema = core_schema.callable_schema()
v = SchemaValidator(schema)
v.validate_python(min)
```

--------------------------------

### Run a BaseSettings CLI app with CliApp.run

Source: https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings

Use CliApp.run to parse CLI arguments and execute the model's cli_cmd method after instantiation. The example shows a BaseSettings subclass with a cli_cmd method that prints and updates the parsed data, and then runs the app with cli_args.

```python
from pydantic_settings import BaseSettings, CliApp


class Settings(BaseSettings):
    this_foo: str

    def cli_cmd(self) -> None:
        # Print the parsed data
        print(self.model_dump())
        #> {'this_foo': 'is such a foo'}

        # Update the parsed data showing cli_cmd ran
        self.this_foo = 'ran the foo cli cmd'


s = CliApp.run(Settings, cli_args=['--this_foo', 'is such a foo'])
print(s.model_dump())
#> {'this_foo': 'ran the foo cli cmd'}
```

--------------------------------

### enum_schema usage example

Source: https://pydantic.dev/docs/validation/latest/api/pydantic-core/pydantic_core_schema

Example usage of enum_schema to validate an integer value against an enum class.

```python
from enum import Enum
from pydantic_core import SchemaValidator, core_schema

class Color(Enum):
    RED = 1
    GREEN = 2
    BLUE = 3

schema = core_schema.enum_schema(Color, list(Color.__members__.values()))
v = SchemaValidator(schema)
assert v.validate_python(2) is Color.GREEN
```

--------------------------------

### literal_schema usage example

Source: https://pydantic.dev/docs/validation/latest/api/pydantic-core/pydantic_core_schema

Example usage of literal_schema to validate a value against a list of allowed literals.

```python
from pydantic_core import SchemaValidator, core_schema

schema = core_schema.literal_schema(['hello', 'world'])
v = SchemaValidator(schema)
assert v.validate_python('hello') == 'hello'
```
Tokens:
Raw