Coverage for pydantic/type_adapter.py: 89.16%
159 statements
« prev ^ index » next coverage.py v7.8.0, created at 2025-05-02 08:21 +0000
1"""Type adapter specification."""
3from __future__ import annotations as _annotations 1rstuvwabcdefgxyzABChijklDEFGHImnopq
5import sys 1rstuvwabcdefgxyzABChijklDEFGHImnopq
6from collections.abc import Callable, Iterable 1rstuvwabcdefgxyzABChijklDEFGHImnopq
7from dataclasses import is_dataclass 1rstuvwabcdefgxyzABChijklDEFGHImnopq
8from types import FrameType 1rstuvwabcdefgxyzABChijklDEFGHImnopq
9from typing import ( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
10 Any,
11 Generic,
12 Literal,
13 TypeVar,
14 cast,
15 final,
16 overload,
17)
19from pydantic_core import CoreSchema, SchemaSerializer, SchemaValidator, Some 1rstuvwabcdefgxyzABChijklDEFGHImnopq
20from typing_extensions import ParamSpec, is_typeddict 1rstuvwabcdefgxyzABChijklDEFGHImnopq
22from pydantic.errors import PydanticUserError 1rstuvwabcdefgxyzABChijklDEFGHImnopq
23from pydantic.main import BaseModel, IncEx 1rstuvwabcdefgxyzABChijklDEFGHImnopq
25from ._internal import _config, _generate_schema, _mock_val_ser, _namespace_utils, _repr, _typing_extra, _utils 1rstuvwabcdefgxyzABChijklDEFGHImnopq
26from .config import ConfigDict 1rstuvwabcdefgxyzABChijklDEFGHImnopq
27from .errors import PydanticUndefinedAnnotation 1rstuvwabcdefgxyzABChijklDEFGHImnopq
28from .json_schema import ( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
29 DEFAULT_REF_TEMPLATE,
30 GenerateJsonSchema,
31 JsonSchemaKeyT,
32 JsonSchemaMode,
33 JsonSchemaValue,
34)
35from .plugin._schema_validator import PluggableSchemaValidator, create_schema_validator 1rstuvwabcdefgxyzABChijklDEFGHImnopq
37T = TypeVar('T') 1rstuvwabcdefgxyzABChijklDEFGHImnopq
38R = TypeVar('R') 1rstuvwabcdefgxyzABChijklDEFGHImnopq
39P = ParamSpec('P') 1rstuvwabcdefgxyzABChijklDEFGHImnopq
40TypeAdapterT = TypeVar('TypeAdapterT', bound='TypeAdapter') 1rstuvwabcdefgxyzABChijklDEFGHImnopq
43def _getattr_no_parents(obj: Any, attribute: str) -> Any: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
44 """Returns the attribute value without attempting to look up attributes from parent types."""
45 if hasattr(obj, '__dict__'): 1rstuvwabcdefgxyzABChijklDEFGHImnopq
46 try: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
47 return obj.__dict__[attribute] 1rstuvwabcdefgxyzABChijklDEFGHImnopq
48 except KeyError: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
49 pass 1rstuvwabcdefgxyzABChijklDEFGHImnopq
51 slots = getattr(obj, '__slots__', None) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
52 if slots is not None and attribute in slots: 52 ↛ 53line 52 didn't jump to line 53 because the condition on line 52 was never true1rstuvwabcdefgxyzABChijklDEFGHImnopq
53 return getattr(obj, attribute)
54 else:
55 raise AttributeError(attribute) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
58def _type_has_config(type_: Any) -> bool: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
59 """Returns whether the type has config."""
60 type_ = _typing_extra.annotated_type(type_) or type_ 1rstuvwabcdefgxyzABChijklDEFGHImnopq
61 try: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
62 return issubclass(type_, BaseModel) or is_dataclass(type_) or is_typeddict(type_) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
63 except TypeError:
64 # type is not a class
65 return False
68@final 1rstuvwabcdefgxyzABChijklDEFGHImnopq
69class TypeAdapter(Generic[T]): 1rstuvwabcdefgxyzABChijklDEFGHImnopq
70 """!!! abstract "Usage Documentation"
71 [`TypeAdapter`](../concepts/type_adapter.md)
73 Type adapters provide a flexible way to perform validation and serialization based on a Python type.
75 A `TypeAdapter` instance exposes some of the functionality from `BaseModel` instance methods
76 for types that do not have such methods (such as dataclasses, primitive types, and more).
78 **Note:** `TypeAdapter` instances are not types, and cannot be used as type annotations for fields.
80 Args:
81 type: The type associated with the `TypeAdapter`.
82 config: Configuration for the `TypeAdapter`, should be a dictionary conforming to
83 [`ConfigDict`][pydantic.config.ConfigDict].
85 !!! note
86 You cannot provide a configuration when instantiating a `TypeAdapter` if the type you're using
87 has its own config that cannot be overridden (ex: `BaseModel`, `TypedDict`, and `dataclass`). A
88 [`type-adapter-config-unused`](../errors/usage_errors.md#type-adapter-config-unused) error will
89 be raised in this case.
90 _parent_depth: Depth at which to search for the [parent frame][frame-objects]. This frame is used when
91 resolving forward annotations during schema building, by looking for the globals and locals of this
92 frame. Defaults to 2, which will result in the frame where the `TypeAdapter` was instantiated.
94 !!! note
95 This parameter is named with an underscore to suggest its private nature and discourage use.
96 It may be deprecated in a minor version, so we only recommend using it if you're comfortable
97 with potential change in behavior/support. It's default value is 2 because internally,
98 the `TypeAdapter` class makes another call to fetch the frame.
99 module: The module that passes to plugin if provided.
101 Attributes:
102 core_schema: The core schema for the type.
103 validator: The schema validator for the type.
104 serializer: The schema serializer for the type.
105 pydantic_complete: Whether the core schema for the type is successfully built.
107 ??? tip "Compatibility with `mypy`"
108 Depending on the type used, `mypy` might raise an error when instantiating a `TypeAdapter`. As a workaround, you can explicitly
109 annotate your variable:
111 ```py
112 from typing import Union
114 from pydantic import TypeAdapter
116 ta: TypeAdapter[Union[str, int]] = TypeAdapter(Union[str, int]) # type: ignore[arg-type]
117 ```
119 ??? info "Namespace management nuances and implementation details"
121 Here, we collect some notes on namespace management, and subtle differences from `BaseModel`:
123 `BaseModel` uses its own `__module__` to find out where it was defined
124 and then looks for symbols to resolve forward references in those globals.
125 On the other hand, `TypeAdapter` can be initialized with arbitrary objects,
126 which may not be types and thus do not have a `__module__` available.
127 So instead we look at the globals in our parent stack frame.
129 It is expected that the `ns_resolver` passed to this function will have the correct
130 namespace for the type we're adapting. See the source code for `TypeAdapter.__init__`
131 and `TypeAdapter.rebuild` for various ways to construct this namespace.
133 This works for the case where this function is called in a module that
134 has the target of forward references in its scope, but
135 does not always work for more complex cases.
137 For example, take the following:
139 ```python {title="a.py"}
140 IntList = list[int]
141 OuterDict = dict[str, 'IntList']
142 ```
144 ```python {test="skip" title="b.py"}
145 from a import OuterDict
147 from pydantic import TypeAdapter
149 IntList = int # replaces the symbol the forward reference is looking for
150 v = TypeAdapter(OuterDict)
151 v({'x': 1}) # should fail but doesn't
152 ```
154 If `OuterDict` were a `BaseModel`, this would work because it would resolve
155 the forward reference within the `a.py` namespace.
156 But `TypeAdapter(OuterDict)` can't determine what module `OuterDict` came from.
158 In other words, the assumption that _all_ forward references exist in the
159 module we are being called from is not technically always true.
160 Although most of the time it is and it works fine for recursive models and such,
161 `BaseModel`'s behavior isn't perfect either and _can_ break in similar ways,
162 so there is no right or wrong between the two.
164 But at the very least this behavior is _subtly_ different from `BaseModel`'s.
165 """
167 core_schema: CoreSchema 1rstuvwabcdefgxyzABChijklDEFGHImnopq
168 validator: SchemaValidator | PluggableSchemaValidator 1rstuvwabcdefgxyzABChijklDEFGHImnopq
169 serializer: SchemaSerializer 1rstuvwabcdefgxyzABChijklDEFGHImnopq
170 pydantic_complete: bool 1rstuvwabcdefgxyzABChijklDEFGHImnopq
172 @overload 1rstuvwabcdefgxyzABChijklDEFGHImnopq
173 def __init__( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
174 self,
175 type: type[T], 1abcdefghijklmnopq
176 *,
177 config: ConfigDict | None = ..., 1rstuvwabcdefgxyzABChijklDEFGHImnopq
178 _parent_depth: int = ..., 1rstuvwabcdefgxyzABChijklDEFGHImnopq
179 module: str | None = ..., 1rstuvwabcdefgxyzABChijklDEFGHImnopq
180 ) -> None: ... 1abcdefghijklmnopq
182 # This second overload is for unsupported special forms (such as Annotated, Union, etc.)
183 # Currently there is no way to type this correctly
184 # See https://github.com/python/typing/pull/1618
185 @overload 1rstuvwabcdefgxyzABChijklDEFGHImnopq
186 def __init__( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
187 self,
188 type: Any, 1abcdefghijklmnopq
189 *,
190 config: ConfigDict | None = ..., 1rstuvwabcdefgxyzABChijklDEFGHImnopq
191 _parent_depth: int = ..., 1rstuvwabcdefgxyzABChijklDEFGHImnopq
192 module: str | None = ..., 1rstuvwabcdefgxyzABChijklDEFGHImnopq
193 ) -> None: ... 1abcdefghijklmnopq
195 def __init__( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
196 self,
197 type: Any,
198 *,
199 config: ConfigDict | None = None,
200 _parent_depth: int = 2,
201 module: str | None = None,
202 ) -> None:
203 if _type_has_config(type) and config is not None: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
204 raise PydanticUserError( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
205 'Cannot use `config` when the type is a BaseModel, dataclass or TypedDict.'
206 ' These types can have their own config and setting the config via the `config`'
207 ' parameter to TypeAdapter will not override it, thus the `config` you passed to'
208 ' TypeAdapter becomes meaningless, which is probably not what you want.',
209 code='type-adapter-config-unused',
210 )
212 self._type = type 1rstuvwabcdefgxyzABChijklDEFGHImnopq
213 self._config = config 1rstuvwabcdefgxyzABChijklDEFGHImnopq
214 self._parent_depth = _parent_depth 1rstuvwabcdefgxyzABChijklDEFGHImnopq
215 self.pydantic_complete = False 1rstuvwabcdefgxyzABChijklDEFGHImnopq
217 parent_frame = self._fetch_parent_frame() 1rstuvwabcdefgxyzABChijklDEFGHImnopq
218 if parent_frame is not None: 218 ↛ 223line 218 didn't jump to line 223 because the condition on line 218 was always true1rstuvwabcdefgxyzABChijklDEFGHImnopq
219 globalns = parent_frame.f_globals 1rstuvwabcdefgxyzABChijklDEFGHImnopq
220 # Do not provide a local ns if the type adapter happens to be instantiated at the module level:
221 localns = parent_frame.f_locals if parent_frame.f_locals is not globalns else {} 1rstuvwabcdefgxyzABChijklDEFGHImnopq
222 else:
223 globalns = {}
224 localns = {}
226 self._module_name = module or cast(str, globalns.get('__name__', '')) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
227 self._init_core_attrs( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
228 ns_resolver=_namespace_utils.NsResolver(
229 namespaces_tuple=_namespace_utils.NamespacesTuple(locals=localns, globals=globalns),
230 parent_namespace=localns,
231 ),
232 force=False,
233 )
235 def _fetch_parent_frame(self) -> FrameType | None: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
236 frame = sys._getframe(self._parent_depth) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
237 if frame.f_globals.get('__name__') == 'typing': 1rstuvwabcdefgxyzABChijklDEFGHImnopq
238 # Because `TypeAdapter` is generic, explicitly parametrizing the class results
239 # in a `typing._GenericAlias` instance, which proxies instantiation calls to the
240 # "real" `TypeAdapter` class and thus adding an extra frame to the call. To avoid
241 # pulling anything from the `typing` module, use the correct frame (the one before):
242 return frame.f_back 1rstuvwabcdefgxyzABChijklDEFGHImnopq
244 return frame 1rstuvwabcdefgxyzABChijklDEFGHImnopq
246 def _init_core_attrs( 1rstuvwabcdexyzABChijklDEFGHImnopq
247 self, ns_resolver: _namespace_utils.NsResolver, force: bool, raise_errors: bool = False
248 ) -> bool:
249 """Initialize the core schema, validator, and serializer for the type.
251 Args:
252 ns_resolver: The namespace resolver to use when building the core schema for the adapted type.
253 force: Whether to force the construction of the core schema, validator, and serializer.
254 If `force` is set to `False` and `_defer_build` is `True`, the core schema, validator, and serializer will be set to mocks.
255 raise_errors: Whether to raise errors if initializing any of the core attrs fails.
257 Returns:
258 `True` if the core schema, validator, and serializer were successfully initialized, otherwise `False`.
260 Raises:
261 PydanticUndefinedAnnotation: If `PydanticUndefinedAnnotation` occurs in`__get_pydantic_core_schema__`
262 and `raise_errors=True`.
263 """
264 if not force and self._defer_build: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
265 _mock_val_ser.set_type_adapter_mocks(self) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
266 self.pydantic_complete = False 1rstuvwabcdefgxyzABChijklDEFGHImnopq
267 return False 1rstuvwabcdefgxyzABChijklDEFGHImnopq
269 try: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
270 self.core_schema = _getattr_no_parents(self._type, '__pydantic_core_schema__') 1rstuvwabcdefgxyzABChijklDEFGHImnopq
271 self.validator = _getattr_no_parents(self._type, '__pydantic_validator__') 1rstuvwabcdefgxyzABChijklDEFGHImnopq
272 self.serializer = _getattr_no_parents(self._type, '__pydantic_serializer__') 1rstuvwabcdefgxyzABChijklDEFGHImnopq
274 # TODO: we don't go through the rebuild logic here directly because we don't want
275 # to repeat all of the namespace fetching logic that we've already done
276 # so we simply skip to the block below that does the actual schema generation
277 if ( 1rstuvwfgxyzABCDEFGHI
278 isinstance(self.core_schema, _mock_val_ser.MockCoreSchema)
279 or isinstance(self.validator, _mock_val_ser.MockValSer)
280 or isinstance(self.serializer, _mock_val_ser.MockValSer)
281 ):
282 raise AttributeError() 1rstuvwabcdefgxyzABChijklDEFGHImnopq
283 except AttributeError: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
284 config_wrapper = _config.ConfigWrapper(self._config) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
286 schema_generator = _generate_schema.GenerateSchema(config_wrapper, ns_resolver=ns_resolver) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
288 try: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
289 core_schema = schema_generator.generate_schema(self._type) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
290 except PydanticUndefinedAnnotation: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
291 if raise_errors: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
292 raise 1rstuvwabcdefgxyzABChijklDEFGHImnopq
293 _mock_val_ser.set_type_adapter_mocks(self) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
294 return False 1rstuvwabcdefgxyzABChijklDEFGHImnopq
296 try: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
297 self.core_schema = schema_generator.clean_schema(core_schema) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
298 except _generate_schema.InvalidSchemaError:
299 _mock_val_ser.set_type_adapter_mocks(self)
300 return False
302 core_config = config_wrapper.core_config(None) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
304 self.validator = create_schema_validator( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
305 schema=self.core_schema,
306 schema_type=self._type,
307 schema_type_module=self._module_name,
308 schema_type_name=str(self._type),
309 schema_kind='TypeAdapter',
310 config=core_config,
311 plugin_settings=config_wrapper.plugin_settings,
312 )
313 self.serializer = SchemaSerializer(self.core_schema, core_config) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
315 self.pydantic_complete = True 1rstuvwabcdefgxyzABChijklDEFGHImnopq
316 return True 1rstuvwabcdefgxyzABChijklDEFGHImnopq
318 @property 1rstuvwabcdefgxyzABChijklDEFGHImnopq
319 def _defer_build(self) -> bool: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
320 config = self._config if self._config is not None else self._model_config 1rstuvwabcdefgxyzABChijklDEFGHImnopq
321 if config: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
322 return config.get('defer_build') is True 1rstuvwabcdefgxyzABChijklDEFGHImnopq
323 return False 1rstuvwabcdefgxyzABChijklDEFGHImnopq
325 @property 1rstuvwabcdefgxyzABChijklDEFGHImnopq
326 def _model_config(self) -> ConfigDict | None: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
327 type_: Any = _typing_extra.annotated_type(self._type) or self._type # Eg FastAPI heavily uses Annotated 1rstuvwabcdefgxyzABChijklDEFGHImnopq
328 if _utils.lenient_issubclass(type_, BaseModel): 1rstuvwabcdefgxyzABChijklDEFGHImnopq
329 return type_.model_config 1rstuvwabcdefgxyzABChijklDEFGHImnopq
330 return getattr(type_, '__pydantic_config__', None) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
332 def __repr__(self) -> str: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
333 return f'TypeAdapter({_repr.display_as_type(self._type)})' 1rstuvwabcdefgxyzABChijklDEFGHImnopq
335 def rebuild( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
336 self,
337 *,
338 force: bool = False,
339 raise_errors: bool = True,
340 _parent_namespace_depth: int = 2,
341 _types_namespace: _namespace_utils.MappingNamespace | None = None,
342 ) -> bool | None:
343 """Try to rebuild the pydantic-core schema for the adapter's type.
345 This may be necessary when one of the annotations is a ForwardRef which could not be resolved during
346 the initial attempt to build the schema, and automatic rebuilding fails.
348 Args:
349 force: Whether to force the rebuilding of the type adapter's schema, defaults to `False`.
350 raise_errors: Whether to raise errors, defaults to `True`.
351 _parent_namespace_depth: Depth at which to search for the [parent frame][frame-objects]. This
352 frame is used when resolving forward annotations during schema rebuilding, by looking for
353 the locals of this frame. Defaults to 2, which will result in the frame where the method
354 was called.
355 _types_namespace: An explicit types namespace to use, instead of using the local namespace
356 from the parent frame. Defaults to `None`.
358 Returns:
359 Returns `None` if the schema is already "complete" and rebuilding was not required.
360 If rebuilding _was_ required, returns `True` if rebuilding was successful, otherwise `False`.
361 """
362 if not force and self.pydantic_complete: 362 ↛ 363line 362 didn't jump to line 363 because the condition on line 362 was never true1rstuvwabcdefgxyzABChijklDEFGHImnopq
363 return None
365 if _types_namespace is not None: 365 ↛ 366line 365 didn't jump to line 366 because the condition on line 365 was never true1rstuvwabcdefgxyzABChijklDEFGHImnopq
366 rebuild_ns = _types_namespace
367 elif _parent_namespace_depth > 0: 367 ↛ 370line 367 didn't jump to line 370 because the condition on line 367 was always true1rstuvwabcdefgxyzABChijklDEFGHImnopq
368 rebuild_ns = _typing_extra.parent_frame_namespace(parent_depth=_parent_namespace_depth, force=True) or {} 1rstuvwabcdefgxyzABChijklDEFGHImnopq
369 else:
370 rebuild_ns = {}
372 # we have to manually fetch globals here because there's no type on the stack of the NsResolver
373 # and so we skip the globalns = get_module_ns_of(typ) call that would normally happen
374 globalns = sys._getframe(max(_parent_namespace_depth - 1, 1)).f_globals 1rstuvwabcdefgxyzABChijklDEFGHImnopq
375 ns_resolver = _namespace_utils.NsResolver( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
376 namespaces_tuple=_namespace_utils.NamespacesTuple(locals=rebuild_ns, globals=globalns),
377 parent_namespace=rebuild_ns,
378 )
379 return self._init_core_attrs(ns_resolver=ns_resolver, force=True, raise_errors=raise_errors) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
381 def validate_python( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
382 self,
383 object: Any,
384 /,
385 *,
386 strict: bool | None = None,
387 from_attributes: bool | None = None,
388 context: dict[str, Any] | None = None,
389 experimental_allow_partial: bool | Literal['off', 'on', 'trailing-strings'] = False,
390 by_alias: bool | None = None,
391 by_name: bool | None = None,
392 ) -> T:
393 """Validate a Python object against the model.
395 Args:
396 object: The Python object to validate against the model.
397 strict: Whether to strictly check types.
398 from_attributes: Whether to extract data from object attributes.
399 context: Additional context to pass to the validator.
400 experimental_allow_partial: **Experimental** whether to enable
401 [partial validation](../concepts/experimental.md#partial-validation), e.g. to process streams.
402 * False / 'off': Default behavior, no partial validation.
403 * True / 'on': Enable partial validation.
404 * 'trailing-strings': Enable partial validation and allow trailing strings in the input.
405 by_alias: Whether to use the field's alias when validating against the provided input data.
406 by_name: Whether to use the field's name when validating against the provided input data.
408 !!! note
409 When using `TypeAdapter` with a Pydantic `dataclass`, the use of the `from_attributes`
410 argument is not supported.
412 Returns:
413 The validated object.
414 """
415 if by_alias is False and by_name is not True: 415 ↛ 416line 415 didn't jump to line 416 because the condition on line 415 was never true1rstuvwabcdefgxyzABChijklDEFGHImnopq
416 raise PydanticUserError(
417 'At least one of `by_alias` or `by_name` must be set to True.',
418 code='validate-by-alias-and-name-false',
419 )
421 return self.validator.validate_python( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
422 object,
423 strict=strict,
424 from_attributes=from_attributes,
425 context=context,
426 allow_partial=experimental_allow_partial,
427 by_alias=by_alias,
428 by_name=by_name,
429 )
431 def validate_json( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
432 self,
433 data: str | bytes | bytearray,
434 /,
435 *,
436 strict: bool | None = None,
437 context: dict[str, Any] | None = None,
438 experimental_allow_partial: bool | Literal['off', 'on', 'trailing-strings'] = False,
439 by_alias: bool | None = None,
440 by_name: bool | None = None,
441 ) -> T:
442 """!!! abstract "Usage Documentation"
443 [JSON Parsing](../concepts/json.md#json-parsing)
445 Validate a JSON string or bytes against the model.
447 Args:
448 data: The JSON data to validate against the model.
449 strict: Whether to strictly check types.
450 context: Additional context to use during validation.
451 experimental_allow_partial: **Experimental** whether to enable
452 [partial validation](../concepts/experimental.md#partial-validation), e.g. to process streams.
453 * False / 'off': Default behavior, no partial validation.
454 * True / 'on': Enable partial validation.
455 * 'trailing-strings': Enable partial validation and allow trailing strings in the input.
456 by_alias: Whether to use the field's alias when validating against the provided input data.
457 by_name: Whether to use the field's name when validating against the provided input data.
459 Returns:
460 The validated object.
461 """
462 if by_alias is False and by_name is not True: 462 ↛ 463line 462 didn't jump to line 463 because the condition on line 462 was never true1rstuvwabcdefgxyzABChijklDEFGHImnopq
463 raise PydanticUserError(
464 'At least one of `by_alias` or `by_name` must be set to True.',
465 code='validate-by-alias-and-name-false',
466 )
468 return self.validator.validate_json( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
469 data,
470 strict=strict,
471 context=context,
472 allow_partial=experimental_allow_partial,
473 by_alias=by_alias,
474 by_name=by_name,
475 )
477 def validate_strings( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
478 self,
479 obj: Any,
480 /,
481 *,
482 strict: bool | None = None,
483 context: dict[str, Any] | None = None,
484 experimental_allow_partial: bool | Literal['off', 'on', 'trailing-strings'] = False,
485 by_alias: bool | None = None,
486 by_name: bool | None = None,
487 ) -> T:
488 """Validate object contains string data against the model.
490 Args:
491 obj: The object contains string data to validate.
492 strict: Whether to strictly check types.
493 context: Additional context to use during validation.
494 experimental_allow_partial: **Experimental** whether to enable
495 [partial validation](../concepts/experimental.md#partial-validation), e.g. to process streams.
496 * False / 'off': Default behavior, no partial validation.
497 * True / 'on': Enable partial validation.
498 * 'trailing-strings': Enable partial validation and allow trailing strings in the input.
499 by_alias: Whether to use the field's alias when validating against the provided input data.
500 by_name: Whether to use the field's name when validating against the provided input data.
502 Returns:
503 The validated object.
504 """
505 if by_alias is False and by_name is not True: 505 ↛ 506line 505 didn't jump to line 506 because the condition on line 505 was never true1rstuvwabcdefgxyzABChijklDEFGHImnopq
506 raise PydanticUserError(
507 'At least one of `by_alias` or `by_name` must be set to True.',
508 code='validate-by-alias-and-name-false',
509 )
511 return self.validator.validate_strings( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
512 obj,
513 strict=strict,
514 context=context,
515 allow_partial=experimental_allow_partial,
516 by_alias=by_alias,
517 by_name=by_name,
518 )
520 def get_default_value(self, *, strict: bool | None = None, context: dict[str, Any] | None = None) -> Some[T] | None: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
521 """Get the default value for the wrapped type.
523 Args:
524 strict: Whether to strictly check types.
525 context: Additional context to pass to the validator.
527 Returns:
528 The default value wrapped in a `Some` if there is one or None if not.
529 """
530 return self.validator.get_default_value(strict=strict, context=context) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
532 def dump_python( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
533 self,
534 instance: T,
535 /,
536 *,
537 mode: Literal['json', 'python'] = 'python',
538 include: IncEx | None = None,
539 exclude: IncEx | None = None,
540 by_alias: bool | None = None,
541 exclude_unset: bool = False,
542 exclude_defaults: bool = False,
543 exclude_none: bool = False,
544 round_trip: bool = False,
545 warnings: bool | Literal['none', 'warn', 'error'] = True,
546 fallback: Callable[[Any], Any] | None = None,
547 serialize_as_any: bool = False,
548 context: dict[str, Any] | None = None,
549 ) -> Any:
550 """Dump an instance of the adapted type to a Python object.
552 Args:
553 instance: The Python object to serialize.
554 mode: The output format.
555 include: Fields to include in the output.
556 exclude: Fields to exclude from the output.
557 by_alias: Whether to use alias names for field names.
558 exclude_unset: Whether to exclude unset fields.
559 exclude_defaults: Whether to exclude fields with default values.
560 exclude_none: Whether to exclude fields with None values.
561 round_trip: Whether to output the serialized data in a way that is compatible with deserialization.
562 warnings: How to handle serialization errors. False/"none" ignores them, True/"warn" logs errors,
563 "error" raises a [`PydanticSerializationError`][pydantic_core.PydanticSerializationError].
564 fallback: A function to call when an unknown value is encountered. If not provided,
565 a [`PydanticSerializationError`][pydantic_core.PydanticSerializationError] error is raised.
566 serialize_as_any: Whether to serialize fields with duck-typing serialization behavior.
567 context: Additional context to pass to the serializer.
569 Returns:
570 The serialized object.
571 """
572 return self.serializer.to_python( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
573 instance,
574 mode=mode,
575 by_alias=by_alias,
576 include=include,
577 exclude=exclude,
578 exclude_unset=exclude_unset,
579 exclude_defaults=exclude_defaults,
580 exclude_none=exclude_none,
581 round_trip=round_trip,
582 warnings=warnings,
583 fallback=fallback,
584 serialize_as_any=serialize_as_any,
585 context=context,
586 )
588 def dump_json( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
589 self,
590 instance: T,
591 /,
592 *,
593 indent: int | None = None,
594 include: IncEx | None = None,
595 exclude: IncEx | None = None,
596 by_alias: bool | None = None,
597 exclude_unset: bool = False,
598 exclude_defaults: bool = False,
599 exclude_none: bool = False,
600 round_trip: bool = False,
601 warnings: bool | Literal['none', 'warn', 'error'] = True,
602 fallback: Callable[[Any], Any] | None = None,
603 serialize_as_any: bool = False,
604 context: dict[str, Any] | None = None,
605 ) -> bytes:
606 """!!! abstract "Usage Documentation"
607 [JSON Serialization](../concepts/json.md#json-serialization)
609 Serialize an instance of the adapted type to JSON.
611 Args:
612 instance: The instance to be serialized.
613 indent: Number of spaces for JSON indentation.
614 include: Fields to include.
615 exclude: Fields to exclude.
616 by_alias: Whether to use alias names for field names.
617 exclude_unset: Whether to exclude unset fields.
618 exclude_defaults: Whether to exclude fields with default values.
619 exclude_none: Whether to exclude fields with a value of `None`.
620 round_trip: Whether to serialize and deserialize the instance to ensure round-tripping.
621 warnings: How to handle serialization errors. False/"none" ignores them, True/"warn" logs errors,
622 "error" raises a [`PydanticSerializationError`][pydantic_core.PydanticSerializationError].
623 fallback: A function to call when an unknown value is encountered. If not provided,
624 a [`PydanticSerializationError`][pydantic_core.PydanticSerializationError] error is raised.
625 serialize_as_any: Whether to serialize fields with duck-typing serialization behavior.
626 context: Additional context to pass to the serializer.
628 Returns:
629 The JSON representation of the given instance as bytes.
630 """
631 return self.serializer.to_json( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
632 instance,
633 indent=indent,
634 include=include,
635 exclude=exclude,
636 by_alias=by_alias,
637 exclude_unset=exclude_unset,
638 exclude_defaults=exclude_defaults,
639 exclude_none=exclude_none,
640 round_trip=round_trip,
641 warnings=warnings,
642 fallback=fallback,
643 serialize_as_any=serialize_as_any,
644 context=context,
645 )
647 def json_schema( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
648 self,
649 *,
650 by_alias: bool = True,
651 ref_template: str = DEFAULT_REF_TEMPLATE,
652 schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema,
653 mode: JsonSchemaMode = 'validation',
654 ) -> dict[str, Any]:
655 """Generate a JSON schema for the adapted type.
657 Args:
658 by_alias: Whether to use alias names for field names.
659 ref_template: The format string used for generating $ref strings.
660 schema_generator: The generator class used for creating the schema.
661 mode: The mode to use for schema generation.
663 Returns:
664 The JSON schema for the model as a dictionary.
665 """
666 schema_generator_instance = schema_generator(by_alias=by_alias, ref_template=ref_template) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
667 if isinstance(self.core_schema, _mock_val_ser.MockCoreSchema): 1rstuvwabcdefgxyzABChijklDEFGHImnopq
668 self.core_schema.rebuild() 1rstuvwabcdefgxyzABChijklDEFGHImnopq
669 assert not isinstance(self.core_schema, _mock_val_ser.MockCoreSchema), 'this is a bug! please report it' 1rstuvwabcdefgxyzABChijklDEFGHImnopq
670 return schema_generator_instance.generate(self.core_schema, mode=mode) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
672 @staticmethod 1rstuvwabcdefgxyzABChijklDEFGHImnopq
673 def json_schemas( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
674 inputs: Iterable[tuple[JsonSchemaKeyT, JsonSchemaMode, TypeAdapter[Any]]],
675 /,
676 *,
677 by_alias: bool = True,
678 title: str | None = None,
679 description: str | None = None,
680 ref_template: str = DEFAULT_REF_TEMPLATE,
681 schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema,
682 ) -> tuple[dict[tuple[JsonSchemaKeyT, JsonSchemaMode], JsonSchemaValue], JsonSchemaValue]:
683 """Generate a JSON schema including definitions from multiple type adapters.
685 Args:
686 inputs: Inputs to schema generation. The first two items will form the keys of the (first)
687 output mapping; the type adapters will provide the core schemas that get converted into
688 definitions in the output JSON schema.
689 by_alias: Whether to use alias names.
690 title: The title for the schema.
691 description: The description for the schema.
692 ref_template: The format string used for generating $ref strings.
693 schema_generator: The generator class used for creating the schema.
695 Returns:
696 A tuple where:
698 - The first element is a dictionary whose keys are tuples of JSON schema key type and JSON mode, and
699 whose values are the JSON schema corresponding to that pair of inputs. (These schemas may have
700 JsonRef references to definitions that are defined in the second returned element.)
701 - The second element is a JSON schema containing all definitions referenced in the first returned
702 element, along with the optional title and description keys.
704 """
705 schema_generator_instance = schema_generator(by_alias=by_alias, ref_template=ref_template) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
707 inputs_ = [] 1rstuvwabcdefgxyzABChijklDEFGHImnopq
708 for key, mode, adapter in inputs: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
709 # This is the same pattern we follow for model json schemas - we attempt a core schema rebuild if we detect a mock
710 if isinstance(adapter.core_schema, _mock_val_ser.MockCoreSchema): 1rstuvwabcdefgxyzABChijklDEFGHImnopq
711 adapter.core_schema.rebuild() 1rstuvwabcdefgxyzABChijklDEFGHImnopq
712 assert not isinstance(adapter.core_schema, _mock_val_ser.MockCoreSchema), ( 1rstuvwabcdefgxyzABChijklDEFGHImnopq
713 'this is a bug! please report it'
714 )
715 inputs_.append((key, mode, adapter.core_schema)) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
717 json_schemas_map, definitions = schema_generator_instance.generate_definitions(inputs_) 1rstuvwabcdefgxyzABChijklDEFGHImnopq
719 json_schema: dict[str, Any] = {} 1rstuvwabcdefgxyzABChijklDEFGHImnopq
720 if definitions: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
721 json_schema['$defs'] = definitions 1rstuvwabcdefgxyzABChijklDEFGHImnopq
722 if title: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
723 json_schema['title'] = title 1rstuvwabcdefgxyzABChijklDEFGHImnopq
724 if description: 1rstuvwabcdefgxyzABChijklDEFGHImnopq
725 json_schema['description'] = description 1rstuvwabcdefgxyzABChijklDEFGHImnopq
727 return json_schemas_map, json_schema 1rstuvwabcdefgxyzABChijklDEFGHImnopq