Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/pydantic/config.py: 89%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""Configuration for Pydantic models."""
3from __future__ import annotations as _annotations
5import warnings
6from re import Pattern
7from typing import TYPE_CHECKING, Any, Callable, Literal, TypeVar, Union, cast, overload
9from typing_extensions import TypeAlias, TypedDict, Unpack, deprecated
11from ._migration import getattr_migration
12from .aliases import AliasGenerator
13from .errors import PydanticUserError
14from .warnings import PydanticDeprecatedSince211
16if TYPE_CHECKING:
17 from ._internal._generate_schema import GenerateSchema as _GenerateSchema
18 from .fields import ComputedFieldInfo, FieldInfo
20__all__ = ('ConfigDict', 'with_config')
23JsonValue: TypeAlias = Union[int, float, str, bool, None, list['JsonValue'], 'JsonDict']
24JsonDict: TypeAlias = dict[str, JsonValue]
26JsonEncoder = Callable[[Any], Any]
28JsonSchemaExtraCallable: TypeAlias = Union[
29 Callable[[JsonDict], None],
30 Callable[[JsonDict, type[Any]], None],
31]
33ExtraValues = Literal['allow', 'ignore', 'forbid']
36class ConfigDict(TypedDict, total=False):
37 """A TypedDict for configuring Pydantic behaviour."""
39 title: str | None
40 """The title for the generated JSON schema, defaults to the model's name"""
42 model_title_generator: Callable[[type], str] | None
43 """A callable that takes a model class and returns the title for it. Defaults to `None`."""
45 field_title_generator: Callable[[str, FieldInfo | ComputedFieldInfo], str] | None
46 """A callable that takes a field's name and info and returns title for it. Defaults to `None`."""
48 str_to_lower: bool
49 """Whether to convert all characters to lowercase for str types. Defaults to `False`."""
51 str_to_upper: bool
52 """Whether to convert all characters to uppercase for str types. Defaults to `False`."""
54 str_strip_whitespace: bool
55 """Whether to strip leading and trailing whitespace for str types."""
57 str_min_length: int
58 """The minimum length for str types. Defaults to `None`."""
60 str_max_length: int | None
61 """The maximum length for str types. Defaults to `None`."""
63 extra: ExtraValues | None
64 '''
65 Whether to ignore, allow, or forbid extra data during model initialization. Defaults to `'ignore'`.
67 Three configuration values are available:
69 - `'ignore'`: Providing extra data is ignored (the default):
70 ```python
71 from pydantic import BaseModel, ConfigDict
73 class User(BaseModel):
74 model_config = ConfigDict(extra='ignore') # (1)!
76 name: str
78 user = User(name='John Doe', age=20) # (2)!
79 print(user)
80 #> name='John Doe'
81 ```
83 1. This is the default behaviour.
84 2. The `age` argument is ignored.
86 - `'forbid'`: Providing extra data is not permitted, and a [`ValidationError`][pydantic_core.ValidationError]
87 will be raised if this is the case:
88 ```python
89 from pydantic import BaseModel, ConfigDict, ValidationError
92 class Model(BaseModel):
93 x: int
95 model_config = ConfigDict(extra='forbid')
98 try:
99 Model(x=1, y='a')
100 except ValidationError as exc:
101 print(exc)
102 """
103 1 validation error for Model
104 y
105 Extra inputs are not permitted [type=extra_forbidden, input_value='a', input_type=str]
106 """
107 ```
109 - `'allow'`: Providing extra data is allowed and stored in the `__pydantic_extra__` dictionary attribute:
110 ```python
111 from pydantic import BaseModel, ConfigDict
114 class Model(BaseModel):
115 x: int
117 model_config = ConfigDict(extra='allow')
120 m = Model(x=1, y='a')
121 assert m.__pydantic_extra__ == {'y': 'a'}
122 ```
123 By default, no validation will be applied to these extra items, but you can set a type for the values by overriding
124 the type annotation for `__pydantic_extra__`:
125 ```python
126 from pydantic import BaseModel, ConfigDict, Field, ValidationError
129 class Model(BaseModel):
130 __pydantic_extra__: dict[str, int] = Field(init=False) # (1)!
132 x: int
134 model_config = ConfigDict(extra='allow')
137 try:
138 Model(x=1, y='a')
139 except ValidationError as exc:
140 print(exc)
141 """
142 1 validation error for Model
143 y
144 Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='a', input_type=str]
145 """
147 m = Model(x=1, y='2')
148 assert m.x == 1
149 assert m.y == 2
150 assert m.model_dump() == {'x': 1, 'y': 2}
151 assert m.__pydantic_extra__ == {'y': 2}
152 ```
154 1. The `= Field(init=False)` does not have any effect at runtime, but prevents the `__pydantic_extra__` field from
155 being included as a parameter to the model's `__init__` method by type checkers.
157 As well as specifying an `extra` configuration value on the model, you can also provide it as an argument to the validation methods.
158 This will override any `extra` configuration value set on the model:
159 ```python
160 from pydantic import BaseModel, ConfigDict, ValidationError
162 class Model(BaseModel):
163 x: int
164 model_config = ConfigDict(extra="allow")
166 try:
167 # Override model config and forbid extra fields just this time
168 Model.model_validate({"x": 1, "y": 2}, extra="forbid")
169 except ValidationError as exc:
170 print(exc)
171 """
172 1 validation error for Model
173 y
174 Extra inputs are not permitted [type=extra_forbidden, input_value=2, input_type=int]
175 """
176 ```
177 '''
179 frozen: bool
180 """
181 Whether models are faux-immutable, i.e. whether `__setattr__` is allowed, and also generates
182 a `__hash__()` method for the model. This makes instances of the model potentially hashable if all the
183 attributes are hashable. Defaults to `False`.
185 Note:
186 On V1, the inverse of this setting was called `allow_mutation`, and was `True` by default.
187 """
189 populate_by_name: bool
190 """
191 Whether an aliased field may be populated by its name as given by the model
192 attribute, as well as the alias. Defaults to `False`.
194 !!! warning
195 `populate_by_name` usage is not recommended in v2.11+ and will be deprecated in v3.
196 Instead, you should use the [`validate_by_name`][pydantic.config.ConfigDict.validate_by_name] configuration setting.
198 When `validate_by_name=True` and `validate_by_alias=True`, this is strictly equivalent to the
199 previous behavior of `populate_by_name=True`.
201 In v2.11, we also introduced a [`validate_by_alias`][pydantic.config.ConfigDict.validate_by_alias] setting that introduces more fine grained
202 control for validation behavior.
204 Here's how you might go about using the new settings to achieve the same behavior:
206 ```python
207 from pydantic import BaseModel, ConfigDict, Field
209 class Model(BaseModel):
210 model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
212 my_field: str = Field(alias='my_alias') # (1)!
214 m = Model(my_alias='foo') # (2)!
215 print(m)
216 #> my_field='foo'
218 m = Model(my_field='foo') # (3)!
219 print(m)
220 #> my_field='foo'
221 ```
223 1. The field `'my_field'` has an alias `'my_alias'`.
224 2. The model is populated by the alias `'my_alias'`.
225 3. The model is populated by the attribute name `'my_field'`.
226 """
228 use_enum_values: bool
229 """
230 Whether to populate models with the `value` property of enums, rather than the raw enum.
231 This may be useful if you want to serialize `model.model_dump()` later. Defaults to `False`.
233 !!! note
234 If you have an `Optional[Enum]` value that you set a default for, you need to use `validate_default=True`
235 for said Field to ensure that the `use_enum_values` flag takes effect on the default, as extracting an
236 enum's value occurs during validation, not serialization.
238 ```python
239 from enum import Enum
240 from typing import Optional
242 from pydantic import BaseModel, ConfigDict, Field
244 class SomeEnum(Enum):
245 FOO = 'foo'
246 BAR = 'bar'
247 BAZ = 'baz'
249 class SomeModel(BaseModel):
250 model_config = ConfigDict(use_enum_values=True)
252 some_enum: SomeEnum
253 another_enum: Optional[SomeEnum] = Field(
254 default=SomeEnum.FOO, validate_default=True
255 )
257 model1 = SomeModel(some_enum=SomeEnum.BAR)
258 print(model1.model_dump())
259 #> {'some_enum': 'bar', 'another_enum': 'foo'}
261 model2 = SomeModel(some_enum=SomeEnum.BAR, another_enum=SomeEnum.BAZ)
262 print(model2.model_dump())
263 #> {'some_enum': 'bar', 'another_enum': 'baz'}
264 ```
265 """
267 validate_assignment: bool
268 """
269 Whether to validate the data when the model is changed. Defaults to `False`.
271 The default behavior of Pydantic is to validate the data when the model is created.
273 In case the user changes the data after the model is created, the model is _not_ revalidated.
275 ```python
276 from pydantic import BaseModel
278 class User(BaseModel):
279 name: str
281 user = User(name='John Doe') # (1)!
282 print(user)
283 #> name='John Doe'
284 user.name = 123 # (1)!
285 print(user)
286 #> name=123
287 ```
289 1. The validation happens only when the model is created.
290 2. The validation does not happen when the data is changed.
292 In case you want to revalidate the model when the data is changed, you can use `validate_assignment=True`:
294 ```python
295 from pydantic import BaseModel, ValidationError
297 class User(BaseModel, validate_assignment=True): # (1)!
298 name: str
300 user = User(name='John Doe') # (2)!
301 print(user)
302 #> name='John Doe'
303 try:
304 user.name = 123 # (3)!
305 except ValidationError as e:
306 print(e)
307 '''
308 1 validation error for User
309 name
310 Input should be a valid string [type=string_type, input_value=123, input_type=int]
311 '''
312 ```
314 1. You can either use class keyword arguments, or `model_config` to set `validate_assignment=True`.
315 2. The validation happens when the model is created.
316 3. The validation _also_ happens when the data is changed.
317 """
319 arbitrary_types_allowed: bool
320 """
321 Whether arbitrary types are allowed for field types. Defaults to `False`.
323 ```python
324 from pydantic import BaseModel, ConfigDict, ValidationError
326 # This is not a pydantic model, it's an arbitrary class
327 class Pet:
328 def __init__(self, name: str):
329 self.name = name
331 class Model(BaseModel):
332 model_config = ConfigDict(arbitrary_types_allowed=True)
334 pet: Pet
335 owner: str
337 pet = Pet(name='Hedwig')
338 # A simple check of instance type is used to validate the data
339 model = Model(owner='Harry', pet=pet)
340 print(model)
341 #> pet=<__main__.Pet object at 0x0123456789ab> owner='Harry'
342 print(model.pet)
343 #> <__main__.Pet object at 0x0123456789ab>
344 print(model.pet.name)
345 #> Hedwig
346 print(type(model.pet))
347 #> <class '__main__.Pet'>
348 try:
349 # If the value is not an instance of the type, it's invalid
350 Model(owner='Harry', pet='Hedwig')
351 except ValidationError as e:
352 print(e)
353 '''
354 1 validation error for Model
355 pet
356 Input should be an instance of Pet [type=is_instance_of, input_value='Hedwig', input_type=str]
357 '''
359 # Nothing in the instance of the arbitrary type is checked
360 # Here name probably should have been a str, but it's not validated
361 pet2 = Pet(name=42)
362 model2 = Model(owner='Harry', pet=pet2)
363 print(model2)
364 #> pet=<__main__.Pet object at 0x0123456789ab> owner='Harry'
365 print(model2.pet)
366 #> <__main__.Pet object at 0x0123456789ab>
367 print(model2.pet.name)
368 #> 42
369 print(type(model2.pet))
370 #> <class '__main__.Pet'>
371 ```
372 """
374 from_attributes: bool
375 """
376 Whether to build models and look up discriminators of tagged unions using python object attributes.
377 """
379 loc_by_alias: bool
380 """Whether to use the actual key provided in the data (e.g. alias) for error `loc`s rather than the field's name. Defaults to `True`."""
382 alias_generator: Callable[[str], str] | AliasGenerator | None
383 """
384 A callable that takes a field name and returns an alias for it
385 or an instance of [`AliasGenerator`][pydantic.aliases.AliasGenerator]. Defaults to `None`.
387 When using a callable, the alias generator is used for both validation and serialization.
388 If you want to use different alias generators for validation and serialization, you can use
389 [`AliasGenerator`][pydantic.aliases.AliasGenerator] instead.
391 If data source field names do not match your code style (e.g. CamelCase fields),
392 you can automatically generate aliases using `alias_generator`. Here's an example with
393 a basic callable:
395 ```python
396 from pydantic import BaseModel, ConfigDict
397 from pydantic.alias_generators import to_pascal
399 class Voice(BaseModel):
400 model_config = ConfigDict(alias_generator=to_pascal)
402 name: str
403 language_code: str
405 voice = Voice(Name='Filiz', LanguageCode='tr-TR')
406 print(voice.language_code)
407 #> tr-TR
408 print(voice.model_dump(by_alias=True))
409 #> {'Name': 'Filiz', 'LanguageCode': 'tr-TR'}
410 ```
412 If you want to use different alias generators for validation and serialization, you can use
413 [`AliasGenerator`][pydantic.aliases.AliasGenerator].
415 ```python
416 from pydantic import AliasGenerator, BaseModel, ConfigDict
417 from pydantic.alias_generators import to_camel, to_pascal
419 class Athlete(BaseModel):
420 first_name: str
421 last_name: str
422 sport: str
424 model_config = ConfigDict(
425 alias_generator=AliasGenerator(
426 validation_alias=to_camel,
427 serialization_alias=to_pascal,
428 )
429 )
431 athlete = Athlete(firstName='John', lastName='Doe', sport='track')
432 print(athlete.model_dump(by_alias=True))
433 #> {'FirstName': 'John', 'LastName': 'Doe', 'Sport': 'track'}
434 ```
436 Note:
437 Pydantic offers three built-in alias generators: [`to_pascal`][pydantic.alias_generators.to_pascal],
438 [`to_camel`][pydantic.alias_generators.to_camel], and [`to_snake`][pydantic.alias_generators.to_snake].
439 """
441 ignored_types: tuple[type, ...]
442 """A tuple of types that may occur as values of class attributes without annotations. This is
443 typically used for custom descriptors (classes that behave like `property`). If an attribute is set on a
444 class without an annotation and has a type that is not in this tuple (or otherwise recognized by
445 _pydantic_), an error will be raised. Defaults to `()`.
446 """
448 allow_inf_nan: bool
449 """Whether to allow infinity (`+inf` an `-inf`) and NaN values to float and decimal fields. Defaults to `True`."""
451 json_schema_extra: JsonDict | JsonSchemaExtraCallable | None
452 """A dict or callable to provide extra JSON schema properties. Defaults to `None`."""
454 json_encoders: dict[type[object], JsonEncoder] | None
455 """
456 A `dict` of custom JSON encoders for specific types. Defaults to `None`.
458 /// version-deprecated | v2
459 This configuration option is a carryover from v1. We originally planned to remove it in v2 but didn't have a 1:1 replacement
460 so we are keeping it for now. It is still deprecated and will likely be removed in the future.
461 ///
462 """
464 # new in V2
465 strict: bool
466 """
467 Whether strict validation is applied to all fields on the model.
469 By default, Pydantic attempts to coerce values to the correct type, when possible.
471 There are situations in which you may want to disable this behavior, and instead raise an error if a value's type
472 does not match the field's type annotation.
474 To configure strict mode for all fields on a model, you can set `strict=True` on the model.
476 ```python
477 from pydantic import BaseModel, ConfigDict
479 class Model(BaseModel):
480 model_config = ConfigDict(strict=True)
482 name: str
483 age: int
484 ```
486 See [Strict Mode](../concepts/strict_mode.md) for more details.
488 See the [Conversion Table](../concepts/conversion_table.md) for more details on how Pydantic converts data in both
489 strict and lax modes.
491 /// version-added | v2
492 ///
493 """
494 # whether instances of models and dataclasses (including subclass instances) should re-validate, default 'never'
495 revalidate_instances: Literal['always', 'never', 'subclass-instances']
496 """
497 When and how to revalidate models and dataclasses during validation. Can be one of:
499 - `'never'`: will *not* revalidate models and dataclasses during validation
500 - `'always'`: will revalidate models and dataclasses during validation
501 - `'subclass-instances'`: will revalidate models and dataclasses during validation if the instance is a
502 subclass of the model or dataclass
504 The default is `'never'` (no revalidation).
506 This configuration only affects *the current model* it is applied on, and does *not* propagate to the models
507 referenced in fields.
509 ```python
510 from pydantic import BaseModel
512 class User(BaseModel, revalidate_instances='never'): # (1)!
513 name: str
515 class Transaction(BaseModel):
516 user: User
518 my_user = User(name='John')
519 t = Transaction(user=my_user)
521 my_user.name = 1 # (2)!
522 t = Transaction(user=my_user) # (3)!
523 print(t)
524 #> user=User(name=1)
525 ```
527 1. This is the default behavior.
528 2. The assignment is *not* validated, unless you set [`validate_assignment`][pydantic.ConfigDict.validate_assignment] in the configuration.
529 3. Since `revalidate_instances` is set to `'never'`, the user instance is not revalidated.
531 Here is an example demonstrating the behavior of `'subclass-instances'`:
533 ```python
534 from pydantic import BaseModel
536 class User(BaseModel, revalidate_instances='subclass-instances'):
537 name: str
539 class SubUser(User):
540 age: int
542 class Transaction(BaseModel):
543 user: User
545 my_user = User(name='John')
546 my_user.name = 1 # (1)!
547 t = Transaction(user=my_user) # (2)!
548 print(t)
549 #> user=User(name=1)
551 my_sub_user = SubUser(name='John', age=20)
552 t = Transaction(user=my_sub_user)
553 print(t) # (3)!
554 #> user=User(name='John')
555 ```
557 1. The assignment is *not* validated, unless you set [`validate_assignment`][pydantic.ConfigDict.validate_assignment] in the configuration.
558 2. Because `my_user` is a "direct" instance of `User`, it is *not* being revalidated. It would have been the case if
559 `revalidate_instances` was set to `'always'`.
560 3. Because `my_sub_user` is an instance of a `User` subclass, it is being revalidated. In this case, Pydantic coerces `my_sub_user` to the defined
561 `User` class defined on `Transaction`. If one of its fields had an invalid value, a validation error would have been raised.
563 /// version-added | v2
564 ///
565 """
567 ser_json_timedelta: Literal['iso8601', 'float']
568 """
569 The format of JSON serialized timedeltas. Accepts the string values of `'iso8601'` and
570 `'float'`. Defaults to `'iso8601'`.
572 - `'iso8601'` will serialize timedeltas to [ISO 8601 text format](https://en.wikipedia.org/wiki/ISO_8601#Durations).
573 - `'float'` will serialize timedeltas to the total number of seconds.
575 /// version-changed | v2.12
576 It is now recommended to use the [`ser_json_temporal`][pydantic.config.ConfigDict.ser_json_temporal]
577 setting. `ser_json_timedelta` will be deprecated in v3.
578 ///
579 """
581 ser_json_temporal: Literal['iso8601', 'seconds', 'milliseconds']
582 """
583 The format of JSON serialized temporal types from the [`datetime`][] module. This includes:
585 - [`datetime.datetime`][]
586 - [`datetime.date`][]
587 - [`datetime.time`][]
588 - [`datetime.timedelta`][]
590 Can be one of:
592 - `'iso8601'` will serialize date-like types to [ISO 8601 text format](https://en.wikipedia.org/wiki/ISO_8601#Durations).
593 - `'milliseconds'` will serialize date-like types to a floating point number of milliseconds since the epoch.
594 - `'seconds'` will serialize date-like types to a floating point number of seconds since the epoch.
596 Defaults to `'iso8601'`.
598 /// version-added | v2.12
599 This setting replaces [`ser_json_timedelta`][pydantic.config.ConfigDict.ser_json_timedelta],
600 which will be deprecated in v3. `ser_json_temporal` adds more configurability for the other temporal types.
601 ///
602 """
604 val_temporal_unit: Literal['seconds', 'milliseconds', 'infer']
605 """
606 The unit to assume for validating numeric input for datetime-like types ([`datetime.datetime`][] and [`datetime.date`][]). Can be one of:
608 - `'seconds'` will validate date or time numeric inputs as seconds since the [epoch].
609 - `'milliseconds'` will validate date or time numeric inputs as milliseconds since the [epoch].
610 - `'infer'` will infer the unit from the string numeric input on unix time as:
612 * seconds since the [epoch] if $-2^{10} <= v <= 2^{10}$
613 * milliseconds since the [epoch] (if $v < -2^{10}$ or $v > 2^{10}$).
615 Defaults to `'infer'`.
617 /// version-added | v2.12
618 ///
620 [epoch]: https://en.wikipedia.org/wiki/Unix_time
621 """
623 ser_json_bytes: Literal['utf8', 'base64', 'hex']
624 """
625 The encoding of JSON serialized bytes. Defaults to `'utf8'`.
626 Set equal to `val_json_bytes` to get back an equal value after serialization round trip.
628 - `'utf8'` will serialize bytes to UTF-8 strings.
629 - `'base64'` will serialize bytes to URL safe base64 strings.
630 - `'hex'` will serialize bytes to hexadecimal strings.
631 """
633 val_json_bytes: Literal['utf8', 'base64', 'hex']
634 """
635 /// version-added | v2.9
636 ///
638 The encoding of JSON serialized bytes to decode. Defaults to `'utf8'`.
639 Set equal to `ser_json_bytes` to get back an equal value after serialization round trip.
641 - `'utf8'` will deserialize UTF-8 strings to bytes.
642 - `'base64'` will deserialize URL safe base64 strings to bytes.
643 - `'hex'` will deserialize hexadecimal strings to bytes.
644 """
646 ser_json_inf_nan: Literal['null', 'constants', 'strings']
647 """
648 The encoding of JSON serialized infinity and NaN float values. Defaults to `'null'`.
650 - `'null'` will serialize infinity and NaN values as `null`.
651 - `'constants'` will serialize infinity and NaN values as `Infinity` and `NaN`.
652 - `'strings'` will serialize infinity as string `"Infinity"` and NaN as string `"NaN"`.
653 """
655 # whether to validate default values during validation, default False
656 validate_default: bool
657 """Whether to validate default values during validation. Defaults to `False`."""
659 validate_return: bool
660 """Whether to validate the return value from call validators. Defaults to `False`."""
662 protected_namespaces: tuple[str | Pattern[str], ...]
663 """
664 A tuple of strings and/or regex patterns that prevent models from having fields with names that conflict with its existing members/methods.
666 Strings are matched on a prefix basis. For instance, with `'dog'`, having a field named `'dog_name'` will be disallowed.
668 Regex patterns are matched on the entire field name. For instance, with the pattern `'^dog$'`, having a field named `'dog'` will be disallowed,
669 but `'dog_name'` will be accepted.
671 Defaults to `('model_validate', 'model_dump')`. This default is used to prevent collisions with the existing (and possibly future)
672 [validation](../concepts/models.md#validating-data) and [serialization](../concepts/serialization.md#serializing-data) methods.
674 ```python
675 import warnings
677 from pydantic import BaseModel
679 warnings.filterwarnings('error') # Raise warnings as errors
681 try:
683 class Model(BaseModel):
684 model_dump_something: str
686 except UserWarning as e:
687 print(e)
688 '''
689 Field 'model_dump_something' in 'Model' conflicts with protected namespace 'model_dump'.
691 You may be able to solve this by setting the 'protected_namespaces' configuration to ('model_validate',).
692 '''
693 ```
695 You can customize this behavior using the `protected_namespaces` setting:
697 ```python {test="skip"}
698 import re
699 import warnings
701 from pydantic import BaseModel, ConfigDict
703 with warnings.catch_warnings(record=True) as caught_warnings:
704 warnings.simplefilter('always') # Catch all warnings
706 class Model(BaseModel):
707 safe_field: str
708 also_protect_field: str
709 protect_this: str
711 model_config = ConfigDict(
712 protected_namespaces=(
713 'protect_me_',
714 'also_protect_',
715 re.compile('^protect_this$'),
716 )
717 )
719 for warning in caught_warnings:
720 print(f'{warning.message}')
721 '''
722 Field 'also_protect_field' in 'Model' conflicts with protected namespace 'also_protect_'.
723 You may be able to solve this by setting the 'protected_namespaces' configuration to ('protect_me_', re.compile('^protect_this$'))`.
725 Field 'protect_this' in 'Model' conflicts with protected namespace 're.compile('^protect_this$')'.
726 You may be able to solve this by setting the 'protected_namespaces' configuration to ('protect_me_', 'also_protect_')`.
727 '''
728 ```
730 While Pydantic will only emit a warning when an item is in a protected namespace but does not actually have a collision,
731 an error _is_ raised if there is an actual collision with an existing attribute:
733 ```python
734 from pydantic import BaseModel, ConfigDict
736 try:
738 class Model(BaseModel):
739 model_validate: str
741 model_config = ConfigDict(protected_namespaces=('model_',))
743 except ValueError as e:
744 print(e)
745 '''
746 Field 'model_validate' conflicts with member <bound method BaseModel.model_validate of <class 'pydantic.main.BaseModel'>> of protected namespace 'model_'.
747 '''
748 ```
750 /// version-changed | v2.10
751 The default protected namespaces was changed from `('model_',)` to `('model_validate', 'model_dump')`, to allow
752 for fields like `model_id`, `model_name` to be used.
753 ///
754 """
756 hide_input_in_errors: bool
757 """
758 Whether to hide inputs when printing errors. Defaults to `False`.
760 Pydantic shows the input value and type when it raises `ValidationError` during the validation.
762 ```python
763 from pydantic import BaseModel, ValidationError
765 class Model(BaseModel):
766 a: str
768 try:
769 Model(a=123)
770 except ValidationError as e:
771 print(e)
772 '''
773 1 validation error for Model
774 a
775 Input should be a valid string [type=string_type, input_value=123, input_type=int]
776 '''
777 ```
779 You can hide the input value and type by setting the `hide_input_in_errors` config to `True`.
781 ```python
782 from pydantic import BaseModel, ConfigDict, ValidationError
784 class Model(BaseModel):
785 a: str
786 model_config = ConfigDict(hide_input_in_errors=True)
788 try:
789 Model(a=123)
790 except ValidationError as e:
791 print(e)
792 '''
793 1 validation error for Model
794 a
795 Input should be a valid string [type=string_type]
796 '''
797 ```
798 """
800 defer_build: bool
801 """
802 Whether to defer model validator and serializer construction until the first model validation. Defaults to False.
804 This can be useful to avoid the overhead of building models which are only
805 used nested within other models, or when you want to manually define type namespace via
806 [`Model.model_rebuild(_types_namespace=...)`][pydantic.BaseModel.model_rebuild].
808 /// version-changed | v2.10
809 The setting also applies to [Pydantic dataclasses](../concepts/dataclasses.md) and [type adapters](../concepts/type_adapter.md).
810 ///
811 """
813 plugin_settings: dict[str, object] | None
814 """A `dict` of settings for plugins. Defaults to `None`."""
816 schema_generator: type[_GenerateSchema] | None
817 """
818 The `GenerateSchema` class to use during core schema generation.
820 /// version-deprecated | v2.10
821 The `GenerateSchema` class is private and highly subject to change.
822 ///
823 """
825 json_schema_serialization_defaults_required: bool
826 """
827 Whether fields with default values should be marked as required in the serialization schema. Defaults to `False`.
829 This ensures that the serialization schema will reflect the fact a field with a default will always be present
830 when serializing the model, even though it is not required for validation.
832 However, there are scenarios where this may be undesirable — in particular, if you want to share the schema
833 between validation and serialization, and don't mind fields with defaults being marked as not required during
834 serialization. See [#7209](https://github.com/pydantic/pydantic/issues/7209) for more details.
836 ```python
837 from pydantic import BaseModel, ConfigDict
839 class Model(BaseModel):
840 a: str = 'a'
842 model_config = ConfigDict(json_schema_serialization_defaults_required=True)
844 print(Model.model_json_schema(mode='validation'))
845 '''
846 {
847 'properties': {'a': {'default': 'a', 'title': 'A', 'type': 'string'}},
848 'title': 'Model',
849 'type': 'object',
850 }
851 '''
852 print(Model.model_json_schema(mode='serialization'))
853 '''
854 {
855 'properties': {'a': {'default': 'a', 'title': 'A', 'type': 'string'}},
856 'required': ['a'],
857 'title': 'Model',
858 'type': 'object',
859 }
860 '''
861 ```
863 /// version-added | v2.4
864 ///
865 """
867 json_schema_mode_override: Literal['validation', 'serialization', None]
868 """
869 If not `None`, the specified mode will be used to generate the JSON schema regardless of what `mode` was passed to
870 the function call. Defaults to `None`.
872 This provides a way to force the JSON schema generation to reflect a specific mode, e.g., to always use the
873 validation schema.
875 It can be useful when using frameworks (such as FastAPI) that may generate different schemas for validation
876 and serialization that must both be referenced from the same schema; when this happens, we automatically append
877 `-Input` to the definition reference for the validation schema and `-Output` to the definition reference for the
878 serialization schema. By specifying a `json_schema_mode_override` though, this prevents the conflict between
879 the validation and serialization schemas (since both will use the specified schema), and so prevents the suffixes
880 from being added to the definition references.
882 ```python
883 from pydantic import BaseModel, ConfigDict, Json
885 class Model(BaseModel):
886 a: Json[int] # requires a string to validate, but will dump an int
888 print(Model.model_json_schema(mode='serialization'))
889 '''
890 {
891 'properties': {'a': {'title': 'A', 'type': 'integer'}},
892 'required': ['a'],
893 'title': 'Model',
894 'type': 'object',
895 }
896 '''
898 class ForceInputModel(Model):
899 # the following ensures that even with mode='serialization', we
900 # will get the schema that would be generated for validation.
901 model_config = ConfigDict(json_schema_mode_override='validation')
903 print(ForceInputModel.model_json_schema(mode='serialization'))
904 '''
905 {
906 'properties': {
907 'a': {
908 'contentMediaType': 'application/json',
909 'contentSchema': {'type': 'integer'},
910 'title': 'A',
911 'type': 'string',
912 }
913 },
914 'required': ['a'],
915 'title': 'ForceInputModel',
916 'type': 'object',
917 }
918 '''
919 ```
921 /// version-added | v2.4
922 ///
923 """
925 coerce_numbers_to_str: bool
926 """
927 If `True`, enables automatic coercion of any `Number` type to `str` in "lax" (non-strict) mode. Defaults to `False`.
929 Pydantic doesn't allow number types (`int`, `float`, `Decimal`) to be coerced as type `str` by default.
931 ```python
932 from decimal import Decimal
934 from pydantic import BaseModel, ConfigDict, ValidationError
936 class Model(BaseModel):
937 value: str
939 try:
940 print(Model(value=42))
941 except ValidationError as e:
942 print(e)
943 '''
944 1 validation error for Model
945 value
946 Input should be a valid string [type=string_type, input_value=42, input_type=int]
947 '''
949 class Model(BaseModel):
950 model_config = ConfigDict(coerce_numbers_to_str=True)
952 value: str
954 repr(Model(value=42).value)
955 #> "42"
956 repr(Model(value=42.13).value)
957 #> "42.13"
958 repr(Model(value=Decimal('42.13')).value)
959 #> "42.13"
960 ```
961 """
963 regex_engine: Literal['rust-regex', 'python-re']
964 """
965 The regex engine to be used for pattern validation.
966 Defaults to `'rust-regex'`.
968 - `'rust-regex'` uses the [`regex`](https://docs.rs/regex) Rust crate,
969 which is non-backtracking and therefore more DDoS resistant, but does not support all regex features.
970 - `'python-re'` use the [`re`][] module, which supports all regex features, but may be slower.
972 !!! note
973 If you use a compiled regex pattern, the `'python-re'` engine will be used regardless of this setting.
974 This is so that flags such as [`re.IGNORECASE`][] are respected.
976 ```python
977 from pydantic import BaseModel, ConfigDict, Field, ValidationError
979 class Model(BaseModel):
980 model_config = ConfigDict(regex_engine='python-re')
982 value: str = Field(pattern=r'^abc(?=def)')
984 print(Model(value='abcdef').value)
985 #> abcdef
987 try:
988 print(Model(value='abxyzcdef'))
989 except ValidationError as e:
990 print(e)
991 '''
992 1 validation error for Model
993 value
994 String should match pattern '^abc(?=def)' [type=string_pattern_mismatch, input_value='abxyzcdef', input_type=str]
995 '''
996 ```
998 /// version-added | v2.5
999 ///
1000 """
1002 validation_error_cause: bool
1003 """
1004 If `True`, Python exceptions that were part of a validation failure will be shown as an exception group as a cause. Can be useful for debugging. Defaults to `False`.
1006 Note:
1007 Python 3.10 and older don't support exception groups natively. <=3.10, backport must be installed: `pip install exceptiongroup`.
1009 Note:
1010 The structure of validation errors are likely to change in future Pydantic versions. Pydantic offers no guarantees about their structure. Should be used for visual traceback debugging only.
1012 /// version-added | v2.5
1013 ///
1014 """
1016 use_attribute_docstrings: bool
1017 '''
1018 Whether docstrings of attributes (bare string literals immediately following the attribute declaration)
1019 should be used for field descriptions. Defaults to `False`.
1021 ```python
1022 from pydantic import BaseModel, ConfigDict, Field
1025 class Model(BaseModel):
1026 model_config = ConfigDict(use_attribute_docstrings=True)
1028 x: str
1029 """
1030 Example of an attribute docstring
1031 """
1033 y: int = Field(description="Description in Field")
1034 """
1035 Description in Field overrides attribute docstring
1036 """
1039 print(Model.model_fields["x"].description)
1040 # > Example of an attribute docstring
1041 print(Model.model_fields["y"].description)
1042 # > Description in Field
1043 ```
1044 This requires the source code of the class to be available at runtime (and so won't work in the interactive interpreter shell).
1046 !!! warning "Usage with `TypedDict` and stdlib dataclasses"
1047 Due to current limitations, attribute docstrings detection may not work as expected when using
1048 [`TypedDict`][typing.TypedDict] and stdlib dataclasses, in particular when:
1050 - inheritance is being used.
1051 - multiple classes have the same name in the same source file (unless Python 3.13 or greater is used).
1053 /// version-added | v2.7
1054 ///
1055 '''
1057 cache_strings: bool | Literal['all', 'keys', 'none']
1058 """
1059 Whether to cache strings to avoid constructing new Python objects. Defaults to True.
1061 Enabling this setting should significantly improve validation performance while increasing memory usage slightly.
1063 - `True` or `'all'` (the default): cache all strings
1064 - `'keys'`: cache only dictionary keys
1065 - `False` or `'none'`: no caching
1067 !!! note
1068 `True` or `'all'` is required to cache strings during general validation because
1069 validators don't know if they're in a key or a value.
1071 !!! tip
1072 If repeated strings are rare, it's recommended to use `'keys'` or `'none'` to reduce memory usage,
1073 as the performance difference is minimal if repeated strings are rare.
1075 /// version-added | v2.7
1076 ///
1077 """
1079 validate_by_alias: bool
1080 """
1081 Whether an aliased field may be populated by its alias. Defaults to `True`.
1083 Here's an example of disabling validation by alias:
1085 ```py
1086 from pydantic import BaseModel, ConfigDict, Field
1088 class Model(BaseModel):
1089 model_config = ConfigDict(validate_by_name=True, validate_by_alias=False)
1091 my_field: str = Field(validation_alias='my_alias') # (1)!
1093 m = Model(my_field='foo') # (2)!
1094 print(m)
1095 #> my_field='foo'
1096 ```
1098 1. The field `'my_field'` has an alias `'my_alias'`.
1099 2. The model can only be populated by the attribute name `'my_field'`.
1101 !!! warning
1102 You cannot set both `validate_by_alias` and `validate_by_name` to `False`.
1103 This would make it impossible to populate an attribute.
1105 See [usage errors](../errors/usage_errors.md#validate-by-alias-and-name-false) for an example.
1107 If you set `validate_by_alias` to `False`, under the hood, Pydantic dynamically sets
1108 `validate_by_name` to `True` to ensure that validation can still occur.
1110 /// version-added | v2.11
1111 This setting was introduced in conjunction with [`validate_by_name`][pydantic.ConfigDict.validate_by_name]
1112 to empower users with more fine grained validation control.
1113 ///
1114 """
1116 validate_by_name: bool
1117 """
1118 Whether an aliased field may be populated by its name as given by the model
1119 attribute. Defaults to `False`.
1121 ```python
1122 from pydantic import BaseModel, ConfigDict, Field
1124 class Model(BaseModel):
1125 model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
1127 my_field: str = Field(validation_alias='my_alias') # (1)!
1129 m = Model(my_alias='foo') # (2)!
1130 print(m)
1131 #> my_field='foo'
1133 m = Model(my_field='foo') # (3)!
1134 print(m)
1135 #> my_field='foo'
1136 ```
1138 1. The field `'my_field'` has an alias `'my_alias'`.
1139 2. The model is populated by the alias `'my_alias'`.
1140 3. The model is populated by the attribute name `'my_field'`.
1142 !!! warning
1143 You cannot set both `validate_by_alias` and `validate_by_name` to `False`.
1144 This would make it impossible to populate an attribute.
1146 See [usage errors](../errors/usage_errors.md#validate-by-alias-and-name-false) for an example.
1148 /// version-added | v2.11
1149 This setting was introduced in conjunction with [`validate_by_alias`][pydantic.ConfigDict.validate_by_alias]
1150 to empower users with more fine grained validation control. It is an alternative to [`populate_by_name`][pydantic.ConfigDict.populate_by_name],
1151 that enables validation by name **and** by alias.
1152 ///
1153 """
1155 serialize_by_alias: bool
1156 """
1157 Whether an aliased field should be serialized by its alias. Defaults to `False`.
1159 Note: In v2.11, `serialize_by_alias` was introduced to address the
1160 [popular request](https://github.com/pydantic/pydantic/issues/8379)
1161 for consistency with alias behavior for validation and serialization settings.
1162 In v3, the default value is expected to change to `True` for consistency with the validation default.
1164 ```python
1165 from pydantic import BaseModel, ConfigDict, Field
1167 class Model(BaseModel):
1168 model_config = ConfigDict(serialize_by_alias=True)
1170 my_field: str = Field(serialization_alias='my_alias') # (1)!
1172 m = Model(my_field='foo')
1173 print(m.model_dump()) # (2)!
1174 #> {'my_alias': 'foo'}
1175 ```
1177 1. The field `'my_field'` has an alias `'my_alias'`.
1178 2. The model is serialized using the alias `'my_alias'` for the `'my_field'` attribute.
1181 /// version-added | v2.11
1182 This setting was introduced to address the [popular request](https://github.com/pydantic/pydantic/issues/8379)
1183 for consistency with alias behavior for validation and serialization.
1185 In v3, the default value is expected to change to `True` for consistency with the validation default.
1186 ///
1187 """
1189 url_preserve_empty_path: bool
1190 """
1191 Whether to preserve empty URL paths when validating values for a URL type. Defaults to `False`.
1193 ```python
1194 from pydantic import AnyUrl, BaseModel, ConfigDict
1196 class Model(BaseModel):
1197 model_config = ConfigDict(url_preserve_empty_path=True)
1199 url: AnyUrl
1201 m = Model(url='http://example.com')
1202 print(m.url)
1203 #> http://example.com
1204 ```
1206 /// version-added | v2.12
1207 ///
1208 """
1210 polymorphic_serialization: bool
1211 """
1212 Whether to use polymorphic serialization for subclasses of the model or Pydantic dataclass. Defaults to `False`.
1213 """
1216_TypeT = TypeVar('_TypeT', bound=type)
1219@overload
1220@deprecated('Passing `config` as a keyword argument is deprecated. Pass `config` as a positional argument instead.')
1221def with_config(*, config: ConfigDict) -> Callable[[_TypeT], _TypeT]: ...
1224@overload
1225def with_config(config: ConfigDict, /) -> Callable[[_TypeT], _TypeT]: ...
1228@overload
1229def with_config(**config: Unpack[ConfigDict]) -> Callable[[_TypeT], _TypeT]: ...
1232def with_config(config: ConfigDict | None = None, /, **kwargs: Any) -> Callable[[_TypeT], _TypeT]:
1233 """!!! abstract "Usage Documentation"
1234 [Configuration with other types](../concepts/config.md#configuration-on-other-supported-types)
1236 A convenience decorator to set a [Pydantic configuration](config.md) on a `TypedDict` or a `dataclass` from the standard library.
1238 Although the configuration can be set using the `__pydantic_config__` attribute, it does not play well with type checkers,
1239 especially with `TypedDict`.
1241 !!! example "Usage"
1243 ```python
1244 from typing_extensions import TypedDict
1246 from pydantic import ConfigDict, TypeAdapter, with_config
1248 @with_config(ConfigDict(str_to_lower=True))
1249 class TD(TypedDict):
1250 x: str
1252 ta = TypeAdapter(TD)
1254 print(ta.validate_python({'x': 'ABC'}))
1255 #> {'x': 'abc'}
1256 ```
1258 /// deprecated-removed | v2.11 v3
1259 Passing `config` as a keyword argument.
1260 ///
1262 /// version-changed | v2.11
1263 Keyword arguments can be provided directly instead of a config dictionary.
1264 ///
1265 """
1266 if config is not None and kwargs:
1267 raise ValueError('Cannot specify both `config` and keyword arguments')
1269 if len(kwargs) == 1 and (kwargs_conf := kwargs.get('config')) is not None:
1270 warnings.warn(
1271 'Passing `config` as a keyword argument is deprecated. Pass `config` as a positional argument instead',
1272 category=PydanticDeprecatedSince211,
1273 stacklevel=2,
1274 )
1275 final_config = cast(ConfigDict, kwargs_conf)
1276 else:
1277 final_config = config if config is not None else cast(ConfigDict, kwargs)
1279 def inner(class_: _TypeT, /) -> _TypeT:
1280 # Ideally, we would check for `class_` to either be a `TypedDict` or a stdlib dataclass.
1281 # However, the `@with_config` decorator can be applied *after* `@dataclass`. To avoid
1282 # common mistakes, we at least check for `class_` to not be a Pydantic model.
1283 from ._internal._utils import is_model_class
1285 if is_model_class(class_):
1286 raise PydanticUserError(
1287 f'Cannot use `with_config` on {class_.__name__} as it is a Pydantic model',
1288 code='with-config-on-model',
1289 )
1290 class_.__pydantic_config__ = final_config
1291 return class_
1293 return inner
1296__getattr__ = getattr_migration(__name__)