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* populate 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 The encoding of JSON serialized bytes to decode. Defaults to `'utf8'`.
636 Set equal to `ser_json_bytes` to get back an equal value after serialization round trip.
638 - `'utf8'` will deserialize UTF-8 strings to bytes.
639 - `'base64'` will deserialize URL safe base64 strings to bytes.
640 - `'hex'` will deserialize hexadecimal strings to bytes.
641 """
643 ser_json_inf_nan: Literal['null', 'constants', 'strings']
644 """
645 The encoding of JSON serialized infinity and NaN float values. Defaults to `'null'`.
647 - `'null'` will serialize infinity and NaN values as `null`.
648 - `'constants'` will serialize infinity and NaN values as `Infinity` and `NaN`.
649 - `'strings'` will serialize infinity as string `"Infinity"` and NaN as string `"NaN"`.
650 """
652 # whether to validate default values during validation, default False
653 validate_default: bool
654 """Whether to validate default values during validation. Defaults to `False`."""
656 validate_return: bool
657 """Whether to validate the return value from call validators. Defaults to `False`."""
659 protected_namespaces: tuple[str | Pattern[str], ...]
660 """
661 A tuple of strings and/or regex patterns that prevent models from having fields with names that conflict with its existing members/methods.
663 Strings are matched on a prefix basis. For instance, with `'dog'`, having a field named `'dog_name'` will be disallowed.
665 Regex patterns are matched on the entire field name. For instance, with the pattern `'^dog$'`, having a field named `'dog'` will be disallowed,
666 but `'dog_name'` will be accepted.
668 Defaults to `('model_validate', 'model_dump')`. This default is used to prevent collisions with the existing (and possibly future)
669 [validation](../concepts/models.md#validating-data) and [serialization](../concepts/serialization.md#serializing-data) methods.
671 ```python
672 import warnings
674 from pydantic import BaseModel
676 warnings.filterwarnings('error') # Raise warnings as errors
678 try:
680 class Model(BaseModel):
681 model_dump_something: str
683 except UserWarning as e:
684 print(e)
685 '''
686 Field 'model_dump_something' in 'Model' conflicts with protected namespace 'model_dump'.
688 You may be able to solve this by setting the 'protected_namespaces' configuration to ('model_validate',).
689 '''
690 ```
692 You can customize this behavior using the `protected_namespaces` setting:
694 ```python {test="skip"}
695 import re
696 import warnings
698 from pydantic import BaseModel, ConfigDict
700 with warnings.catch_warnings(record=True) as caught_warnings:
701 warnings.simplefilter('always') # Catch all warnings
703 class Model(BaseModel):
704 safe_field: str
705 also_protect_field: str
706 protect_this: str
708 model_config = ConfigDict(
709 protected_namespaces=(
710 'protect_me_',
711 'also_protect_',
712 re.compile('^protect_this$'),
713 )
714 )
716 for warning in caught_warnings:
717 print(f'{warning.message}')
718 '''
719 Field 'also_protect_field' in 'Model' conflicts with protected namespace 'also_protect_'.
720 You may be able to solve this by setting the 'protected_namespaces' configuration to ('protect_me_', re.compile('^protect_this$'))`.
722 Field 'protect_this' in 'Model' conflicts with protected namespace 're.compile('^protect_this$')'.
723 You may be able to solve this by setting the 'protected_namespaces' configuration to ('protect_me_', 'also_protect_')`.
724 '''
725 ```
727 While Pydantic will only emit a warning when an item is in a protected namespace but does not actually have a collision,
728 an error _is_ raised if there is an actual collision with an existing attribute:
730 ```python
731 from pydantic import BaseModel, ConfigDict
733 try:
735 class Model(BaseModel):
736 model_validate: str
738 model_config = ConfigDict(protected_namespaces=('model_',))
740 except ValueError as e:
741 print(e)
742 '''
743 Field 'model_validate' conflicts with member <bound method BaseModel.model_validate of <class 'pydantic.main.BaseModel'>> of protected namespace 'model_'.
744 '''
745 ```
747 /// version-changed | v2.10
748 The default protected namespaces was changed from `('model_',)` to `('model_validate', 'model_dump')`, to allow
749 for fields like `model_id`, `model_name` to be used.
750 ///
751 """
753 hide_input_in_errors: bool
754 """
755 Whether to hide inputs when printing errors. Defaults to `False`.
757 Pydantic shows the input value and type when it raises `ValidationError` during the validation.
759 ```python
760 from pydantic import BaseModel, ValidationError
762 class Model(BaseModel):
763 a: str
765 try:
766 Model(a=123)
767 except ValidationError as e:
768 print(e)
769 '''
770 1 validation error for Model
771 a
772 Input should be a valid string [type=string_type, input_value=123, input_type=int]
773 '''
774 ```
776 You can hide the input value and type by setting the `hide_input_in_errors` config to `True`.
778 ```python
779 from pydantic import BaseModel, ConfigDict, ValidationError
781 class Model(BaseModel):
782 a: str
783 model_config = ConfigDict(hide_input_in_errors=True)
785 try:
786 Model(a=123)
787 except ValidationError as e:
788 print(e)
789 '''
790 1 validation error for Model
791 a
792 Input should be a valid string [type=string_type]
793 '''
794 ```
795 """
797 defer_build: bool
798 """
799 Whether to defer model validator and serializer construction until the first model validation. Defaults to False.
801 This can be useful to avoid the overhead of building models which are only
802 used nested within other models, or when you want to manually define type namespace via
803 [`Model.model_rebuild(_types_namespace=...)`][pydantic.BaseModel.model_rebuild].
805 /// version-changed | v2.10
806 The setting also applies to [Pydantic dataclasses](../concepts/dataclasses.md) and [type adapters](../concepts/type_adapter.md).
807 ///
808 """
810 plugin_settings: dict[str, object] | None
811 """A `dict` of settings for plugins. Defaults to `None`."""
813 schema_generator: type[_GenerateSchema] | None
814 """
815 The `GenerateSchema` class to use during core schema generation.
817 /// version-deprecated | v2.10
818 The `GenerateSchema` class is private and highly subject to change.
819 ///
820 """
822 json_schema_serialization_defaults_required: bool
823 """
824 Whether fields with default values should be marked as required in the serialization schema. Defaults to `False`.
826 This ensures that the serialization schema will reflect the fact a field with a default will always be present
827 when serializing the model, even though it is not required for validation.
829 However, there are scenarios where this may be undesirable — in particular, if you want to share the schema
830 between validation and serialization, and don't mind fields with defaults being marked as not required during
831 serialization. See [#7209](https://github.com/pydantic/pydantic/issues/7209) for more details.
833 ```python
834 from pydantic import BaseModel, ConfigDict
836 class Model(BaseModel):
837 a: str = 'a'
839 model_config = ConfigDict(json_schema_serialization_defaults_required=True)
841 print(Model.model_json_schema(mode='validation'))
842 '''
843 {
844 'properties': {'a': {'default': 'a', 'title': 'A', 'type': 'string'}},
845 'title': 'Model',
846 'type': 'object',
847 }
848 '''
849 print(Model.model_json_schema(mode='serialization'))
850 '''
851 {
852 'properties': {'a': {'default': 'a', 'title': 'A', 'type': 'string'}},
853 'required': ['a'],
854 'title': 'Model',
855 'type': 'object',
856 }
857 '''
858 ```
860 /// version-added | v2.4
861 ///
862 """
864 json_schema_mode_override: Literal['validation', 'serialization', None]
865 """
866 If not `None`, the specified mode will be used to generate the JSON schema regardless of what `mode` was passed to
867 the function call. Defaults to `None`.
869 This provides a way to force the JSON schema generation to reflect a specific mode, e.g., to always use the
870 validation schema.
872 It can be useful when using frameworks (such as FastAPI) that may generate different schemas for validation
873 and serialization that must both be referenced from the same schema; when this happens, we automatically append
874 `-Input` to the definition reference for the validation schema and `-Output` to the definition reference for the
875 serialization schema. By specifying a `json_schema_mode_override` though, this prevents the conflict between
876 the validation and serialization schemas (since both will use the specified schema), and so prevents the suffixes
877 from being added to the definition references.
879 ```python
880 from pydantic import BaseModel, ConfigDict, Json
882 class Model(BaseModel):
883 a: Json[int] # requires a string to validate, but will dump an int
885 print(Model.model_json_schema(mode='serialization'))
886 '''
887 {
888 'properties': {'a': {'title': 'A', 'type': 'integer'}},
889 'required': ['a'],
890 'title': 'Model',
891 'type': 'object',
892 }
893 '''
895 class ForceInputModel(Model):
896 # the following ensures that even with mode='serialization', we
897 # will get the schema that would be generated for validation.
898 model_config = ConfigDict(json_schema_mode_override='validation')
900 print(ForceInputModel.model_json_schema(mode='serialization'))
901 '''
902 {
903 'properties': {
904 'a': {
905 'contentMediaType': 'application/json',
906 'contentSchema': {'type': 'integer'},
907 'title': 'A',
908 'type': 'string',
909 }
910 },
911 'required': ['a'],
912 'title': 'ForceInputModel',
913 'type': 'object',
914 }
915 '''
916 ```
918 /// version-added | v2.4
919 ///
920 """
922 coerce_numbers_to_str: bool
923 """
924 If `True`, enables automatic coercion of any `Number` type to `str` in "lax" (non-strict) mode. Defaults to `False`.
926 Pydantic doesn't allow number types (`int`, `float`, `Decimal`) to be coerced as type `str` by default.
928 ```python
929 from decimal import Decimal
931 from pydantic import BaseModel, ConfigDict, ValidationError
933 class Model(BaseModel):
934 value: str
936 try:
937 print(Model(value=42))
938 except ValidationError as e:
939 print(e)
940 '''
941 1 validation error for Model
942 value
943 Input should be a valid string [type=string_type, input_value=42, input_type=int]
944 '''
946 class Model(BaseModel):
947 model_config = ConfigDict(coerce_numbers_to_str=True)
949 value: str
951 repr(Model(value=42).value)
952 #> "42"
953 repr(Model(value=42.13).value)
954 #> "42.13"
955 repr(Model(value=Decimal('42.13')).value)
956 #> "42.13"
957 ```
958 """
960 regex_engine: Literal['rust-regex', 'python-re']
961 """
962 The regex engine to be used for pattern validation.
963 Defaults to `'rust-regex'`.
965 - `'rust-regex'` uses the [`regex`](https://docs.rs/regex) Rust crate,
966 which is non-backtracking and therefore more DDoS resistant, but does not support all regex features.
967 - `'python-re'` use the [`re`][] module, which supports all regex features, but may be slower.
969 !!! note
970 If you use a compiled regex pattern, the `'python-re'` engine will be used regardless of this setting.
971 This is so that flags such as [`re.IGNORECASE`][] are respected.
973 ```python
974 from pydantic import BaseModel, ConfigDict, Field, ValidationError
976 class Model(BaseModel):
977 model_config = ConfigDict(regex_engine='python-re')
979 value: str = Field(pattern=r'^abc(?=def)')
981 print(Model(value='abcdef').value)
982 #> abcdef
984 try:
985 print(Model(value='abxyzcdef'))
986 except ValidationError as e:
987 print(e)
988 '''
989 1 validation error for Model
990 value
991 String should match pattern '^abc(?=def)' [type=string_pattern_mismatch, input_value='abxyzcdef', input_type=str]
992 '''
993 ```
995 /// version-added | v2.5
996 ///
997 """
999 validation_error_cause: bool
1000 """
1001 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`.
1003 Note:
1004 Python 3.10 and older don't support exception groups natively. <=3.10, backport must be installed: `pip install exceptiongroup`.
1006 Note:
1007 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.
1009 /// version-added | v2.5
1010 ///
1011 """
1013 use_attribute_docstrings: bool
1014 '''
1015 Whether docstrings of attributes (bare string literals immediately following the attribute declaration)
1016 should be used for field descriptions. Defaults to `False`.
1018 ```python
1019 from pydantic import BaseModel, ConfigDict, Field
1022 class Model(BaseModel):
1023 model_config = ConfigDict(use_attribute_docstrings=True)
1025 x: str
1026 """
1027 Example of an attribute docstring
1028 """
1030 y: int = Field(description="Description in Field")
1031 """
1032 Description in Field overrides attribute docstring
1033 """
1036 print(Model.model_fields["x"].description)
1037 # > Example of an attribute docstring
1038 print(Model.model_fields["y"].description)
1039 # > Description in Field
1040 ```
1041 This requires the source code of the class to be available at runtime.
1043 !!! warning "Usage with `TypedDict` and stdlib dataclasses"
1044 Due to current limitations, attribute docstrings detection may not work as expected when using
1045 [`TypedDict`][typing.TypedDict] and stdlib dataclasses, in particular when:
1047 - inheritance is being used.
1048 - multiple classes have the same name in the same source file (unless Python 3.13 or greater is used).
1050 /// version-added | v2.7
1051 ///
1052 '''
1054 cache_strings: bool | Literal['all', 'keys', 'none']
1055 """
1056 Whether to cache strings to avoid constructing new Python objects. Defaults to True.
1058 Enabling this setting should significantly improve validation performance while increasing memory usage slightly.
1060 - `True` or `'all'` (the default): cache all strings
1061 - `'keys'`: cache only dictionary keys
1062 - `False` or `'none'`: no caching
1064 !!! note
1065 `True` or `'all'` is required to cache strings during general validation because
1066 validators don't know if they're in a key or a value.
1068 !!! tip
1069 If repeated strings are rare, it's recommended to use `'keys'` or `'none'` to reduce memory usage,
1070 as the performance difference is minimal if repeated strings are rare.
1072 /// version-added | v2.7
1073 ///
1074 """
1076 validate_by_alias: bool
1077 """
1078 Whether an aliased field may be populated by its alias. Defaults to `True`.
1080 Here's an example of disabling validation by alias:
1082 ```py
1083 from pydantic import BaseModel, ConfigDict, Field
1085 class Model(BaseModel):
1086 model_config = ConfigDict(validate_by_name=True, validate_by_alias=False)
1088 my_field: str = Field(validation_alias='my_alias') # (1)!
1090 m = Model(my_field='foo') # (2)!
1091 print(m)
1092 #> my_field='foo'
1093 ```
1095 1. The field `'my_field'` has an alias `'my_alias'`.
1096 2. The model can only be populated by the attribute name `'my_field'`.
1098 !!! warning
1099 You cannot set both `validate_by_alias` and `validate_by_name` to `False`.
1100 This would make it impossible to populate an attribute.
1102 See [usage errors](../errors/usage_errors.md#validate-by-alias-and-name-false) for an example.
1104 If you set `validate_by_alias` to `False`, under the hood, Pydantic dynamically sets
1105 `validate_by_name` to `True` to ensure that validation can still occur.
1107 /// version-added | v2.11
1108 This setting was introduced in conjunction with [`validate_by_name`][pydantic.ConfigDict.validate_by_name]
1109 to empower users with more fine grained validation control.
1110 ///
1111 """
1113 validate_by_name: bool
1114 """
1115 Whether an aliased field may be populated by its name as given by the model
1116 attribute. Defaults to `False`.
1118 ```python
1119 from pydantic import BaseModel, ConfigDict, Field
1121 class Model(BaseModel):
1122 model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
1124 my_field: str = Field(validation_alias='my_alias') # (1)!
1126 m = Model(my_alias='foo') # (2)!
1127 print(m)
1128 #> my_field='foo'
1130 m = Model(my_field='foo') # (3)!
1131 print(m)
1132 #> my_field='foo'
1133 ```
1135 1. The field `'my_field'` has an alias `'my_alias'`.
1136 2. The model is populated by the alias `'my_alias'`.
1137 3. The model is populated by the attribute name `'my_field'`.
1139 !!! warning
1140 You cannot set both `validate_by_alias` and `validate_by_name` to `False`.
1141 This would make it impossible to populate an attribute.
1143 See [usage errors](../errors/usage_errors.md#validate-by-alias-and-name-false) for an example.
1145 /// version-added | v2.11
1146 This setting was introduced in conjunction with [`validate_by_alias`][pydantic.ConfigDict.validate_by_alias]
1147 to empower users with more fine grained validation control. It is an alternative to [`populate_by_name`][pydantic.ConfigDict.populate_by_name],
1148 that enables validation by name **and** by alias.
1149 ///
1150 """
1152 serialize_by_alias: bool
1153 """
1154 Whether an aliased field should be serialized by its alias. Defaults to `False`.
1156 Note: In v2.11, `serialize_by_alias` was introduced to address the
1157 [popular request](https://github.com/pydantic/pydantic/issues/8379)
1158 for consistency with alias behavior for validation and serialization settings.
1159 In v3, the default value is expected to change to `True` for consistency with the validation default.
1161 ```python
1162 from pydantic import BaseModel, ConfigDict, Field
1164 class Model(BaseModel):
1165 model_config = ConfigDict(serialize_by_alias=True)
1167 my_field: str = Field(serialization_alias='my_alias') # (1)!
1169 m = Model(my_field='foo')
1170 print(m.model_dump()) # (2)!
1171 #> {'my_alias': 'foo'}
1172 ```
1174 1. The field `'my_field'` has an alias `'my_alias'`.
1175 2. The model is serialized using the alias `'my_alias'` for the `'my_field'` attribute.
1178 /// version-added | v2.11
1179 This setting was introduced to address the [popular request](https://github.com/pydantic/pydantic/issues/8379)
1180 for consistency with alias behavior for validation and serialization.
1182 In v3, the default value is expected to change to `True` for consistency with the validation default.
1183 ///
1184 """
1186 url_preserve_empty_path: bool
1187 """
1188 Whether to preserve empty URL paths when validating values for a URL type. Defaults to `False`.
1190 ```python
1191 from pydantic import AnyUrl, BaseModel, ConfigDict
1193 class Model(BaseModel):
1194 model_config = ConfigDict(url_preserve_empty_path=True)
1196 url: AnyUrl
1198 m = Model(url='http://example.com')
1199 print(m.url)
1200 #> http://example.com
1201 ```
1203 /// version-added | v2.12
1204 ///
1205 """
1208_TypeT = TypeVar('_TypeT', bound=type)
1211@overload
1212@deprecated('Passing `config` as a keyword argument is deprecated. Pass `config` as a positional argument instead.')
1213def with_config(*, config: ConfigDict) -> Callable[[_TypeT], _TypeT]: ...
1216@overload
1217def with_config(config: ConfigDict, /) -> Callable[[_TypeT], _TypeT]: ...
1220@overload
1221def with_config(**config: Unpack[ConfigDict]) -> Callable[[_TypeT], _TypeT]: ...
1224def with_config(config: ConfigDict | None = None, /, **kwargs: Any) -> Callable[[_TypeT], _TypeT]:
1225 """!!! abstract "Usage Documentation"
1226 [Configuration with other types](../concepts/config.md#configuration-on-other-supported-types)
1228 A convenience decorator to set a [Pydantic configuration](config.md) on a `TypedDict` or a `dataclass` from the standard library.
1230 Although the configuration can be set using the `__pydantic_config__` attribute, it does not play well with type checkers,
1231 especially with `TypedDict`.
1233 !!! example "Usage"
1235 ```python
1236 from typing_extensions import TypedDict
1238 from pydantic import ConfigDict, TypeAdapter, with_config
1240 @with_config(ConfigDict(str_to_lower=True))
1241 class TD(TypedDict):
1242 x: str
1244 ta = TypeAdapter(TD)
1246 print(ta.validate_python({'x': 'ABC'}))
1247 #> {'x': 'abc'}
1248 ```
1250 /// deprecated-removed | v2.11 v3
1251 Passing `config` as a keyword argument.
1252 ///
1254 /// version-changed | v2.11
1255 Keyword arguments can be provided directly instead of a config dictionary.
1256 ///
1257 """
1258 if config is not None and kwargs:
1259 raise ValueError('Cannot specify both `config` and keyword arguments')
1261 if len(kwargs) == 1 and (kwargs_conf := kwargs.get('config')) is not None:
1262 warnings.warn(
1263 'Passing `config` as a keyword argument is deprecated. Pass `config` as a positional argument instead',
1264 category=PydanticDeprecatedSince211,
1265 stacklevel=2,
1266 )
1267 final_config = cast(ConfigDict, kwargs_conf)
1268 else:
1269 final_config = config if config is not None else cast(ConfigDict, kwargs)
1271 def inner(class_: _TypeT, /) -> _TypeT:
1272 # Ideally, we would check for `class_` to either be a `TypedDict` or a stdlib dataclass.
1273 # However, the `@with_config` decorator can be applied *after* `@dataclass`. To avoid
1274 # common mistakes, we at least check for `class_` to not be a Pydantic model.
1275 from ._internal._utils import is_model_class
1277 if is_model_class(class_):
1278 raise PydanticUserError(
1279 f'Cannot use `with_config` on {class_.__name__} as it is a Pydantic model',
1280 code='with-config-on-model',
1281 )
1282 class_.__pydantic_config__ = final_config
1283 return class_
1285 return inner
1288__getattr__ = getattr_migration(__name__)