pydantic_core

pydantic-core

This package provides the core functionality for pydantic validation and serialization.

Pydantic-core is currently around 17x faster than pydantic V1. See tests/benchmarks/ for details.

Example of direct usage

NOTE: You should not need to use pydantic-core directly; instead, use pydantic, which in turn uses pydantic-core.

from pydantic_core import SchemaValidator, ValidationError


v = SchemaValidator(
    {
        'type': 'typed-dict',
        'fields': {
            'name': {
                'type': 'typed-dict-field',
                'schema': {
                    'type': 'str',
                },
            },
            'age': {
                'type': 'typed-dict-field',
                'schema': {
                    'type': 'int',
                    'ge': 18,
                },
            },
            'is_developer': {
                'type': 'typed-dict-field',
                'schema': {
                    'type': 'default',
                    'schema': {'type': 'bool'},
                    'default': True,
                },
            },
        },
    }
)

r1 = v.validate_python({'name': 'Samuel', 'age': 35})
assert r1 == {'name': 'Samuel', 'age': 35, 'is_developer': True}

# pydantic-core can also validate JSON directly
r2 = v.validate_json('{"name": "Samuel", "age": 35}')
assert r1 == r2

try:
    v.validate_python({'name': 'Samuel', 'age': 11})
except ValidationError as e:
    print(e)
    """
    1 validation error for model
    age
      Input should be greater than or equal to 18
      [type=greater_than_equal, context={ge: 18}, input_value=11, input_type=int]
    """

Getting Started

Prerequisites

You'll need:

• Rust - Rust stable (or nightly for coverage)
• uv - Fast Python package manager (will install Python 3.9+ automatically)
• git - For version control
• make - For running development commands (or use nmake on Windows)

Quick Start

# Clone the repository (or from your fork)
git clone [e-mail]:pydantic/pydantic-core.git
cd pydantic-core

# Install all dependencies using uv, setup pre-commit hooks, and build the development version
make install

Verify your installation by running:

make

This runs a full development cycle: formatting, building, linting, and testing

Development Commands

Run make help to see all available commands, or use these common ones:

make build-dev    # to build the package during development
make build-prod   # to perform an optimised build for benchmarking
make test         # to run the tests
make testcov      # to run the tests and generate a coverage report
make lint         # to run the linter
make format       # to format python and rust code
make all          # to run to run build-dev + format + lint + test

Useful Resources

• python/pydantic_core/_pydantic_core.pyi - Python API types
• python/pydantic_core/core_schema.py - Core schema definitions
• tests/ - Comprehensive usage examples

Profiling

It's possible to profile the code using the flamegraph utility from flamegraph-rs. (Tested on Linux.) You can install this with cargo install flamegraph.

Run make build-profiling to install a release build with debugging symbols included (needed for profiling).

Once that is built, you can profile pytest benchmarks with (e.g.):

flamegraph -- pytest tests/benchmarks/test_micro_benchmarks.py -k test_list_of_ints_core_py --benchmark-enable

The flamegraph command will produce an interactive SVG at flamegraph.svg.

Releasing

• Bump package version locally. Do not just edit Cargo.toml on Github, you need both Cargo.toml and Cargo.lock to be updated.
• Make a PR for the version bump and merge it.
• Go to https://github.com/pydantic/pydantic-core/releases and click "Draft a new release"
• In the "Choose a tag" dropdown enter the new tag v<the.new.version> and select "Create new tag on publish" when the option appears.
• Enter the release title in the form "v<the.new.version> "
• Click Generate release notes button
• Click Publish release
• Go to https://github.com/pydantic/pydantic-core/actions and ensure that all build for release are done successfully.
• Go to https://pypi.org/project/pydantic-core/ and ensure that the latest release is published.
• Done 🎉