pydantic/pydantic
github.com/pydantic/pydantic ↗ · 791 files · 8.7 MB
Pydantic Validation Data validation using Python type hints.
Overview
Pydantic is a Python library for developers who need to validate application data against type annotations and serialize the resulting objects. At commit 29933d1c8cfc882a7640f4d831b09381b39aa311, Python handles model construction, annotation resolution, customization, and JSON Schema generation, while a bundled Rust/PyO3 package executes validation and serialization. Its public surfaces include BaseModel, TypeAdapter, validated dataclasses, function-call validation, specialized types, and validation instrumentation plugins.
System map
This checkout is a library workspace with Python and native-extension boundaries. The Python package constructs schemas and exposes developer APIs; pydantic-core compiles schema descriptions into Rust validator and serializer objects. Model state belongs to Python instances, while compiled schemas belong to classes or adapters. Packaging, documentation publication, and ecosystem checks are handled by repository tooling and GitHub Actions.
- The package entrypoint checks core compatibility immediately, then lazily resolves public attributes through _dynamic_imports and caches exports from the imported module.
- ModelMetaclass collects configuration and decorators, builds fields, and either installs deferred mocks or calls complete_model_class.
- Core schemas are dictionaries with supported type tags; GenerateSchema produces them, and Rust build_validator_inner dispatches their type to concrete validator builders.
- The _pydantic_core PyO3 module exports SchemaValidator, SchemaSerializer, JSON helpers, URL types, and structured errors; module initialization also exposes build information and the recursion limit.
- The root package requires Python >=3.10, uses Hatchling, and pins pydantic-core==2.49.0; uv resolves that dependency from the local workspace member.
- The core uses Maturin with module name pydantic_core._pydantic_core; Cargo builds cdylib/rlib artifacts with Rust edition 2024 and minimum Rust 1.88.
- The inspected storage boundary is caller-owned: model state consists of __dict__, extras, explicit-field tracking, and private attributes; dumps return values rather than writing application records.
- Makefile defines lint, typecheck, test, benchmark, and documentation commands; tag-gated CI publishes core before Pydantic, while documentation jobs publish dev/latest versions and upload Algolia search data.
Feature catalog
User-facing functionality is exposed through Python APIs rather than application routes or screens. BaseModel and TypeAdapter cover structured and arbitrary typed data, with dedicated wrappers for dataclasses and function calls. Field metadata, custom validators, serializers, and specialized types refine those contracts. JSON Schema export and instrumentation plugins support integration with surrounding developer systems.
- BaseModel supports keyword construction, Python-object validation with optional attribute extraction, and JSON validation; call options include strictness, extra-field behavior, context, and alias/name selection.
- model_dump returns Python data and model_dump_json returns a string; both support inclusion/exclusion, unset/default/None filtering, context, round-trip behavior, fallbacks, and serialization warning policy.
- TypeAdapter builds or reuses a schema for an arbitrary type, validates Python or JSON input, supports experimental partial validation, and returns JSON bytes from dump_json.
- pydantic.dataclasses.dataclass wraps stdlib dataclasses with initialization validation and optional assignment validation; validate_on_init=False is rejected.
- validate_call validates function arguments and optionally return values, preserving wrapper identity and supporting coroutine functions with validation after awaiting their result.
- FieldInfo represents defaults/factories, distinct validation and serialization aliases, exclusions, tagged-union discriminators, frozen fields, and constraints; decorators and Annotated handlers add custom validation and serialization.
- Specialized APIs include root-value models, runtime create_model factories, ImportString resolution, filesystem path checks, masked secret types, and normalized email validation with deliverability checks disabled.
- JSON Schema export supports validation/serialization modes and selectable union representation; plugins receive schema identity and settings plus optional handlers for Python, JSON, and string validation.
Data flow
Type declarations first become field metadata, configuration, and executable core schemas. Validators and serializers retain those schemas while each validation call creates its own execution state. Input mode, aliases, context, and policy overrides travel into the Rust boundary. Results return as Python objects, structured errors, JSON bytes/strings, or JSON Schema dictionaries; persistence remains outside the main validation flow.
- Configuration merges base-class dictionaries, then class-body configuration, then recognized class keyword options; core_config translates selected keys and omits None values.
- Field annotations and metadata enter _common_field_schema, which combines decorator validators, applies discriminator handling, wraps defaults, and installs field serializers.
- complete_model_class generates and cleans the schema, stores __pydantic_core_schema__, and installs a plugin-aware validator plus SchemaSerializer on the class.
- SchemaValidator.py_new builds a validator graph and definitions, retaining the original Python schema/configuration and error-display settings.
- Python validation converts per-call extra behavior and enters _validate; that function creates recursion and ValidationState objects carrying strictness, context, input mode, aliases, and self_instance.
- JSON validation checks the input byte representation, parses it with jiter::JsonValue::parse_with_config, then uses the same validator graph with InputType::Json and converts failures to ValidationError.
- Model field validation returns a dictionary, extras, and fields-set tuple; ModelValidator writes these onto the instance and invokes post-init, with a separate root-model branch.
- Serialization produces JSON bytes and checks warnings before return; BaseModel decodes those bytes, while JSON Schema generation separately traverses the core schema, prunes/remaps definitions, and sorts the resulting dictionary.
Behavior traces
The source traces cover model definition and instantiation, JSON validation and serialization, and validated function invocation end-to-end. They also follow adapter initialization, JSON Schema export, plugin callbacks, and state restoration. Each sequence describes implementation order and material branches rather than an observed execution. Deferred schemas and optional return validation change when parts of these sequences run.
- Import flow: pydantic.__init__ imports version information → _ensure_pydantic_core_version checks compatibility → __getattr__ resolves a requested public symbol → import_module loads and caches exports.
- Model-definition flow: ModelMetaclass.__new__ → ConfigWrapper.for_model/inspect_namespace → DecoratorInfos.build → set_model_fields → complete_model_class → GenerateSchema.generate_schema/clean_schema → validator and serializer installation; defer_build substitutes mocks.
- Instantiation flow: BaseModel.__init__ → validate_python(data, self_instance=self) → SchemaValidator._validate → ModelValidator.validate_init → inner field validation → set_model_attrs → call_post_init.
- JSON round-trip flow: model_validate_json checks alias/name options → SchemaValidator.validate_json checks bytes → _validate_json parses through jiter and validates → model_dump_json calls SchemaSerializer.to_json → to_json_bytes/final warning check → bytes are decoded to str.
- TypeAdapter flow: __init__ captures appropriate function/caller namespaces → _init_core_attrs reuses existing schema objects or generates/cleans new ones → create_schema_validator and SchemaSerializer initialize → validate_python forwards per-call policy and partial-validation options.
- Function-call flow: validate_call → ValidateCallWrapper → _create_validators/GenerateSchema._call_schema → __call__ packages ArgsKwargs → Rust CallValidator validates arguments and invokes the function → optional return validator runs, awaiting coroutine results when necessary.
- JSON Schema flow: BaseModel.model_json_schema → model_json_schema constructs a generator and rebuilds a mocked core schema if necessary → GenerateJsonSchema.generate/generate_inner → definition cleanup/remapping → sorted dictionary; a used generator cannot be reused.
- State-restoration flow: __getstate__ emits instance fields, extras, fields-set, and defined private values → the caller's serialization mechanism carries that state → __setstate__ assigns it directly without invoking validation.
Testing signals
Tests and CI were inspected, not executed; test existence establishes intended coverage, not passing results. The inspected suites use pytest, with separate native-core, documentation, plugin-installation, and static-type integration checks. CI defines platform and interpreter matrices, benchmarks, and downstream compatibility jobs. This inventory is bounded and does not establish exhaustive coverage or current coverage percentages.
- Root pytest configuration targets tests, treats warnings as errors, enables strict configuration, and disables benchmark timing by default; make test invokes coverage-backed pytest with configurable parallel threads.
- Inspected BaseModel tests assert missing-field/error payloads, invalid numeric inputs, Python/JSON dumps, and cyclic-input recursion errors.
- Serialization tests parameterize UUID, IP, secret, temporal, collection, Decimal, enum, and model outputs; core JSON tests assert partial parsing and base64 byte round-trips including invalid encoding.
- Function-call tests inspect preserved wrapper signatures, configuration-driven return validation, coercion in decorated constructors, and asynchronous return-validation failures.
- Plugin tests assert schema identity/settings and JSON success/error callbacks; the mutable installation fixture is marked thread-unsafe, and CI separately installs tests/plugin before running its integration suite.
- Core model tests directly construct SchemaValidator graphs and assert instance dictionaries, extras, and explicit-field tracking; CI defines core pytest and cargo test on Ubuntu, macOS, and Windows.
- Documentation tests discover and execute examples with platform/skip conditions and explicitly skip v1 docstrings; Mypy tests require --test-mypy, while CI separately invokes Pyright, Mypy, and Pyrefly integration targets. Coverage configuration omits deprecated and v1 modules.
- CI defines Python/platform matrices, CodSpeed workloads, scheduled family integration tests, dependency-boundary cases, and conditional downstream FastAPI tests; none supplies an executed result in this investigation.
Risk map
These are source-observed trust boundaries and maintenance hazards, not confirmed vulnerabilities. Validation can intentionally execute application callbacks, resolve annotations, import modules, and load installed plugins. Legacy parsing and filesystem types expose explicit file/input boundaries beyond ordinary in-memory validation. Cross-language schema contracts, cached validators, and output policy have broad effects across public APIs.
- create_model explicitly warns that resolving string annotations may execute arbitrary code; annotation evaluation delegates to version-dependent typing._eval_type using supplied namespaces.
- ImportString routes string values to import_module and optional getattr, including a dotted-path fallback; this field type crosses into module execution rather than merely checking text.
- Plugin discovery loads installed entry points automatically unless disabled; callbacks receive inputs/results/errors, and callback exceptions are not isolated from callers by build_wrapper.
- Deprecated load_file reads the caller-supplied path directly, and load_str_bytes invokes pickle.loads only when pickle is selected and allow_pickle=True; the default rejects pickle decoding.
- PathType validators inspect arbitrary supplied paths using is_file/is_dir/is_socket/exists; they neither constrain paths to a repository root nor reserve a new path after checking it.
- model_construct bypasses validation, including extra='forbid' errors, and model_copy(update=...) applies unvalidated updates; treating either as a fresh input-validation boundary would violate its documented contract.
- Secret wrappers retain recoverable plaintext through get_secret_value and mask JSON output; error input hiding defaults to False, and ordinary validation-error tests include rejected input values.
- Schema compatibility and cache reuse are maintenance hotspots: import checks an exact core version, while forced model rebuilds use a global lock, replace compiled objects with mocks, and disable prebuilt reuse to avoid stale references.
Extension points
Most application extensions attach to public schema hooks, Annotated metadata, decorators, factories, or plugin protocols. JSON Schema generation offers an explicit generator subclass boundary separate from executable-schema generation. Installed validation plugins wrap three input methods without replacing the underlying Rust validator. Adding a native schema kind requires coordination with fixed dispatch and schema definitions.
- Custom types can implement __get_pydantic_core_schema__; GenerateSchema supplies CallbackGetCoreSchemaHandler and normalizes returned definitions/references, while skipping BaseModel's compatibility implementation.
- Annotated handlers such as AfterValidator and PlainSerializer compose a generated inner schema with Python callbacks and, for serializers, an optional generated return schema.
- field_validator and field_serializer register PydanticDescriptorProxy metadata; class construction collects it, and _common_field_schema applies matching field handlers.
- JSON Schema customization uses __get_pydantic_json_schema__ metadata hooks or a GenerateJsonSchema subclass supplied to model_json_schema; schema tags map to named *_schema methods.
- Validation instrumentation plugins register in entry-point group pydantic and implement new_schema_validator, returning optional Python/JSON/string handlers; PYDANTIC_DISABLE_PLUGINS supports global disablement or named exclusions.
- create_model accepts bases, configuration, validators, namespace attributes, and field definitions, checks namespace clashes, and delegates class creation to the resolved metaclass.
- Native validators plug into BuildValidator implementations selected by EXPECTED_TYPE in build_validator_inner; unknown type tags error, and supported executable schema kinds are constrained by the Python/Rust contract.
- The Mypy plugin factory returns PydanticPlugin, whose hooks transform BaseModel subclasses, model metaclasses, from_orm calls, and create_model dynamic classes; configuration data participates in cache invalidation.
Contributor handoff
Start from the schema boundary and trace the specific public API before changing shared internals. Tests and CI were inspected, not executed, so future implementation work must establish its own validation results. The investigation covered selected source, tests, configuration, and every listed workflow entrypoint, but remains a bounded inventory. Keep version coupling, deferred construction, output types, and validation bypasses explicit in acceptance criteria.
- Read architecture.md, ModelMetaclass/complete_model_class, GenerateSchema, and the relevant Rust validator first; executable core schemas and exported JSON Schema are separate contracts.
- Keep Pydantic's compatible-core constant, root dependency pin, and Cargo version synchronized; this checkout declares Pydantic 2.14.0b2 with core 2.49.0.
- Prefer the repository uv workspace and existing Makefile targets; root formatting is Ruff with 120-column lines, single quotes, Python 3.10 targeting, and Google-style docstrings.
- For authorized changes, begin with focused model, serialization, call, or plugin tests; broader existing checks include make test, make lint, and Rust cargo test. These commands and CI were inspected only, not executed here.
- Static typing needs separate checks: Mypy integration is skipped without --test-mypy, and Makefile exposes distinct Mypy-plugin, Pyright, Mypy, and Pyrefly targets.
- Preserve delayed-build and forced-rebuild semantics: unresolved annotations can install mocks, model_rebuild resolves namespaces under a lock, and forced completion prevents reuse of stale compiled objects.
- Acceptance tests should preserve BaseModel JSON str versus TypeAdapter JSON bytes, alias/name validation guards, unvalidated construction/copy updates, and RootModel's rejection of extra configuration.
- Contributor policy targets new features at v2 and requires understanding AI-assisted changes; the assignment workflow closes non-exempt PRs whose referenced closing issues are not assigned to the author, while allowing PRs with no closing references through that check.
Languages
| Language | Files | Share of source |
|---|---|---|
| Python | 453 | 72% |
| Rust | 144 | 23% |
| Markdown | 102 | docs/config |
| YAML | 29 | docs/config |
| TOML | 19 | 3% |
| HTML | 5 | docs/config |
| JavaScript | 5 | 1% |
| Shell | 4 | 1% |
Start reading here
Probable source entrypoint: pyproject.toml — inferred from the directory tree and manifest, not the upstream docs.
Source roots
pydantic/ (107 files)
Repository structure
| Top-level path | Files |
|---|---|
pydantic-core/ | 292 |
tests/ | 229 |
docs/ | 112 |
pydantic/ | 107 |
.github/ | 27 |
.hyperlint/ | 4 |
release/ | 4 |
.agents/ | 1 |
Docs found: CONTRIBUTING.mdREADME.mddocs/api/aliases.mddocs/api/annotated_handlers.mddocs/api/base_model.mddocs/api/config.mddocs/api/dataclasses.mddocs/api/errors.mddocs/api/experimental.mddocs/api/fields.md
Package
pyproject.toml — pydantic, 5 declared dependencies.
emailtimezone#'tzdata;]
CI & config entrypoints
README.md— Repository readme.github/workflows/coverage.yml— GitHub Actions workflow.github/workflows/dependencies-check.yml— GitHub Actions workflow.github/workflows/docs-update.yml— GitHub Actions workflow.github/workflows/integration.yml— GitHub Actions workflow.github/workflows/update-pydantic-people.yml— GitHub Actions workflow.github/workflows/enforce-issue-assignment.yml— GitHub Actions workflow.github/workflows/codspeed.yml— GitHub Actions workflow.github/workflows/upload-previews.yml— GitHub Actions workflow.github/workflows/ci.yml— GitHub Actions workflow
Structural health signals
Average score 6.3/10 across 96 analyzed source files; 64 hotspots surfaced.
pydantic-core/src/serializers/ser.rs— 1346 lines, score 5 (Large file, Deep nesting)pydantic-core/src/input/input_python.rs— 1115 lines, score 5 (Large file, Deep nesting)pydantic-core/src/validators/mod.rs— 956 lines, score 5 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
29933d1c8cfc2026-10-01 — Bump py-cov-action/python-coverage-comment-action from 4.1 to 4.4 (#13916)00ab3d5a2f7c2026-10-01 — Bump pnpm/action-setup from 6.0.9 to 6.1.0 (#13917)24c1cbd3288a2026-10-01 — Bump re-actors/alls-green from 1.2.2 to 1.3.0 (#13915)4944bf39a0802026-10-01 — Bump astral-sh/setup-uv from 10.0.1 to 10.2.0 (#13914)1bde20b3b8242026-10-01 — Bump uraimo/run-on-arch-action from 3.1.0 to 3.2.0 (#13913)