BaseModel is the base class for Pydantic models
Pydantic models are simply classes which inherit from BaseModel and define fields as annotated attributes.
Pydantic · API reference · all subjects
basemodel
73 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
BaseModel public members and methods
BaseModel includes the following members and methods: __init__, model_config, model_fields, model_computed_fields, __pydantic_core_schema__, model_extra, model_fields_set, model_construct, model_copy, model_dump, model_dump_json, model_json_schema, model_parametrized_name, model_post_init, model_rebuild, model_validate, model_validate_json, model_validate_strings.
create_model function exists
Pydantic provides a create_model function for dynamically creating Pydantic models.
ConfigDict primary configuration method in V2
ConfigDict is the primary way to configure a Pydantic model in V2. It replaces the V1 approach of using a nested Config class. The config.md API documentation lists ConfigDict as a core configuration component alongside with_config, ExtraValues, and BaseConfig.
Pydantic config module exports
The pydantic.config module exports ConfigDict, with_config, ExtraValues, and BaseConfig. The pydantic.alias_generators module is also part of the public API.
pydantic.fields module contents
The pydantic.fields module exports the following members: Field, FieldInfo, PrivateAttr, ModelPrivateAttr, computed_field, and ComputedFieldInfo. The module documentation filters out internal functions: from_field, from_annotation, from_annotated_attribute, merge_field_infos, rebuild_annotation, and apply_typevars_map.
RootModel class for wrapping root-level types
RootModel is a Pydantic class that allows you to create a model with a single root field. It is used when you want to validate data that is not a dictionary at the top level, such as a list, string, or other primitive type. RootModel inherits from BaseModel and provides a simple way to wrap and validate root-level values.
RootModel generic type parameter
RootModel is a generic class that takes a type parameter specifying the type of the root value. For example, RootModel[list[str]] creates a model that validates a list of strings at the root level.
RootModel.root attribute
RootModel instances have a root attribute that contains the validated root value. When you parse or validate data with RootModel, the result is accessible via the root attribute.
pydantic.__version__ attribute
Pydantic provides a __version__ attribute that contains the version string of the installed Pydantic library.
pydantic.version.version_info attribute
Pydantic provides a version_info attribute in the pydantic.version module that contains detailed version information.
BaseModel.model_validate by_alias parameter
The BaseModel.model_validate() method accepts a `by_alias` parameter that controls whether aliases are used for validation. Default value is True.
BaseModel.model_validate by_name parameter
The BaseModel.model_validate() method accepts a `by_name` parameter that controls whether field names (not aliases) are used for validation. Default value is False.
model_validate by_alias and by_name both True example
from pydantic import BaseModel, Field class Model(BaseModel): my_field: str = Field(validation_alias='my_alias') m = Model.model_validate( {'my_alias': 'foo'}, by_alias=True, by_name=True ) print(repr(m)) #> Model(my_field='foo') m = Model.model_validate( {'my_field': 'foo'}, by_alias=True, by_name=True ) print(repr(m)) #> Model(my_field='foo')
model_validate by_alias and by_name cannot both be False
You cannot set both by_alias and by_name to False in model_validate(). A user error is raised if both are set to False.
BaseModel.model_validate_strings by_alias and by_name parameters
The BaseModel.model_validate_strings() method accepts `by_alias` and `by_name` parameters for controlling alias usage during validation, with the same defaults and behavior as model_validate().
model_dump by_alias parameter example
from pydantic import BaseModel, Field class Model(BaseModel): my_field: str = Field(serialization_alias='my_alias') m = Model(my_field='foo') print(m.model_dump(by_alias=True)) #> {'my_alias': 'foo'}
BaseModel.model_dump_json by_alias parameter
The BaseModel.model_dump_json() method accepts a `by_alias` parameter that controls whether aliases are used for serialization, with the same defaults and behavior as model_dump().
model_validate_json parses JSON strings directly
The BaseModel.model_validate_json method parses JSON data directly from strings. When parsing JSON, Pydantic handles type conversions that JSON does not natively support, such as converting JSON strings to date objects and JSON arrays to tuples.
Partial JSON parsing with model_validate example
To use partial JSON parsing with BaseModel, combine pydantic_core.from_json with allow_partial=True and BaseModel.model_validate. Example: dog = Dog.model_validate(from_json(partial_dog_json, allow_partial=True)).
Partial JSON parsing requires default values on all fields
For partial JSON parsing to work reliably, all fields on the model should have default values to handle missing fields when incomplete JSON is parsed.
JSON parsing allows type coercion even in strict mode
When using model_validate_json with strict=True in ConfigDict, Pydantic still allows JSON-native type conversions (e.g., strings to dates, arrays to tuples) because JSON has no native date or tuple types. However, model_validate will reject these conversions when strict=True is enabled.
BaseModel.model_json_schema method
BaseModel.model_json_schema returns a jsonable dict of a model's JSON schema. It accepts the following parameters: mode (either 'validation' or 'serialization', defaults to 'validation'), by_alias (boolean to use aliases as keys instead of property names, defaults to True), ref_template (string to customize the format of $refs, defaults to '#/$defs/{model}'), and schema_generator (a custom GenerateJsonSchema subclass for custom schema generation).
Model iteration example
from pydantic import BaseModel class BarModel(BaseModel): whatever: int class FooBarModel(BaseModel): banana: float foo: str bar: BarModel m = FooBarModel(banana=3.14, foo='hello', bar={'whatever': 123}) for name, value in m: print(f'{name}: {value}') #> banana: 3.14 #> foo: hello #> bar: whatever=123 print(dict(m)) #> {'banana': 3.14, 'foo': 'hello', 'bar': BarModel(whatever=123)}
model_dump() method signature and parameters
The model_dump() method is used to convert a Pydantic model to a dictionary in Python mode. It accepts the following parameters: by_alias (use serialization aliases for field names), mode (set to 'json' for JSON-compatible types or leave default for Python mode), include (specify which fields to include using a set or dict), exclude (specify which fields to exclude using a set or dict), exclude_defaults (exclude fields equal to default values), exclude_none (exclude None values), exclude_unset (exclude fields not explicitly set during instantiation), context (pass context object for serializers), serialize_as_any (enable duck-typed serialization for all values), and polymorphic_serialization (serialize subclasses with all their fields).
model_dump_json() method signature and parameters
The model_dump_json() method is used to serialize a Pydantic model directly to a JSON-encoded string. It accepts parameters including indent (for pretty-printing), by_alias, mode, include, exclude, exclude_defaults, exclude_none, exclude_unset, context, serialize_as_any, and polymorphic_serialization. It converts Python values to valid JSON data automatically.
model_dump() example with by_alias and mode parameters
from pydantic import BaseModel, Field class BarModel(BaseModel): whatever: tuple[int, ...] class FooBarModel(BaseModel): banana: float | None = 1.1 foo: str = Field(serialization_alias='foo_alias') bar: BarModel m = FooBarModel(banana=3.14, foo='hello', bar={'whatever': (1, 2)}) print(m.model_dump()) #> {'banana': 3.14, 'foo': 'hello', 'bar': {'whatever': (1, 2)}} print(m.model_dump(by_alias=True)) #> {'banana': 3.14, 'foo_alias': 'hello', 'bar': {'whatever': (1, 2)}} print(m.model_dump(mode='json')) #> {'banana': 3.14, 'foo': 'hello', 'bar': {'whatever': [1, 2]}}
model_dump_json() example with indent parameter
from datetime import datetime from pydantic import BaseModel class BarModel(BaseModel): whatever: tuple[int, ...] class FooBarModel(BaseModel): foo: datetime bar: BarModel m = FooBarModel(foo=datetime(2032, 6, 1, 12, 13, 14), bar={'whatever': (1, 2)}) print(m.model_dump_json(indent=2))
Field iteration behavior on BaseModel
Pydantic models can be iterated over, yielding (field_name, field_value) pairs. Field values are left as-is, so nested models are not converted to dictionaries. Calling dict() on a model constructs a dictionary, but nested models remain as model instances, not dictionaries.
model_dump exclude and include parameters
The exclude and include parameters accept either a set of field names or a dict for nested field specification. For nested models, use a dict with field names as keys and True/set/dict as values. The special key '__all__' applies a pattern to all members. exclude takes priority when both field-level and parameter-level exclusion apply.
model_dump exclude with set and dict example
from pydantic import BaseModel, Field, SecretStr class User(BaseModel): id: int username: str password: SecretStr class Transaction(BaseModel): id: str private_id: str = Field(exclude=True) user: User value: int t = Transaction( id='1234567890', private_id='123', user=User(id=42, username='JohnDoe', password='hashedpassword'), value=9876543210, ) # using a set: print(t.model_dump(exclude={'user', 'value'})) #> {'id': '1234567890'} # using a dictionary: print(t.model_dump(exclude={'user': {'username', 'password'}, 'value': True})) #> {'id': '1234567890', 'user': {'id': 42}} # same using include: print(t.model_dump(include={'id': True, 'user': {'id'}})) #> {'id': '1234567890', 'user': {'id': 42}}
Exclude and include with sequence and dictionary indices
Specific items can be excluded or included from sequences and dictionaries using index notation in the exclude/include dict. Negative indices are supported (e.g., -1 for last item). The special key '__all__' applies a pattern to all items.
Exclude sequence items example
from pydantic import BaseModel class Hobby(BaseModel): name: str info: str class User(BaseModel): hobbies: list[Hobby] user = User( hobbies=[ Hobby(name='Programming', info='Writing code and stuff'), Hobby(name='Gaming', info='Hell Yeah!!!'), ], ) print(user.model_dump(exclude={'hobbies': {-1: {'info'}}})) """ { 'hobbies': [ {'name': 'Programming', 'info': 'Writing code and stuff'}, {'name': 'Gaming'}, ] } """ print(user.model_dump(exclude={'hobbies': {'__all__': {'info'}}})) #> {'hobbies': [{'name': 'Programming'}, {'name': 'Gaming'}]}
exclude_defaults serialization parameter
The exclude_defaults parameter to model_dump() and model_dump_json() excludes all fields whose value compares equal to the default value using the equality (==) comparison operator.
exclude_none serialization parameter
The exclude_none parameter to model_dump() and model_dump_json() excludes all fields whose value is None.
exclude_unset serialization parameter
The exclude_unset parameter to model_dump() and model_dump_json() excludes fields that were not explicitly provided during model instantiation. Pydantic tracks explicitly set fields via the model_fields_set property. Modifying a field after instantiation removes it from unset fields.
exclude_unset example with model_fields_set
from pydantic import BaseModel class UserModel(BaseModel): name: str age: int = 18 user = UserModel(name='John') print(user.model_fields_set) #> {'name'} print(user.model_dump(exclude_unset=True)) #> {'name': 'John'} user.age = 21 print(user.model_dump(exclude_unset=True)) #> {'name': 'John', 'age': 21}
Pickling support for Pydantic models
Pydantic models support efficient pickling and unpickling using the standard pickle module. Models can be serialized with pickle.dumps() and deserialized with pickle.loads().
Generic model parametrization not validated against type variable bounds
When parametrizing a model with a concrete type, Pydantic does not validate that the provided type is assignable to the type variable if it has an upper bound.
Unparametrized generic model data loss warning
Validation against an unparametrized generic model can lead to data loss when a subtype of the type variable upper bound, constraints, or default is being used. The resulting type will not be the one provided; instead it will validate against the bound, constraint, or default.
isinstance() with parametrized generics warning
It is not safe to use isinstance() with parametrized generic classes like isinstance(my_model, MyGenericModel[int]). Use isinstance(my_model, MyGenericModel) without the type parameter instead. To check against parametrized generics, create a subclass: class MyIntModel(MyGenericModel[int]): ... then use isinstance(my_model, MyIntModel).
No validation message with model_construct()
model_construct() does not do any validation. It can create models which are invalid. Only use model_construct() with data which has already been validated or that you definitely trust.
Dynamic model pickling requirements
To pickle a dynamically created model using create_model(), the model must be defined globally and the __module__ argument must be provided.
create_model() security warning
create_model() may execute arbitrary code contained in field annotations if string references need to be evaluated. See Python documentation on annotationlib security implications for more information.
Generic model revalidation behavior
When using nested generic models, Pydantic sometimes performs revalidation to produce the most intuitive validation result. If a field has type GenericModel[SomeType] and GenericModel[SomeCompatibleType] is validated against it, Pydantic may revalidate the data. This adds validation overhead but makes results more intuitive.
BaseModel.model_fields attribute
model_fields is a mapping between field names and their definitions (FieldInfo instances). It preserves field order.
BaseModel.model_validate() signature and behavior
model_validate() validates the given object against the Pydantic model. It can accept data as a dictionary, as a model instance (which by default is assumed to be valid, unless revalidate_instances is configured), or arbitrary objects if from_attributes is enabled. It also accepts optional parameters including extra and strict for validation control.
BaseModel.model_validate_json() method
model_validate_json() validates the given JSON data (as JSON string or bytes object) against the Pydantic model. This method is generally considered faster when incoming data is a JSON payload compared to manually parsing the data as a dictionary.
BaseModel.model_dump() method
model_dump() returns a dictionary of the model's fields and values. It provides numerous arguments to customize the serialization result. By default, nested fields are not recursively converted into dictionaries, unlike calling dict() on the instance.
BaseModel.model_dump_json() method
model_dump_json() returns a JSON string representation of model_dump(). It is used for JSON serialization of models.
BaseModel.model_construct() method
model_construct() creates models without running validation. It is useful when working with complex data already known to be valid, or when validators have non-idempotent functions or side effects. It does not perform validation, does not convert dictionaries to model instances for nested fields, respects default values for fields with defaults, populates __pydantic_private__ for private attributes, and does not call any __init__ methods.
BaseModel.model_copy() method
model_copy() allows models to be duplicated with optional updates. It supports a deep parameter: by default it performs shallow copy, but with deep=True it creates new object references for nested models. It is particularly useful when working with frozen models.
BaseModel.model_json_schema() method
model_json_schema() returns a jsonable dictionary representing the model's JSON Schema.
RootModel for custom root types
RootModel is a Pydantic class that allows models to be defined with a custom root type. The root type can be any type supported by Pydantic and is specified by the generic parameter to RootModel. The root value can be passed to __init__ or model_validate() via the first and only argument. The model stores the value in a root attribute.
create_model() function for dynamic model creation
create_model() allows models to be created dynamically using runtime information. Field definitions are specified as keyword arguments: either a single element representing the type annotation, or a two-tuple with the type and default value/Field(). It accepts special keyword arguments __config__ and __base__ to customize the new model, and __validators__ to add validators. As of v2.11, any type can be provided as a single element for field definitions.
Generic models in Pydantic
Pydantic supports generic models using TypeVar for type parameters. Models can inherit from both BaseModel and Generic[T]. When a generic model is parametrized with a concrete type, Pydantic creates subclasses at runtime and caches them. Configuration, validation, and serialization logic set on the generic model apply to parametrized classes. Generic models integrate with type checkers for full type checking support.
BaseModel validation modes
Pydantic can validate data in three different modes: Python mode (used with __init__() and model_validate()), JSON mode (used with model_validate_json()), and strings mode (used with model_validate_strings()). Different modes may have different validation behavior depending on types and model configuration.
model_construct() extra data handling
For models with extra set to 'allow', data not corresponding to fields is correctly stored in __pydantic_extra__ and saved to __dict__. For extra='ignore', data is ignored. For extra='forbid', a call to model_construct() does not raise an error in the presence of extra data; it is simply ignored.
Custom __init__() behavior in Pydantic models
When a custom __init__() is defined on a model, it will be called unconditionally from all validation methods without performing validation. You should call super().__init__(**kwargs) in your implementation. Validation parameters like strictness, extra data behavior, and validation context will be lost with a custom __init__(). Using model_post_init() or field/model validators is recommended instead.
BaseModel.model_extra attribute
model_extra is an attribute that contains the extra fields set during validation. It is only populated when the extra configuration is set to 'allow'.