model_definition

107 notes in this subject, read out of this brain and free to use. This is page 2 of 2.

Handling failed annotation resolution

If a forward reference fails to evaluate during class definition, Pydantic keeps the annotation as a string (unevaluated) so the model can be rebuilt at a later stage. This allows classes to be defined even when not all referenced types are available yet.

Forward references and postponed annotation evaluation

Forward references are used to avoid NameError when a type is not yet defined at the time of annotation. With `from __future__ import annotations` (PEP 563), type hints are stringified by default, making all annotations behave like forward references. When this future import is active, annotations become strings equivalent to wrapping them in quotes.

Limitation: class dict includes dunder attributes

The locals of the current class may include irrelevant entries such as dunder attributes. This means an annotation like `f: '__doc__'` will unexpectedly resolve to the class's __doc__ attribute rather than failing. This is a backwards compatibility concern with the namespace resolution logic.

Experimental features naming conventions

Pydantic indicates experimental features using two naming conventions: features located in the pydantic.experimental module, or features in the main module prefixed with experimental_.

Python version support policy

Pydantic will drop support for a Python version when that version reaches its expected end of life and less than 5% of downloads of the most recent minor release are using that version.

V3 pydantic-core integration

In Pydantic V3, pydantic-core is expected to be merged as an internal sub-module of Pydantic and will no longer be published as a standalone library.

V1 support and maintenance

Active development of Pydantic V1 has stopped. Critical bug fixes and security vulnerabilities will be fixed in V1 until the release of Pydantic V3.

V2 breaking changes policy

Pydantic V2 will not intentionally make breaking changes in minor releases. Functionality marked as deprecated will not be removed until the next major V3 release.

Experimental features lifecycle and stability

Experimental features are active works in progress and may have unstable APIs and behaviors that change without backward compatibility. They are subject to removal with little notice if unsuccessful. When successful, they are promoted to main Pydantic: if from the experimental module, the feature is cloned to main Pydantic with a deprecation warning on the experimental version; if already in main with experimental_ prefix, a non-prefixed copy is created and the experimental version is deprecated.

V1 to V2 migration - breaking changes

The transition from Pydantic V1 to V2 involved significant breaking changes to correct design mistakes. There will not be another breaking change of this magnitude in future versions.

Type hints with BaseModel example

Example showing Pydantic validation using only type hints: from typing import Annotated, Literal from annotated_types import Gt from pydantic import BaseModel class Fruit(BaseModel): name: str color: Literal['red', 'green'] weight: Annotated[float, Gt(0)] bazam: dict[str, list[tuple[int, bool, float]]] print( Fruit( name='Apple', color='red', weight=4.2, bazam={'foobar': [(1, True, 0.1)]}, ) ) #> name='Apple' color='red' weight=4.2 bazam={'foobar': [(1, True, 0.1)]}

Pydantic core validation implemented in Rust

Pydantic's core validation logic is implemented in a separate package called pydantic-core, where validation for most types is implemented in Rust. This makes Pydantic among the fastest data validation libraries for Python.

Type hints define Pydantic schema validation

Pydantic uses Python type hints to define the schema that it validates against. Type hints integrate well with static typing tools like mypy and Pyright, and IDEs like PyCharm and VSCode.

model_config is inherited when subclassing models

In Pydantic V2, the `model_config` attribute is inherited when subclassing a model. If inheriting from multiple BaseModel subclasses, non-default settings are merged, with settings from the rightmost parent overriding those from the left.

Removed config settings in V2

The following config settings have been removed in Pydantic V2: `allow_mutation`, `error_msg_templates`, `fields`, `getter_dict`, `smart_union`, `underscore_attrs_are_private`, `json_loads`, `json_dumps`, `copy_on_model_validation`, `post_init_call`.

Renamed config settings in V2

The following config settings have been renamed in Pydantic V2: `allow_population_by_field_name` → `populate_by_name` (or `validate_by_name` starting in v2.11), `anystr_lower` → `str_to_lower`, `anystr_strip_whitespace` → `str_strip_whitespace`, `anystr_upper` → `str_to_upper`, `keep_untouched` → `ignored_types`, `max_anystr_length` → `str_max_length`, `min_anystr_length` → `str_min_length`, `orm_mode` → `from_attributes`, `schema_extra` → `json_schema_extra`, `validate_all` → `validate_default`.

