Coverage for pydantic/fields.py: 98.61%
469 statements
« prev ^ index » next coverage.py v7.8.2, created at 2025-06-11 13:08 +0000
1"""Defining fields on models."""
3from __future__ import annotations as _annotations 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
5import dataclasses 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
6import inspect 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
7import sys 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
8import typing 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
9from collections.abc import Callable, Mapping 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
10from copy import copy 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
11from dataclasses import Field as DataclassField 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
12from functools import cached_property 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
13from typing import Annotated, Any, ClassVar, Literal, TypeVar, cast, overload 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
14from warnings import warn 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
16import annotated_types 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
17import typing_extensions 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
18from pydantic_core import PydanticUndefined 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
19from typing_extensions import TypeAlias, Unpack, deprecated 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
20from typing_inspection import typing_objects 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
21from typing_inspection.introspection import UNKNOWN, AnnotationSource, ForbiddenQualifier, Qualifier, inspect_annotation 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
23from . import types 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
24from ._internal import _decorators, _fields, _generics, _internal_dataclass, _repr, _typing_extra, _utils 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
25from ._internal._namespace_utils import GlobalsNamespace, MappingNamespace 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
26from .aliases import AliasChoices, AliasGenerator, AliasPath 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
27from .config import JsonDict 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
28from .errors import PydanticForbiddenQualifier, PydanticUserError 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
29from .json_schema import PydanticJsonSchemaWarning 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
30from .warnings import PydanticDeprecatedSince20 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
32if typing.TYPE_CHECKING: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
33 from ._internal._config import ConfigWrapper
34 from ._internal._repr import ReprArgs 1p
35else:
36 # See PyCharm issues https://youtrack.jetbrains.com/issue/PY-21915
37 # and https://youtrack.jetbrains.com/issue/PY-51428
38 DeprecationWarning = PydanticDeprecatedSince20 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
40__all__ = 'Field', 'PrivateAttr', 'computed_field' 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
43_Unset: Any = PydanticUndefined 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
45if sys.version_info >= (3, 13): 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
46 import warnings 1abcdefJghi
48 Deprecated: TypeAlias = warnings.deprecated | deprecated 1abcdefJghi
49else:
50 Deprecated: TypeAlias = deprecated 1xyzArsjkqpBCDEtulmFGHIvwno
53class _FromFieldInfoInputs(typing_extensions.TypedDict, total=False): 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
54 """This class exists solely to add type checking for the `**kwargs` in `FieldInfo.from_field`."""
56 # TODO PEP 747: use TypeForm:
57 annotation: type[Any] | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
58 default_factory: Callable[[], Any] | Callable[[dict[str, Any]], Any] | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
59 alias: str | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
60 alias_priority: int | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
61 validation_alias: str | AliasPath | AliasChoices | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
62 serialization_alias: str | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
63 title: str | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
64 field_title_generator: Callable[[str, FieldInfo], str] | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
65 description: str | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
66 examples: list[Any] | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
67 exclude: bool | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
68 gt: annotated_types.SupportsGt | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
69 ge: annotated_types.SupportsGe | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
70 lt: annotated_types.SupportsLt | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
71 le: annotated_types.SupportsLe | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
72 multiple_of: float | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
73 strict: bool | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
74 min_length: int | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
75 max_length: int | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
76 pattern: str | typing.Pattern[str] | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
77 allow_inf_nan: bool | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
78 max_digits: int | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
79 decimal_places: int | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
80 union_mode: Literal['smart', 'left_to_right'] | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
81 discriminator: str | types.Discriminator | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
82 deprecated: Deprecated | str | bool | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
83 json_schema_extra: JsonDict | Callable[[JsonDict], None] | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
84 frozen: bool | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
85 validate_default: bool | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
86 repr: bool 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
87 init: bool | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
88 init_var: bool | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
89 kw_only: bool | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
90 coerce_numbers_to_str: bool | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
91 fail_fast: bool | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
94class _FieldInfoInputs(_FromFieldInfoInputs, total=False): 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
95 """This class exists solely to add type checking for the `**kwargs` in `FieldInfo.__init__`."""
97 default: Any 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
100class FieldInfo(_repr.Representation): 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
101 """This class holds information about a field.
103 `FieldInfo` is used for any field definition regardless of whether the [`Field()`][pydantic.fields.Field]
104 function is explicitly used.
106 !!! warning
107 You generally shouldn't be creating `FieldInfo` directly, you'll only need to use it when accessing
108 [`BaseModel`][pydantic.main.BaseModel] `.model_fields` internals.
110 Attributes:
111 annotation: The type annotation of the field.
112 default: The default value of the field.
113 default_factory: A callable to generate the default value. The callable can either take 0 arguments
114 (in which case it is called as is) or a single argument containing the already validated data.
115 alias: The alias name of the field.
116 alias_priority: The priority of the field's alias.
117 validation_alias: The validation alias of the field.
118 serialization_alias: The serialization alias of the field.
119 title: The title of the field.
120 field_title_generator: A callable that takes a field name and returns title for it.
121 description: The description of the field.
122 examples: List of examples of the field.
123 exclude: Whether to exclude the field from the model serialization.
124 discriminator: Field name or Discriminator for discriminating the type in a tagged union.
125 deprecated: A deprecation message, an instance of `warnings.deprecated` or the `typing_extensions.deprecated` backport,
126 or a boolean. If `True`, a default deprecation message will be emitted when accessing the field.
127 json_schema_extra: A dict or callable to provide extra JSON schema properties.
128 frozen: Whether the field is frozen.
129 validate_default: Whether to validate the default value of the field.
130 repr: Whether to include the field in representation of the model.
131 init: Whether the field should be included in the constructor of the dataclass.
132 init_var: Whether the field should _only_ be included in the constructor of the dataclass, and not stored.
133 kw_only: Whether the field should be a keyword-only argument in the constructor of the dataclass.
134 metadata: List of metadata constraints.
135 """
137 annotation: type[Any] | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
138 default: Any 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
139 default_factory: Callable[[], Any] | Callable[[dict[str, Any]], Any] | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
140 alias: str | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
141 alias_priority: int | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
142 validation_alias: str | AliasPath | AliasChoices | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
143 serialization_alias: str | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
144 title: str | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
145 field_title_generator: Callable[[str, FieldInfo], str] | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
146 description: str | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
147 examples: list[Any] | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
148 exclude: bool | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
149 discriminator: str | types.Discriminator | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
150 deprecated: Deprecated | str | bool | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
151 json_schema_extra: JsonDict | Callable[[JsonDict], None] | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
152 frozen: bool | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
153 validate_default: bool | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
154 repr: bool 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
155 init: bool | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
156 init_var: bool | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
157 kw_only: bool | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
158 metadata: list[Any] 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
160 __slots__ = ( 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
161 'annotation',
162 'default',
163 'default_factory',
164 'alias',
165 'alias_priority',
166 'validation_alias',
167 'serialization_alias',
168 'title',
169 'field_title_generator',
170 'description',
171 'examples',
172 'exclude',
173 'discriminator',
174 'deprecated',
175 'json_schema_extra',
176 'frozen',
177 'validate_default',
178 'repr',
179 'init',
180 'init_var',
181 'kw_only',
182 'metadata',
183 '_attributes_set',
184 '_qualifiers',
185 '_complete',
186 '_original_assignment',
187 '_original_annotation',
188 )
190 # used to convert kwargs to metadata/constraints,
191 # None has a special meaning - these items are collected into a `PydanticGeneralMetadata`
192 metadata_lookup: ClassVar[dict[str, typing.Callable[[Any], Any] | None]] = { 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
193 'strict': types.Strict,
194 'gt': annotated_types.Gt,
195 'ge': annotated_types.Ge,
196 'lt': annotated_types.Lt,
197 'le': annotated_types.Le,
198 'multiple_of': annotated_types.MultipleOf,
199 'min_length': annotated_types.MinLen,
200 'max_length': annotated_types.MaxLen,
201 'pattern': None,
202 'allow_inf_nan': None,
203 'max_digits': None,
204 'decimal_places': None,
205 'union_mode': None,
206 'coerce_numbers_to_str': None,
207 'fail_fast': types.FailFast,
208 }
210 def __init__(self, **kwargs: Unpack[_FieldInfoInputs]) -> None: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
211 """This class should generally not be initialized directly; instead, use the `pydantic.fields.Field` function
212 or one of the constructor classmethods.
214 See the signature of `pydantic.fields.Field` for more details about the expected arguments.
215 """
216 self._attributes_set = {k: v for k, v in kwargs.items() if v is not _Unset} 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
217 kwargs = {k: _DefaultValues.get(k) if v is _Unset else v for k, v in kwargs.items()} # type: ignore 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
218 self.annotation = kwargs.get('annotation') 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
220 default = kwargs.pop('default', PydanticUndefined) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
221 if default is Ellipsis: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
222 self.default = PydanticUndefined 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
223 self._attributes_set.pop('default', None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
224 else:
225 self.default = default 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
227 self.default_factory = kwargs.pop('default_factory', None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
229 if self.default is not PydanticUndefined and self.default_factory is not None: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
230 raise TypeError('cannot specify both default and default_factory') 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
232 self.alias = kwargs.pop('alias', None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
233 self.validation_alias = kwargs.pop('validation_alias', None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
234 self.serialization_alias = kwargs.pop('serialization_alias', None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
235 alias_is_set = any(alias is not None for alias in (self.alias, self.validation_alias, self.serialization_alias)) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
236 self.alias_priority = kwargs.pop('alias_priority', None) or 2 if alias_is_set else None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
237 self.title = kwargs.pop('title', None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
238 self.field_title_generator = kwargs.pop('field_title_generator', None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
239 self.description = kwargs.pop('description', None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
240 self.examples = kwargs.pop('examples', None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
241 self.exclude = kwargs.pop('exclude', None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
242 self.discriminator = kwargs.pop('discriminator', None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
243 # For compatibility with FastAPI<=0.110.0, we preserve the existing value if it is not overridden
244 self.deprecated = kwargs.pop('deprecated', getattr(self, 'deprecated', None)) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
245 self.repr = kwargs.pop('repr', True) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
246 self.json_schema_extra = kwargs.pop('json_schema_extra', None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
247 self.validate_default = kwargs.pop('validate_default', None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
248 self.frozen = kwargs.pop('frozen', None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
249 # currently only used on dataclasses
250 self.init = kwargs.pop('init', None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
251 self.init_var = kwargs.pop('init_var', None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
252 self.kw_only = kwargs.pop('kw_only', None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
254 self.metadata = self._collect_metadata(kwargs) # type: ignore 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
256 # Private attributes:
257 self._qualifiers: set[Qualifier] = set() 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
258 # Used to rebuild FieldInfo instances:
259 self._complete = True 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
260 self._original_annotation: Any = PydanticUndefined 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
261 self._original_assignment: Any = PydanticUndefined 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
263 @staticmethod 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
264 def from_field(default: Any = PydanticUndefined, **kwargs: Unpack[_FromFieldInfoInputs]) -> FieldInfo: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
265 """Create a new `FieldInfo` object with the `Field` function.
267 Args:
268 default: The default value for the field. Defaults to Undefined.
269 **kwargs: Additional arguments dictionary.
271 Raises:
272 TypeError: If 'annotation' is passed as a keyword argument.
274 Returns:
275 A new FieldInfo object with the given parameters.
277 Example:
278 This is how you can create a field with default value like this:
280 ```python
281 import pydantic
283 class MyModel(pydantic.BaseModel):
284 foo: int = pydantic.Field(4)
285 ```
286 """
287 if 'annotation' in kwargs: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
288 raise TypeError('"annotation" is not permitted as a Field keyword argument') 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
289 return FieldInfo(default=default, **kwargs) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
291 @staticmethod 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
292 def from_annotation(annotation: type[Any], *, _source: AnnotationSource = AnnotationSource.ANY) -> FieldInfo: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
293 """Creates a `FieldInfo` instance from a bare annotation.
295 This function is used internally to create a `FieldInfo` from a bare annotation like this:
297 ```python
298 import pydantic
300 class MyModel(pydantic.BaseModel):
301 foo: int # <-- like this
302 ```
304 We also account for the case where the annotation can be an instance of `Annotated` and where
305 one of the (not first) arguments in `Annotated` is an instance of `FieldInfo`, e.g.:
307 ```python
308 from typing import Annotated
310 import annotated_types
312 import pydantic
314 class MyModel(pydantic.BaseModel):
315 foo: Annotated[int, annotated_types.Gt(42)]
316 bar: Annotated[int, pydantic.Field(gt=42)]
317 ```
319 Args:
320 annotation: An annotation object.
322 Returns:
323 An instance of the field metadata.
324 """
325 try: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
326 inspected_ann = inspect_annotation( 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
327 annotation,
328 annotation_source=_source,
329 unpack_type_aliases='skip',
330 )
331 except ForbiddenQualifier as e: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
332 raise PydanticForbiddenQualifier(e.qualifier, annotation) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
334 # TODO check for classvar and error?
336 # No assigned value, this happens when using a bare `Final` qualifier (also for other
337 # qualifiers, but they shouldn't appear here). In this case we infer the type as `Any`
338 # because we don't have any assigned value.
339 type_expr: Any = Any if inspected_ann.type is UNKNOWN else inspected_ann.type 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
340 final = 'final' in inspected_ann.qualifiers 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
341 metadata = inspected_ann.metadata 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
343 if not metadata: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
344 # No metadata, e.g. `field: int`, or `field: Final[str]`:
345 field_info = FieldInfo(annotation=type_expr, frozen=final or None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
346 field_info._qualifiers = inspected_ann.qualifiers 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
347 return field_info 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
349 # With metadata, e.g. `field: Annotated[int, Field(...), Gt(1)]`:
350 field_info_annotations = [a for a in metadata if isinstance(a, FieldInfo)] 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
351 field_info = FieldInfo.merge_field_infos(*field_info_annotations, annotation=type_expr) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
353 new_field_info = copy(field_info) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
354 new_field_info.annotation = type_expr 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
355 new_field_info.frozen = final or field_info.frozen 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
356 field_metadata: list[Any] = [] 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
357 for a in metadata: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
358 if typing_objects.is_deprecated(a): 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
359 new_field_info.deprecated = a.message 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
360 elif not isinstance(a, FieldInfo): 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
361 field_metadata.append(a) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
362 else:
363 field_metadata.extend(a.metadata) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
364 new_field_info.metadata = field_metadata 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
365 new_field_info._qualifiers = inspected_ann.qualifiers 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
366 return new_field_info 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
368 @staticmethod 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
369 def from_annotated_attribute( 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
370 annotation: type[Any], default: Any, *, _source: AnnotationSource = AnnotationSource.ANY
371 ) -> FieldInfo:
372 """Create `FieldInfo` from an annotation with a default value.
374 This is used in cases like the following:
376 ```python
377 from typing import Annotated
379 import annotated_types
381 import pydantic
383 class MyModel(pydantic.BaseModel):
384 foo: int = 4 # <-- like this
385 bar: Annotated[int, annotated_types.Gt(4)] = 4 # <-- or this
386 spam: Annotated[int, pydantic.Field(gt=4)] = 4 # <-- or this
387 ```
389 Args:
390 annotation: The type annotation of the field.
391 default: The default value of the field.
393 Returns:
394 A field object with the passed values.
395 """
396 if annotation is default: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
397 raise PydanticUserError( 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
398 'Error when building FieldInfo from annotated attribute. '
399 "Make sure you don't have any field name clashing with a type annotation.",
400 code='unevaluable-type-annotation',
401 )
403 try: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
404 inspected_ann = inspect_annotation( 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
405 annotation,
406 annotation_source=_source,
407 unpack_type_aliases='skip',
408 )
409 except ForbiddenQualifier as e: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
410 raise PydanticForbiddenQualifier(e.qualifier, annotation) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
412 # TODO check for classvar and error?
414 # TODO infer from the default, this can be done in v3 once we treat final fields with
415 # a default as proper fields and not class variables:
416 type_expr: Any = Any if inspected_ann.type is UNKNOWN else inspected_ann.type 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
417 final = 'final' in inspected_ann.qualifiers 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
418 metadata = inspected_ann.metadata 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
420 if isinstance(default, FieldInfo): 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
421 # e.g. `field: int = Field(...)`
422 default.annotation = type_expr 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
423 default.metadata += metadata 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
424 merged_default = FieldInfo.merge_field_infos( 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
425 *[x for x in metadata if isinstance(x, FieldInfo)],
426 default,
427 annotation=default.annotation,
428 )
429 merged_default.frozen = final or merged_default.frozen 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
430 merged_default._qualifiers = inspected_ann.qualifiers 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
431 return merged_default 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
433 if isinstance(default, dataclasses.Field): 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
434 # `collect_dataclass_fields()` passes the dataclass Field as a default.
435 pydantic_field = FieldInfo._from_dataclass_field(default) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
436 pydantic_field.annotation = type_expr 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
437 pydantic_field.metadata += metadata 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
438 pydantic_field = FieldInfo.merge_field_infos( 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
439 *[x for x in metadata if isinstance(x, FieldInfo)],
440 pydantic_field,
441 annotation=pydantic_field.annotation,
442 )
443 pydantic_field.frozen = final or pydantic_field.frozen 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
444 pydantic_field.init_var = 'init_var' in inspected_ann.qualifiers 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
445 pydantic_field.init = getattr(default, 'init', None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
446 pydantic_field.kw_only = getattr(default, 'kw_only', None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
447 pydantic_field._qualifiers = inspected_ann.qualifiers 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
448 return pydantic_field 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
450 if not metadata: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
451 # No metadata, e.g. `field: int = ...`, or `field: Final[str] = ...`:
452 field_info = FieldInfo(annotation=type_expr, default=default, frozen=final or None) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
453 field_info._qualifiers = inspected_ann.qualifiers 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
454 return field_info 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
456 # With metadata, e.g. `field: Annotated[int, Field(...), Gt(1)] = ...`:
457 field_infos = [a for a in metadata if isinstance(a, FieldInfo)] 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
458 field_info = FieldInfo.merge_field_infos(*field_infos, annotation=type_expr, default=default) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
459 field_metadata: list[Any] = [] 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
460 for a in metadata: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
461 if typing_objects.is_deprecated(a): 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
462 field_info.deprecated = a.message 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
463 elif not isinstance(a, FieldInfo): 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
464 field_metadata.append(a) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
465 else:
466 field_metadata.extend(a.metadata) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
467 field_info.metadata = field_metadata 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
468 field_info._qualifiers = inspected_ann.qualifiers 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
469 return field_info 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
471 @staticmethod 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
472 def merge_field_infos(*field_infos: FieldInfo, **overrides: Any) -> FieldInfo: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
473 """Merge `FieldInfo` instances keeping only explicitly set attributes.
475 Later `FieldInfo` instances override earlier ones.
477 Returns:
478 FieldInfo: A merged FieldInfo instance.
479 """
480 if len(field_infos) == 1: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
481 # No merging necessary, but we still need to make a copy and apply the overrides
482 field_info = copy(field_infos[0]) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
483 field_info._attributes_set.update(overrides) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
485 default_override = overrides.pop('default', PydanticUndefined) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
486 if default_override is Ellipsis: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
487 default_override = PydanticUndefined 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
488 if default_override is not PydanticUndefined: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
489 field_info.default = default_override 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
491 for k, v in overrides.items(): 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
492 setattr(field_info, k, v) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
493 return field_info # type: ignore 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
495 merged_field_info_kwargs: dict[str, Any] = {} 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
496 metadata = {} 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
497 for field_info in field_infos: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
498 attributes_set = field_info._attributes_set.copy() 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
500 try: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
501 json_schema_extra = attributes_set.pop('json_schema_extra') 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
502 existing_json_schema_extra = merged_field_info_kwargs.get('json_schema_extra') 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
504 if existing_json_schema_extra is None: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
505 merged_field_info_kwargs['json_schema_extra'] = json_schema_extra 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
506 if isinstance(existing_json_schema_extra, dict): 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
507 if isinstance(json_schema_extra, dict): 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
508 merged_field_info_kwargs['json_schema_extra'] = { 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
509 **existing_json_schema_extra,
510 **json_schema_extra,
511 }
512 if callable(json_schema_extra): 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
513 warn( 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
514 'Composing `dict` and `callable` type `json_schema_extra` is not supported.'
515 'The `callable` type is being ignored.'
516 "If you'd like support for this behavior, please open an issue on pydantic.",
517 PydanticJsonSchemaWarning,
518 )
519 elif callable(json_schema_extra): 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
520 # if ever there's a case of a callable, we'll just keep the last json schema extra spec
521 merged_field_info_kwargs['json_schema_extra'] = json_schema_extra 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
522 except KeyError: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
523 pass 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
525 # later FieldInfo instances override everything except json_schema_extra from earlier FieldInfo instances
526 merged_field_info_kwargs.update(attributes_set) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
528 for x in field_info.metadata: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
529 if not isinstance(x, FieldInfo): 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
530 metadata[type(x)] = x 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
532 merged_field_info_kwargs.update(overrides) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
533 field_info = FieldInfo(**merged_field_info_kwargs) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
534 field_info.metadata = list(metadata.values()) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
535 return field_info 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
537 @staticmethod 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
538 def _from_dataclass_field(dc_field: DataclassField[Any]) -> FieldInfo: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
539 """Return a new `FieldInfo` instance from a `dataclasses.Field` instance.
541 Args:
542 dc_field: The `dataclasses.Field` instance to convert.
544 Returns:
545 The corresponding `FieldInfo` instance.
547 Raises:
548 TypeError: If any of the `FieldInfo` kwargs does not match the `dataclass.Field` kwargs.
549 """
550 default = dc_field.default 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
551 if default is dataclasses.MISSING: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
552 default = _Unset 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
554 if dc_field.default_factory is dataclasses.MISSING: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
555 default_factory = _Unset 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
556 else:
557 default_factory = dc_field.default_factory 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
559 # use the `Field` function so in correct kwargs raise the correct `TypeError`
560 dc_field_metadata = {k: v for k, v in dc_field.metadata.items() if k in _FIELD_ARG_NAMES} 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
561 return Field(default=default, default_factory=default_factory, repr=dc_field.repr, **dc_field_metadata) # pyright: ignore[reportCallIssue] 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
563 @staticmethod 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
564 def _collect_metadata(kwargs: dict[str, Any]) -> list[Any]: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
565 """Collect annotations from kwargs.
567 Args:
568 kwargs: Keyword arguments passed to the function.
570 Returns:
571 A list of metadata objects - a combination of `annotated_types.BaseMetadata` and
572 `PydanticMetadata`.
573 """
574 metadata: list[Any] = [] 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
575 general_metadata = {} 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
576 for key, value in list(kwargs.items()): 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
577 try: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
578 marker = FieldInfo.metadata_lookup[key] 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
579 except KeyError: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
580 continue 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
582 del kwargs[key] 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
583 if value is not None: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
584 if marker is None: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
585 general_metadata[key] = value 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
586 else:
587 metadata.append(marker(value)) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
588 if general_metadata: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
589 metadata.append(_fields.pydantic_general_metadata(**general_metadata)) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
590 return metadata 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
592 @property 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
593 def deprecation_message(self) -> str | None: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
594 """The deprecation message to be emitted, or `None` if not set."""
595 if self.deprecated is None: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
596 return None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
597 if isinstance(self.deprecated, bool): 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
598 return 'deprecated' if self.deprecated else None 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
599 return self.deprecated if isinstance(self.deprecated, str) else self.deprecated.message 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
601 @property 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
602 def default_factory_takes_validated_data(self) -> bool | None: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
603 """Whether the provided default factory callable has a validated data parameter.
605 Returns `None` if no default factory is set.
606 """
607 if self.default_factory is not None: 607 ↛ exitline 607 didn't return from function 'default_factory_takes_validated_data' because the condition on line 607 was always true1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
608 return _fields.takes_validated_data_argument(self.default_factory) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
610 @overload 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
611 def get_default( 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
612 self, *, call_default_factory: Literal[True], validated_data: dict[str, Any] | None = None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
613 ) -> Any: ... 1jkabcqplmdefJnoghi
615 @overload 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
616 def get_default(self, *, call_default_factory: Literal[False] = ...) -> Any: ... 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
618 def get_default(self, *, call_default_factory: bool = False, validated_data: dict[str, Any] | None = None) -> Any: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
619 """Get the default value.
621 We expose an option for whether to call the default_factory (if present), as calling it may
622 result in side effects that we want to avoid. However, there are times when it really should
623 be called (namely, when instantiating a model via `model_construct`).
625 Args:
626 call_default_factory: Whether to call the default factory or not.
627 validated_data: The already validated data to be passed to the default factory.
629 Returns:
630 The default value, calling the default factory if requested or `None` if not set.
631 """
632 if self.default_factory is None: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
633 return _utils.smart_deepcopy(self.default) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
634 elif call_default_factory: 634 ↛ 646line 634 didn't jump to line 646 because the condition on line 634 was always true1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
635 if self.default_factory_takes_validated_data: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
636 fac = cast('Callable[[dict[str, Any]], Any]', self.default_factory) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
637 if validated_data is None: 637 ↛ 638line 637 didn't jump to line 638 because the condition on line 637 was never true1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
638 raise ValueError(
639 "The default factory requires the 'validated_data' argument, which was not provided when calling 'get_default'."
640 )
641 return fac(validated_data) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
642 else:
643 fac = cast('Callable[[], Any]', self.default_factory) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
644 return fac() 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
645 else:
646 return None
648 def is_required(self) -> bool: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
649 """Check if the field is required (i.e., does not have a default value or factory).
651 Returns:
652 `True` if the field is required, `False` otherwise.
653 """
654 return self.default is PydanticUndefined and self.default_factory is None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
656 def rebuild_annotation(self) -> Any: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
657 """Attempts to rebuild the original annotation for use in function signatures.
659 If metadata is present, it adds it to the original annotation using
660 `Annotated`. Otherwise, it returns the original annotation as-is.
662 Note that because the metadata has been flattened, the original annotation
663 may not be reconstructed exactly as originally provided, e.g. if the original
664 type had unrecognized annotations, or was annotated with a call to `pydantic.Field`.
666 Returns:
667 The rebuilt annotation.
668 """
669 if not self.metadata: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
670 return self.annotation 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
671 else:
672 # Annotated arguments must be a tuple
673 return Annotated[(self.annotation, *self.metadata)] # type: ignore 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
675 def apply_typevars_map( 1xyzArsjkabcBCDEtulmdefJFGHIvwnoghi
676 self,
677 typevars_map: Mapping[TypeVar, Any] | None,
678 globalns: GlobalsNamespace | None = None,
679 localns: MappingNamespace | None = None,
680 ) -> None:
681 """Apply a `typevars_map` to the annotation.
683 This method is used when analyzing parametrized generic types to replace typevars with their concrete types.
685 This method applies the `typevars_map` to the annotation in place.
687 Args:
688 typevars_map: A dictionary mapping type variables to their concrete types.
689 globalns: The globals namespace to use during type annotation evaluation.
690 localns: The locals namespace to use during type annotation evaluation.
692 See Also:
693 pydantic._internal._generics.replace_types is used for replacing the typevars with
694 their concrete types.
695 """
696 annotation = _generics.replace_types(self.annotation, typevars_map) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
697 annotation, evaluated = _typing_extra.try_eval_type(annotation, globalns, localns) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
698 self.annotation = annotation 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
699 if not evaluated: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
700 self._complete = False 1rsjkabctulmdefvwnoghi
701 self._original_annotation = self.annotation 1rsjkabctulmdefvwnoghi
703 def __repr_args__(self) -> ReprArgs: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
704 yield 'annotation', _repr.PlainRepr(_repr.display_as_type(self.annotation)) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
705 yield 'required', self.is_required() 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
707 for s in self.__slots__: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
708 # TODO: properly make use of the protocol (https://rich.readthedocs.io/en/stable/pretty.html#rich-repr-protocol)
709 # By yielding a three-tuple:
710 if s in ( 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
711 'annotation',
712 '_attributes_set',
713 '_qualifiers',
714 '_complete',
715 '_original_assignment',
716 '_original_annotation',
717 ):
718 continue 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
719 elif s == 'metadata' and not self.metadata: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
720 continue 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
721 elif s == 'repr' and self.repr is True: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
722 continue 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
723 if s == 'frozen' and self.frozen is False: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
724 continue 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
725 if s == 'validation_alias' and self.validation_alias == self.alias: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
726 continue 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
727 if s == 'serialization_alias' and self.serialization_alias == self.alias: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
728 continue 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
729 if s == 'default' and self.default is not PydanticUndefined: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
730 yield 'default', self.default 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
731 elif s == 'default_factory' and self.default_factory is not None: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
732 yield 'default_factory', _repr.PlainRepr(_repr.display_as_type(self.default_factory)) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
733 else:
734 value = getattr(self, s) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
735 if value is not None and value is not PydanticUndefined: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
736 yield s, value 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
739class _EmptyKwargs(typing_extensions.TypedDict): 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
740 """This class exists solely to ensure that type checking warns about passing `**extra` in `Field`."""
743_DefaultValues = { 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
744 'default': ...,
745 'default_factory': None,
746 'alias': None,
747 'alias_priority': None,
748 'validation_alias': None,
749 'serialization_alias': None,
750 'title': None,
751 'description': None,
752 'examples': None,
753 'exclude': None,
754 'discriminator': None,
755 'json_schema_extra': None,
756 'frozen': None,
757 'validate_default': None,
758 'repr': True,
759 'init': None,
760 'init_var': None,
761 'kw_only': None,
762 'pattern': None,
763 'strict': None,
764 'gt': None,
765 'ge': None,
766 'lt': None,
767 'le': None,
768 'multiple_of': None,
769 'allow_inf_nan': None,
770 'max_digits': None,
771 'decimal_places': None,
772 'min_length': None,
773 'max_length': None,
774 'coerce_numbers_to_str': None,
775}
778_T = TypeVar('_T') 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
781# NOTE: Actual return type is 'FieldInfo', but we want to help type checkers
782# to understand the magic that happens at runtime with the following overloads:
783@overload # type hint the return value as `Any` to avoid type checking regressions when using `...`. 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
784def Field( 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
785 default: ellipsis, # noqa: F821 # TODO: use `_typing_extra.EllipsisType` when we drop Py3.9 1jkabcqplmdefJnoghi
786 *,
787 alias: str | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
788 alias_priority: int | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
789 validation_alias: str | AliasPath | AliasChoices | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
790 serialization_alias: str | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
791 title: str | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
792 field_title_generator: Callable[[str, FieldInfo], str] | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
793 description: str | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
794 examples: list[Any] | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
795 exclude: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
796 discriminator: str | types.Discriminator | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
797 deprecated: Deprecated | str | bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
798 json_schema_extra: JsonDict | Callable[[JsonDict], None] | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
799 frozen: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
800 validate_default: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
801 repr: bool = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
802 init: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
803 init_var: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
804 kw_only: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
805 pattern: str | typing.Pattern[str] | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
806 strict: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
807 coerce_numbers_to_str: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
808 gt: annotated_types.SupportsGt | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
809 ge: annotated_types.SupportsGe | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
810 lt: annotated_types.SupportsLt | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
811 le: annotated_types.SupportsLe | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
812 multiple_of: float | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
813 allow_inf_nan: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
814 max_digits: int | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
815 decimal_places: int | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
816 min_length: int | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
817 max_length: int | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
818 union_mode: Literal['smart', 'left_to_right'] = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
819 fail_fast: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
820 **extra: Unpack[_EmptyKwargs], 1jkabcqplmdefJnoghi
821) -> Any: ... 1jkabcqplmdefJnoghi
822@overload # `default` argument set 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
823def Field( 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
824 default: _T, 1jkabcqplmdefJnoghi
825 *,
826 alias: str | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
827 alias_priority: int | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
828 validation_alias: str | AliasPath | AliasChoices | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
829 serialization_alias: str | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
830 title: str | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
831 field_title_generator: Callable[[str, FieldInfo], str] | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
832 description: str | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
833 examples: list[Any] | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
834 exclude: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
835 discriminator: str | types.Discriminator | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
836 deprecated: Deprecated | str | bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
837 json_schema_extra: JsonDict | Callable[[JsonDict], None] | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
838 frozen: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
839 validate_default: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
840 repr: bool = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
841 init: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
842 init_var: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
843 kw_only: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
844 pattern: str | typing.Pattern[str] | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
845 strict: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
846 coerce_numbers_to_str: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
847 gt: annotated_types.SupportsGt | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
848 ge: annotated_types.SupportsGe | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
849 lt: annotated_types.SupportsLt | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
850 le: annotated_types.SupportsLe | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
851 multiple_of: float | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
852 allow_inf_nan: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
853 max_digits: int | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
854 decimal_places: int | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
855 min_length: int | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
856 max_length: int | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
857 union_mode: Literal['smart', 'left_to_right'] = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
858 fail_fast: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
859 **extra: Unpack[_EmptyKwargs], 1jkabcqplmdefJnoghi
860) -> _T: ... 1jkabcqplmdefJnoghi
861@overload # `default_factory` argument set 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
862def Field( 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
863 *,
864 default_factory: Callable[[], _T] | Callable[[dict[str, Any]], _T], 1jkabcqplmdefJnoghi
865 alias: str | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
866 alias_priority: int | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
867 validation_alias: str | AliasPath | AliasChoices | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
868 serialization_alias: str | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
869 title: str | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
870 field_title_generator: Callable[[str, FieldInfo], str] | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
871 description: str | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
872 examples: list[Any] | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
873 exclude: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
874 discriminator: str | types.Discriminator | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
875 deprecated: Deprecated | str | bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
876 json_schema_extra: JsonDict | Callable[[JsonDict], None] | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
877 frozen: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
878 validate_default: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
879 repr: bool = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
880 init: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
881 init_var: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
882 kw_only: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
883 pattern: str | typing.Pattern[str] | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
884 strict: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
885 coerce_numbers_to_str: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
886 gt: annotated_types.SupportsGt | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
887 ge: annotated_types.SupportsGe | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
888 lt: annotated_types.SupportsLt | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
889 le: annotated_types.SupportsLe | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
890 multiple_of: float | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
891 allow_inf_nan: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
892 max_digits: int | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
893 decimal_places: int | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
894 min_length: int | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
895 max_length: int | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
896 union_mode: Literal['smart', 'left_to_right'] = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
897 fail_fast: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
898 **extra: Unpack[_EmptyKwargs], 1jkabcqplmdefJnoghi
899) -> _T: ... 1jkabcqplmdefJnoghi
900@overload 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
901def Field( # No default set 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
902 *,
903 alias: str | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
904 alias_priority: int | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
905 validation_alias: str | AliasPath | AliasChoices | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
906 serialization_alias: str | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
907 title: str | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
908 field_title_generator: Callable[[str, FieldInfo], str] | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
909 description: str | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
910 examples: list[Any] | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
911 exclude: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
912 discriminator: str | types.Discriminator | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
913 deprecated: Deprecated | str | bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
914 json_schema_extra: JsonDict | Callable[[JsonDict], None] | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
915 frozen: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
916 validate_default: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
917 repr: bool = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
918 init: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
919 init_var: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
920 kw_only: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
921 pattern: str | typing.Pattern[str] | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
922 strict: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
923 coerce_numbers_to_str: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
924 gt: annotated_types.SupportsGt | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
925 ge: annotated_types.SupportsGe | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
926 lt: annotated_types.SupportsLt | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
927 le: annotated_types.SupportsLe | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
928 multiple_of: float | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
929 allow_inf_nan: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
930 max_digits: int | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
931 decimal_places: int | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
932 min_length: int | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
933 max_length: int | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
934 union_mode: Literal['smart', 'left_to_right'] = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
935 fail_fast: bool | None = _Unset, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
936 **extra: Unpack[_EmptyKwargs], 1jkabcqplmdefJnoghi
937) -> Any: ... 1jkabcqplmdefJnoghi
938def Field( # noqa: C901 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
939 default: Any = PydanticUndefined,
940 *,
941 default_factory: Callable[[], Any] | Callable[[dict[str, Any]], Any] | None = _Unset,
942 alias: str | None = _Unset,
943 alias_priority: int | None = _Unset,
944 validation_alias: str | AliasPath | AliasChoices | None = _Unset,
945 serialization_alias: str | None = _Unset,
946 title: str | None = _Unset,
947 field_title_generator: Callable[[str, FieldInfo], str] | None = _Unset,
948 description: str | None = _Unset,
949 examples: list[Any] | None = _Unset,
950 exclude: bool | None = _Unset,
951 discriminator: str | types.Discriminator | None = _Unset,
952 deprecated: Deprecated | str | bool | None = _Unset,
953 json_schema_extra: JsonDict | Callable[[JsonDict], None] | None = _Unset,
954 frozen: bool | None = _Unset,
955 validate_default: bool | None = _Unset,
956 repr: bool = _Unset,
957 init: bool | None = _Unset,
958 init_var: bool | None = _Unset,
959 kw_only: bool | None = _Unset,
960 pattern: str | typing.Pattern[str] | None = _Unset,
961 strict: bool | None = _Unset,
962 coerce_numbers_to_str: bool | None = _Unset,
963 gt: annotated_types.SupportsGt | None = _Unset,
964 ge: annotated_types.SupportsGe | None = _Unset,
965 lt: annotated_types.SupportsLt | None = _Unset,
966 le: annotated_types.SupportsLe | None = _Unset,
967 multiple_of: float | None = _Unset,
968 allow_inf_nan: bool | None = _Unset,
969 max_digits: int | None = _Unset,
970 decimal_places: int | None = _Unset,
971 min_length: int | None = _Unset,
972 max_length: int | None = _Unset,
973 union_mode: Literal['smart', 'left_to_right'] = _Unset,
974 fail_fast: bool | None = _Unset,
975 **extra: Unpack[_EmptyKwargs],
976) -> Any:
977 """!!! abstract "Usage Documentation"
978 [Fields](../concepts/fields.md)
980 Create a field for objects that can be configured.
982 Used to provide extra information about a field, either for the model schema or complex validation. Some arguments
983 apply only to number fields (`int`, `float`, `Decimal`) and some apply only to `str`.
985 Note:
986 - Any `_Unset` objects will be replaced by the corresponding value defined in the `_DefaultValues` dictionary. If a key for the `_Unset` object is not found in the `_DefaultValues` dictionary, it will default to `None`
988 Args:
989 default: Default value if the field is not set.
990 default_factory: A callable to generate the default value. The callable can either take 0 arguments
991 (in which case it is called as is) or a single argument containing the already validated data.
992 alias: The name to use for the attribute when validating or serializing by alias.
993 This is often used for things like converting between snake and camel case.
994 alias_priority: Priority of the alias. This affects whether an alias generator is used.
995 validation_alias: Like `alias`, but only affects validation, not serialization.
996 serialization_alias: Like `alias`, but only affects serialization, not validation.
997 title: Human-readable title.
998 field_title_generator: A callable that takes a field name and returns title for it.
999 description: Human-readable description.
1000 examples: Example values for this field.
1001 exclude: Whether to exclude the field from the model serialization.
1002 discriminator: Field name or Discriminator for discriminating the type in a tagged union.
1003 deprecated: A deprecation message, an instance of `warnings.deprecated` or the `typing_extensions.deprecated` backport,
1004 or a boolean. If `True`, a default deprecation message will be emitted when accessing the field.
1005 json_schema_extra: A dict or callable to provide extra JSON schema properties.
1006 frozen: Whether the field is frozen. If true, attempts to change the value on an instance will raise an error.
1007 validate_default: If `True`, apply validation to the default value every time you create an instance.
1008 Otherwise, for performance reasons, the default value of the field is trusted and not validated.
1009 repr: A boolean indicating whether to include the field in the `__repr__` output.
1010 init: Whether the field should be included in the constructor of the dataclass.
1011 (Only applies to dataclasses.)
1012 init_var: Whether the field should _only_ be included in the constructor of the dataclass.
1013 (Only applies to dataclasses.)
1014 kw_only: Whether the field should be a keyword-only argument in the constructor of the dataclass.
1015 (Only applies to dataclasses.)
1016 coerce_numbers_to_str: Whether to enable coercion of any `Number` type to `str` (not applicable in `strict` mode).
1017 strict: If `True`, strict validation is applied to the field.
1018 See [Strict Mode](../concepts/strict_mode.md) for details.
1019 gt: Greater than. If set, value must be greater than this. Only applicable to numbers.
1020 ge: Greater than or equal. If set, value must be greater than or equal to this. Only applicable to numbers.
1021 lt: Less than. If set, value must be less than this. Only applicable to numbers.
1022 le: Less than or equal. If set, value must be less than or equal to this. Only applicable to numbers.
1023 multiple_of: Value must be a multiple of this. Only applicable to numbers.
1024 min_length: Minimum length for iterables.
1025 max_length: Maximum length for iterables.
1026 pattern: Pattern for strings (a regular expression).
1027 allow_inf_nan: Allow `inf`, `-inf`, `nan`. Only applicable to float and [`Decimal`][decimal.Decimal] numbers.
1028 max_digits: Maximum number of allow digits for strings.
1029 decimal_places: Maximum number of decimal places allowed for numbers.
1030 union_mode: The strategy to apply when validating a union. Can be `smart` (the default), or `left_to_right`.
1031 See [Union Mode](../concepts/unions.md#union-modes) for details.
1032 fail_fast: If `True`, validation will stop on the first error. If `False`, all validation errors will be collected.
1033 This option can be applied only to iterable types (list, tuple, set, and frozenset).
1034 extra: (Deprecated) Extra fields that will be included in the JSON schema.
1036 !!! warning Deprecated
1037 The `extra` kwargs is deprecated. Use `json_schema_extra` instead.
1039 Returns:
1040 A new [`FieldInfo`][pydantic.fields.FieldInfo]. The return annotation is `Any` so `Field` can be used on
1041 type-annotated fields without causing a type error.
1042 """
1043 # Check deprecated and removed params from V1. This logic should eventually be removed.
1044 const = extra.pop('const', None) # type: ignore 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1045 if const is not None: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1046 raise PydanticUserError('`const` is removed, use `Literal` instead', code='removed-kwargs') 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1048 min_items = extra.pop('min_items', None) # type: ignore 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1049 if min_items is not None: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1050 warn('`min_items` is deprecated and will be removed, use `min_length` instead', DeprecationWarning) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1051 if min_length in (None, _Unset): 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1052 min_length = min_items # type: ignore 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1054 max_items = extra.pop('max_items', None) # type: ignore 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1055 if max_items is not None: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1056 warn('`max_items` is deprecated and will be removed, use `max_length` instead', DeprecationWarning) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1057 if max_length in (None, _Unset): 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1058 max_length = max_items # type: ignore 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1060 unique_items = extra.pop('unique_items', None) # type: ignore 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1061 if unique_items is not None: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1062 raise PydanticUserError( 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1063 (
1064 '`unique_items` is removed, use `Set` instead'
1065 '(this feature is discussed in https://github.com/pydantic/pydantic-core/issues/296)'
1066 ),
1067 code='removed-kwargs',
1068 )
1070 allow_mutation = extra.pop('allow_mutation', None) # type: ignore 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1071 if allow_mutation is not None: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1072 warn('`allow_mutation` is deprecated and will be removed. use `frozen` instead', DeprecationWarning) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1073 if allow_mutation is False: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1074 frozen = True 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1076 regex = extra.pop('regex', None) # type: ignore 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1077 if regex is not None: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1078 raise PydanticUserError('`regex` is removed. use `pattern` instead', code='removed-kwargs') 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1080 if extra: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1081 warn( 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1082 'Using extra keyword arguments on `Field` is deprecated and will be removed.'
1083 ' Use `json_schema_extra` instead.'
1084 f' (Extra keys: {", ".join(k.__repr__() for k in extra.keys())})',
1085 DeprecationWarning,
1086 )
1087 if not json_schema_extra or json_schema_extra is _Unset: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1088 json_schema_extra = extra # type: ignore 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1090 if ( 1xyzArsqpBCDEtuFGHIvw
1091 validation_alias
1092 and validation_alias is not _Unset
1093 and not isinstance(validation_alias, (str, AliasChoices, AliasPath))
1094 ):
1095 raise TypeError('Invalid `validation_alias` type. it should be `str`, `AliasChoices`, or `AliasPath`') 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1097 if serialization_alias in (_Unset, None) and isinstance(alias, str): 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1098 serialization_alias = alias 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1100 if validation_alias in (_Unset, None): 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1101 validation_alias = alias 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1103 include = extra.pop('include', None) # type: ignore 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1104 if include is not None: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1105 warn('`include` is deprecated and does nothing. It will be removed, use `exclude` instead', DeprecationWarning) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1107 return FieldInfo.from_field( 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1108 default,
1109 default_factory=default_factory,
1110 alias=alias,
1111 alias_priority=alias_priority,
1112 validation_alias=validation_alias,
1113 serialization_alias=serialization_alias,
1114 title=title,
1115 field_title_generator=field_title_generator,
1116 description=description,
1117 examples=examples,
1118 exclude=exclude,
1119 discriminator=discriminator,
1120 deprecated=deprecated,
1121 json_schema_extra=json_schema_extra,
1122 frozen=frozen,
1123 pattern=pattern,
1124 validate_default=validate_default,
1125 repr=repr,
1126 init=init,
1127 init_var=init_var,
1128 kw_only=kw_only,
1129 coerce_numbers_to_str=coerce_numbers_to_str,
1130 strict=strict,
1131 gt=gt,
1132 ge=ge,
1133 lt=lt,
1134 le=le,
1135 multiple_of=multiple_of,
1136 min_length=min_length,
1137 max_length=max_length,
1138 allow_inf_nan=allow_inf_nan,
1139 max_digits=max_digits,
1140 decimal_places=decimal_places,
1141 union_mode=union_mode,
1142 fail_fast=fail_fast,
1143 )
1146_FIELD_ARG_NAMES = set(inspect.signature(Field).parameters) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1147_FIELD_ARG_NAMES.remove('extra') # do not include the varkwargs parameter 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1150class ModelPrivateAttr(_repr.Representation): 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1151 """A descriptor for private attributes in class models.
1153 !!! warning
1154 You generally shouldn't be creating `ModelPrivateAttr` instances directly, instead use
1155 `pydantic.fields.PrivateAttr`. (This is similar to `FieldInfo` vs. `Field`.)
1157 Attributes:
1158 default: The default value of the attribute if not provided.
1159 default_factory: A callable function that generates the default value of the
1160 attribute if not provided.
1161 """
1163 __slots__ = ('default', 'default_factory') 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1165 def __init__( 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1166 self, default: Any = PydanticUndefined, *, default_factory: typing.Callable[[], Any] | None = None
1167 ) -> None:
1168 if default is Ellipsis: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1169 self.default = PydanticUndefined 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1170 else:
1171 self.default = default 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1172 self.default_factory = default_factory 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1174 if not typing.TYPE_CHECKING: 1174 ↛ 1186line 1174 didn't jump to line 1186 because the condition on line 1174 was always true1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1175 # We put `__getattr__` in a non-TYPE_CHECKING block because otherwise, mypy allows arbitrary attribute access
1177 def __getattr__(self, item: str) -> Any: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1178 """This function improves compatibility with custom descriptors by ensuring delegation happens
1179 as expected when the default value of a private attribute is a descriptor.
1180 """
1181 if item in {'__get__', '__set__', '__delete__'}: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1182 if hasattr(self.default, item): 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1183 return getattr(self.default, item) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1184 raise AttributeError(f'{type(self).__name__!r} object has no attribute {item!r}') 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1186 def __set_name__(self, cls: type[Any], name: str) -> None: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1187 """Preserve `__set_name__` protocol defined in https://peps.python.org/pep-0487."""
1188 default = self.default 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1189 if default is PydanticUndefined: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1190 return 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1191 set_name = getattr(default, '__set_name__', None) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1192 if callable(set_name): 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1193 set_name(cls, name) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1195 def get_default(self) -> Any: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1196 """Retrieve the default value of the object.
1198 If `self.default_factory` is `None`, the method will return a deep copy of the `self.default` object.
1200 If `self.default_factory` is not `None`, it will call `self.default_factory` and return the value returned.
1202 Returns:
1203 The default value of the object.
1204 """
1205 return _utils.smart_deepcopy(self.default) if self.default_factory is None else self.default_factory() 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1207 def __eq__(self, other: Any) -> bool: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1208 return isinstance(other, self.__class__) and (self.default, self.default_factory) == ( 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1209 other.default,
1210 other.default_factory,
1211 )
1214# NOTE: Actual return type is 'ModelPrivateAttr', but we want to help type checkers
1215# to understand the magic that happens at runtime.
1216@overload # `default` argument set 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1217def PrivateAttr( 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1218 default: _T, 1jkabcqplmdefJnoghi
1219 *,
1220 init: Literal[False] = False, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1221) -> _T: ... 1jkabcqplmdefJnoghi
1222@overload # `default_factory` argument set 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1223def PrivateAttr( 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1224 *,
1225 default_factory: Callable[[], _T], 1jkabcqplmdefJnoghi
1226 init: Literal[False] = False, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1227) -> _T: ... 1jkabcqplmdefJnoghi
1228@overload # No default set 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1229def PrivateAttr( 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1230 *,
1231 init: Literal[False] = False, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1232) -> Any: ... 1jkabcqplmdefJnoghi
1233def PrivateAttr( 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1234 default: Any = PydanticUndefined,
1235 *,
1236 default_factory: Callable[[], Any] | None = None,
1237 init: Literal[False] = False,
1238) -> Any:
1239 """!!! abstract "Usage Documentation"
1240 [Private Model Attributes](../concepts/models.md#private-model-attributes)
1242 Indicates that an attribute is intended for private use and not handled during normal validation/serialization.
1244 Private attributes are not validated by Pydantic, so it's up to you to ensure they are used in a type-safe manner.
1246 Private attributes are stored in `__private_attributes__` on the model.
1248 Args:
1249 default: The attribute's default value. Defaults to Undefined.
1250 default_factory: Callable that will be
1251 called when a default value is needed for this attribute.
1252 If both `default` and `default_factory` are set, an error will be raised.
1253 init: Whether the attribute should be included in the constructor of the dataclass. Always `False`.
1255 Returns:
1256 An instance of [`ModelPrivateAttr`][pydantic.fields.ModelPrivateAttr] class.
1258 Raises:
1259 ValueError: If both `default` and `default_factory` are set.
1260 """
1261 if default is not PydanticUndefined and default_factory is not None: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1262 raise TypeError('cannot specify both default and default_factory') 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1264 return ModelPrivateAttr( 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1265 default,
1266 default_factory=default_factory,
1267 )
1270@dataclasses.dataclass(**_internal_dataclass.slots_true) 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1271class ComputedFieldInfo: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1272 """A container for data from `@computed_field` so that we can access it while building the pydantic-core schema.
1274 Attributes:
1275 decorator_repr: A class variable representing the decorator string, '@computed_field'.
1276 wrapped_property: The wrapped computed field property.
1277 return_type: The type of the computed field property's return value.
1278 alias: The alias of the property to be used during serialization.
1279 alias_priority: The priority of the alias. This affects whether an alias generator is used.
1280 title: Title of the computed field to include in the serialization JSON schema.
1281 field_title_generator: A callable that takes a field name and returns title for it.
1282 description: Description of the computed field to include in the serialization JSON schema.
1283 deprecated: A deprecation message, an instance of `warnings.deprecated` or the `typing_extensions.deprecated` backport,
1284 or a boolean. If `True`, a default deprecation message will be emitted when accessing the field.
1285 examples: Example values of the computed field to include in the serialization JSON schema.
1286 json_schema_extra: A dict or callable to provide extra JSON schema properties.
1287 repr: A boolean indicating whether to include the field in the __repr__ output.
1288 """
1290 decorator_repr: ClassVar[str] = '@computed_field' 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1291 wrapped_property: property 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1292 return_type: Any 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1293 alias: str | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1294 alias_priority: int | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1295 title: str | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1296 field_title_generator: Callable[[str, ComputedFieldInfo], str] | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1297 description: str | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1298 deprecated: Deprecated | str | bool | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1299 examples: list[Any] | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1300 json_schema_extra: JsonDict | Callable[[JsonDict], None] | None 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1301 repr: bool 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1303 @property 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1304 def deprecation_message(self) -> str | None: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1305 """The deprecation message to be emitted, or `None` if not set."""
1306 if self.deprecated is None: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1307 return None 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1308 if isinstance(self.deprecated, bool): 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1309 return 'deprecated' if self.deprecated else None 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1310 return self.deprecated if isinstance(self.deprecated, str) else self.deprecated.message 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1312 def _update_from_config(self, config_wrapper: ConfigWrapper, name: str) -> None: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1313 """Update the instance from the configuration set on the class this computed field belongs to."""
1314 title_generator = self.field_title_generator or config_wrapper.field_title_generator 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1315 if title_generator is not None and self.title is None: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1316 self.title = title_generator(name, self) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1317 if config_wrapper.alias_generator is not None: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1318 self._apply_alias_generator(config_wrapper.alias_generator, name) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1320 def _apply_alias_generator(self, alias_generator: Callable[[str], str] | AliasGenerator, name: str) -> None: 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1321 """Apply an alias generator to aliases if appropriate.
1323 Args:
1324 alias_generator: A callable that takes a string and returns a string, or an `AliasGenerator` instance.
1325 name: The name of the computed field from which to generate the alias.
1326 """
1327 # Apply an alias_generator if
1328 # 1. An alias is not specified
1329 # 2. An alias is specified, but the priority is <= 1
1331 if self.alias_priority is None or self.alias_priority <= 1 or self.alias is None: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1332 alias, _, serialization_alias = None, None, None 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1334 if isinstance(alias_generator, AliasGenerator): 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1335 alias, _, serialization_alias = alias_generator.generate_aliases(name) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1336 elif callable(alias_generator): 1336 ↛ 1342line 1336 didn't jump to line 1342 because the condition on line 1336 was always true1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1337 alias = alias_generator(name) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1339 # if priority is not set, we set to 1
1340 # which supports the case where the alias_generator from a child class is used
1341 # to generate an alias for a field in a parent class
1342 if self.alias_priority is None or self.alias_priority <= 1: 1342 ↛ 1348line 1342 didn't jump to line 1348 because the condition on line 1342 was always true1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1343 self.alias_priority = 1 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1345 # if the priority is 1, then we set the aliases to the generated alias
1346 # note that we use the serialization_alias with priority over alias, as computed_field
1347 # aliases are used for serialization only (not validation)
1348 if self.alias_priority == 1: 1348 ↛ exitline 1348 didn't return from function '_apply_alias_generator' because the condition on line 1348 was always true1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1349 self.alias = _utils.get_first_not_none(serialization_alias, alias) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1352def _wrapped_property_is_private(property_: cached_property | property) -> bool: # type: ignore 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1353 """Returns true if provided property is private, False otherwise."""
1354 wrapped_name: str = '' 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1356 if isinstance(property_, property): 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1357 wrapped_name = getattr(property_.fget, '__name__', '') 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1358 elif isinstance(property_, cached_property): # type: ignore 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1359 wrapped_name = getattr(property_.func, '__name__', '') # type: ignore 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1361 return wrapped_name.startswith('_') and not wrapped_name.startswith('__') 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1364# this should really be `property[T], cached_property[T]` but property is not generic unlike cached_property
1365# See https://github.com/python/typing/issues/985 and linked issues
1366PropertyT = typing.TypeVar('PropertyT') 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1369@typing.overload 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1370def computed_field(func: PropertyT, /) -> PropertyT: ... 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1373@typing.overload 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1374def computed_field( 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1375 *,
1376 alias: str | None = None, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1377 alias_priority: int | None = None, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1378 title: str | None = None, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1379 field_title_generator: typing.Callable[[str, ComputedFieldInfo], str] | None = None, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1380 description: str | None = None, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1381 deprecated: Deprecated | str | bool | None = None, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1382 examples: list[Any] | None = None, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1383 json_schema_extra: JsonDict | typing.Callable[[JsonDict], None] | None = None, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1384 repr: bool = True, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1385 return_type: Any = PydanticUndefined, 1xyzArsjkabcqpBCDEtulmdefJFGHIvwnoghi
1386) -> typing.Callable[[PropertyT], PropertyT]: ... 1jkabcqplmdefJnoghi
1389def computed_field( 1xyzArsjkabcBCDEtulmdefJFGHIvwnoghi
1390 func: PropertyT | None = None,
1391 /,
1392 *,
1393 alias: str | None = None,
1394 alias_priority: int | None = None,
1395 title: str | None = None,
1396 field_title_generator: typing.Callable[[str, ComputedFieldInfo], str] | None = None,
1397 description: str | None = None,
1398 deprecated: Deprecated | str | bool | None = None,
1399 examples: list[Any] | None = None,
1400 json_schema_extra: JsonDict | typing.Callable[[JsonDict], None] | None = None,
1401 repr: bool | None = None,
1402 return_type: Any = PydanticUndefined,
1403) -> PropertyT | typing.Callable[[PropertyT], PropertyT]:
1404 """!!! abstract "Usage Documentation"
1405 [The `computed_field` decorator](../concepts/fields.md#the-computed_field-decorator)
1407 Decorator to include `property` and `cached_property` when serializing models or dataclasses.
1409 This is useful for fields that are computed from other fields, or for fields that are expensive to compute and should be cached.
1411 ```python
1412 from pydantic import BaseModel, computed_field
1414 class Rectangle(BaseModel):
1415 width: int
1416 length: int
1418 @computed_field
1419 @property
1420 def area(self) -> int:
1421 return self.width * self.length
1423 print(Rectangle(width=3, length=2).model_dump())
1424 #> {'width': 3, 'length': 2, 'area': 6}
1425 ```
1427 If applied to functions not yet decorated with `@property` or `@cached_property`, the function is
1428 automatically wrapped with `property`. Although this is more concise, you will lose IntelliSense in your IDE,
1429 and confuse static type checkers, thus explicit use of `@property` is recommended.
1431 !!! warning "Mypy Warning"
1432 Even with the `@property` or `@cached_property` applied to your function before `@computed_field`,
1433 mypy may throw a `Decorated property not supported` error.
1434 See [mypy issue #1362](https://github.com/python/mypy/issues/1362), for more information.
1435 To avoid this error message, add `# type: ignore[prop-decorator]` to the `@computed_field` line.
1437 [pyright](https://github.com/microsoft/pyright) supports `@computed_field` without error.
1439 ```python
1440 import random
1442 from pydantic import BaseModel, computed_field
1444 class Square(BaseModel):
1445 width: float
1447 @computed_field
1448 def area(self) -> float: # converted to a `property` by `computed_field`
1449 return round(self.width**2, 2)
1451 @area.setter
1452 def area(self, new_area: float) -> None:
1453 self.width = new_area**0.5
1455 @computed_field(alias='the magic number', repr=False)
1456 def random_number(self) -> int:
1457 return random.randint(0, 1_000)
1459 square = Square(width=1.3)
1461 # `random_number` does not appear in representation
1462 print(repr(square))
1463 #> Square(width=1.3, area=1.69)
1465 print(square.random_number)
1466 #> 3
1468 square.area = 4
1470 print(square.model_dump_json(by_alias=True))
1471 #> {"width":2.0,"area":4.0,"the magic number":3}
1472 ```
1474 !!! warning "Overriding with `computed_field`"
1475 You can't override a field from a parent class with a `computed_field` in the child class.
1476 `mypy` complains about this behavior if allowed, and `dataclasses` doesn't allow this pattern either.
1477 See the example below:
1479 ```python
1480 from pydantic import BaseModel, computed_field
1482 class Parent(BaseModel):
1483 a: str
1485 try:
1487 class Child(Parent):
1488 @computed_field
1489 @property
1490 def a(self) -> str:
1491 return 'new a'
1493 except TypeError as e:
1494 print(e)
1495 '''
1496 Field 'a' of class 'Child' overrides symbol of same name in a parent class. This override with a computed_field is incompatible.
1497 '''
1498 ```
1500 Private properties decorated with `@computed_field` have `repr=False` by default.
1502 ```python
1503 from functools import cached_property
1505 from pydantic import BaseModel, computed_field
1507 class Model(BaseModel):
1508 foo: int
1510 @computed_field
1511 @cached_property
1512 def _private_cached_property(self) -> int:
1513 return -self.foo
1515 @computed_field
1516 @property
1517 def _private_property(self) -> int:
1518 return -self.foo
1520 m = Model(foo=1)
1521 print(repr(m))
1522 #> Model(foo=1)
1523 ```
1525 Args:
1526 func: the function to wrap.
1527 alias: alias to use when serializing this computed field, only used when `by_alias=True`
1528 alias_priority: priority of the alias. This affects whether an alias generator is used
1529 title: Title to use when including this computed field in JSON Schema
1530 field_title_generator: A callable that takes a field name and returns title for it.
1531 description: Description to use when including this computed field in JSON Schema, defaults to the function's
1532 docstring
1533 deprecated: A deprecation message (or an instance of `warnings.deprecated` or the `typing_extensions.deprecated` backport).
1534 to be emitted when accessing the field. Or a boolean. This will automatically be set if the property is decorated with the
1535 `deprecated` decorator.
1536 examples: Example values to use when including this computed field in JSON Schema
1537 json_schema_extra: A dict or callable to provide extra JSON schema properties.
1538 repr: whether to include this computed field in model repr.
1539 Default is `False` for private properties and `True` for public properties.
1540 return_type: optional return for serialization logic to expect when serializing to JSON, if included
1541 this must be correct, otherwise a `TypeError` is raised.
1542 If you don't include a return type Any is used, which does runtime introspection to handle arbitrary
1543 objects.
1545 Returns:
1546 A proxy wrapper for the property.
1547 """
1549 def dec(f: Any) -> Any: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1550 nonlocal description, deprecated, return_type, alias_priority
1551 unwrapped = _decorators.unwrap_wrapped_function(f) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1553 if description is None and unwrapped.__doc__: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1554 description = inspect.cleandoc(unwrapped.__doc__) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1556 if deprecated is None and hasattr(unwrapped, '__deprecated__'): 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1557 deprecated = unwrapped.__deprecated__ 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1559 # if the function isn't already decorated with `@property` (or another descriptor), then we wrap it now
1560 f = _decorators.ensure_property(f) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1561 alias_priority = (alias_priority or 2) if alias is not None else None 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1563 if repr is None: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1564 repr_: bool = not _wrapped_property_is_private(property_=f) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1565 else:
1566 repr_ = repr 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1568 dec_info = ComputedFieldInfo( 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1569 f,
1570 return_type,
1571 alias,
1572 alias_priority,
1573 title,
1574 field_title_generator,
1575 description,
1576 deprecated,
1577 examples,
1578 json_schema_extra,
1579 repr_,
1580 )
1581 return _decorators.PydanticDescriptorProxy(f, dec_info) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1583 if func is None: 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1584 return dec 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi
1585 else:
1586 return dec(func) 1xyzArsjkabcqpBCDEtulmdefFGHIvwnoghi