TypeAdapter for non-BaseModel types

In Pydantic V2, use the `TypeAdapter` class to validate, serialize, and generate JSON schemas for arbitrary types (non-`BaseModel`). This replaces `parse_obj_as` and `schema_of` functions from V1, which are now deprecated.

JSON schema for Optional indicates null is allowed

In Pydantic V2, the JSON schema for `Optional` fields now indicates that the value `null` is allowed.

JSON schema targets draft 2020-12 by default

In Pydantic V2, the JSON schema generated by default targets draft 2020-12 with some OpenAPI extensions.

JSON schema can distinguish input vs output serialization

In Pydantic V2, you can specify whether the JSON schema should represent the inputs to validation or the outputs from serialization.

GenerateJsonSchema class for customizing JSON schema

In Pydantic V2, use the `GenerateJsonSchema` class to customize JSON schema generation. Methods like `BaseModel.model_json_schema()` and `TypeAdapter.json_schema()` accept a `schema_generator` parameter to pass a custom subclass.

BaseSettings moved to pydantic-settings package

In Pydantic V2, `BaseSettings` has been moved to a separate package, `pydantic-settings`. The `parse_env_var` classmethod has been removed; customize settings sources instead.

Mypy plugin configuration for Pydantic V2

Pydantic V2 contains a mypy plugin at `pydantic.mypy`. Configure it in `mypy.ini` or `pyproject.toml` by adding to the plugins list. If using V1 features, also add `pydantic.v1.mypy`.

Install pydantic V2 from PyPI

To install Pydantic V2, use: `pip install -U pydantic`.

bump-pydantic tool for code migration

The `bump-pydantic` tool helps migrate code from Pydantic V1 to V2. Install with `pip install bump-pydantic` and run from the repo root with the target package path: `bump-pydantic my_package`.

Migrate V1 imports to pydantic.v1 namespace

To migrate code using V1 features in a V1/V2 environment with `pydantic>=1.10.17`: replace `pydantic<2` with `pydantic>=1.10.17`, then find and replace all `from pydantic.<module> import <object>` with `from pydantic.v1.<module> import <object>`.

Using Pydantic V1 features via pydantic.v1 namespace

Pydantic V2 provides access to V1 API through `pydantic.v1` imports. For example, `from pydantic.v1 import BaseModel` or `from pydantic.v1.utils import lenient_isinstance`. As of `pydantic>=1.10.17`, this namespace is also available in V1.

Module identity differs for pydantic.v1 imports

When importing using `pydantic>=1.10.17` with the `.v1` namespace, the modules themselves are not identical (`pydantic.v1.fields is not pydantic.fields`), but the symbols imported are the same (`pydantic.v1.fields.ModelField is pydantic.fields.ModelField`).

BaseModel method name changes from V1 to V2

Pydantic V2 renamed various BaseModel methods to follow either `model_.*` or `__.*pydantic.*__` naming patterns. The following V1 methods have been renamed: `__fields__` → `model_fields`, `__private_attributes__` → `__pydantic_private__`, `__validators__` → `__pydantic_validator__`, `construct()` → `model_construct()`, `copy()` → `model_copy()`, `dict()` → `model_dump()`, `json_schema()` → `model_json_schema()`, `json()` → `model_dump_json()`, `parse_obj()` → `model_validate()`, `update_forward_refs()` → `model_rebuild()`.

Deprecated data-loading methods parse_raw and parse_file

The `parse_raw` and `parse_file` methods are now deprecated in Pydantic V2. The `model_validate_json` method works like the old `parse_raw`. For `parse_file`, you should load the data first and then pass it to `model_validate`.

from_orm method deprecated, use model_validate with from_attributes

The `from_orm` method has been deprecated in Pydantic V2. Use `model_validate` instead (equivalent to `parse_obj` from V1), with `from_attributes=True` set in the model config.

BaseModel equality changes in V2

In Pydantic V2, the `__eq__` method has changed for models. Models can only be equal to other BaseModel instances. For two model instances to be equal, they must have the same: type (or non-parametrized generic origin type for generic models), field values, extra values (only when `model_config['extra'] == 'allow'`), and private attribute values. Models are no longer equal to dicts containing their data. Non-generic models of different types are never equal. Generic models with different origin types are never equal.

RootModel replaces root field

Pydantic V2 replaces the `__root__` field for specifying a custom root model with a new type called `RootModel`. Note that `RootModel` types no longer support the `arbitrary_types_allowed` config setting.

New serialization decorators: @field_serializer, @model_serializer, @computed_field

Pydantic V2 has added three new decorators for customizing serialization: `@field_serializer`, `@model_serializer`, and `@computed_field`. These address shortcomings from Pydantic V1 and provide more flexibility than the deprecated `json_encoders` config option, which is now deprecated due to performance overhead and implementation complexity.

Subclass serialization behavior change

In Pydantic V2, when dumping a model with nested subclass fields, only fields defined on the annotated type of the field are included, not all fields from the subclass instance. This is different from V1 which included all subclass fields. This change helps prevent accidental security bugs.

Constructor arguments may be copied for validation

In Pydantic V2, arguments passed to the constructor may be copied in order to perform validation and coercion. This is particularly notable when passing mutable objects as arguments to a constructor.

json() method deprecated, use model_dump_json()

The `.json()` method is deprecated in Pydantic V2. Attempting to use this method with arguments such as `indent` or `ensure_ascii` may lead to confusing errors. Switch to `model_dump_json()` instead.

JSON serialization of non-string keys uses str(key)

In Pydantic V2, JSON serialization of non-string key values is done with `str(key)`. For example, a key of `None` serializes to the string `"None"` in V2, whereas in V1 it serialized to `"null"`.

model_dump_json() output is compacted

In Pydantic V2, `model_dump_json()` results are compacted to save space and may not exactly match `json.dumps()` output. You can use `json.dumps(model.model_dump(), separators=(',', ':'))` to align the outputs.

GenericModel removed, use BaseModel with Generic directly

The `pydantic.generics.GenericModel` class has been removed in Pydantic V2. Create generic `BaseModel` subclasses by adding `Generic` as a parent class directly: `class MyGenericModel(BaseModel, Generic[T]): ...`.

Avoid parametrized generics in isinstance checks

In Pydantic V2, do not use parametrized generics in `isinstance` checks. For example, do not do `isinstance(my_model, MyGenericModel[int])`. Use `isinstance(my_model, MyGenericModel)` instead. If needed to check against parametrized generics, subclass the parametrized generic: `class MyIntModel(MyGenericModel[int]): ...` and then check `isinstance(my_model, MyIntModel)`.

Dataclasses no longer accept tuples as validation input

In Pydantic V2, when used as fields, dataclasses (Pydantic or vanilla) no longer accept tuples as validation inputs. Dicts should be used instead.

__post_init__ called after validation in Pydantic dataclasses

In Pydantic V2, the `__post_init__` method in Pydantic dataclasses is called after validation, not before. As a result, the `__post_init_post_parse__` method has been removed.

Pydantic dataclasses no longer support extra='allow'

Pydantic V2 no longer supports `extra='allow'` for Pydantic dataclasses, which would store extra fields as attributes. `extra='ignore'` is still supported to ignore unexpected fields without storing them.

Pydantic dataclasses no longer have __pydantic_model__

In Pydantic V2, Pydantic dataclasses no longer have an `__pydantic_model__` attribute and no longer use an underlying `BaseModel` for validation. To validate, generate JSON schema, or use other functionality, wrap the dataclass with `TypeAdapter` and use its methods.

Vanilla dataclass config no longer inherited from parent

In Pydantic V1, a vanilla (non-Pydantic) dataclass field would use the parent type's config. In Pydantic V2, this no longer happens. To override config for a vanilla dataclass, use the `config` parameter on the `@dataclass` decorator.

model_config class attribute replaces Config class

In Pydantic V2, to specify config on a model, set a class attribute called `model_config` to a dict with key/value pairs. The Pydantic V1 behavior of creating a nested `Config` class is now deprecated.

Give your agent this brain