Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1from __future__ import annotations
3import sys as _sys
4from typing import Any as _Any
6from typing_extensions import Sentinel
8from ._pydantic_core import (
9 ArgsKwargs,
10 MultiHostUrl,
11 PydanticCustomError,
12 PydanticKnownError,
13 PydanticOmit,
14 PydanticSerializationError,
15 PydanticSerializationUnexpectedValue,
16 PydanticUndefined,
17 PydanticUndefinedType,
18 PydanticUseDefault,
19 SchemaError,
20 SchemaSerializer,
21 SchemaValidator,
22 Some,
23 TzInfo,
24 Url,
25 ValidationError,
26 __version__,
27 from_json,
28 to_json,
29 to_jsonable_python,
30)
31from .core_schema import CoreConfig, CoreSchema, CoreSchemaType, ErrorType
33if _sys.version_info < (3, 11):
34 from typing_extensions import NotRequired as _NotRequired
35else:
36 from typing import NotRequired as _NotRequired
38if _sys.version_info < (3, 12):
39 from typing_extensions import TypedDict as _TypedDict
40else:
41 from typing import TypedDict as _TypedDict
43__all__ = [
44 'UNSET',
45 'ArgsKwargs',
46 'CoreConfig',
47 'CoreSchema',
48 'CoreSchemaType',
49 'ErrorDetails',
50 'InitErrorDetails',
51 'ModelFieldsSet',
52 'MultiHostUrl',
53 'PydanticCustomError',
54 'PydanticKnownError',
55 'PydanticOmit',
56 'PydanticSerializationError',
57 'PydanticSerializationUnexpectedValue',
58 'PydanticUndefined',
59 'PydanticUndefinedType',
60 'PydanticUseDefault',
61 'SchemaError',
62 'SchemaSerializer',
63 'SchemaValidator',
64 'Some',
65 'TzInfo',
66 'Url',
67 'ValidationError',
68 '__version__',
69 'from_json',
70 'to_json',
71 'to_jsonable_python',
72]
75class ErrorDetails(_TypedDict):
76 type: str
77 """
78 The type of error that occurred, this is an identifier designed for
79 programmatic use that will change rarely or never.
81 `type` is unique for each error message, and can hence be used as an identifier to build custom error messages.
82 """
83 loc: tuple[int | str, ...]
84 """Tuple of strings and ints identifying where in the schema the error occurred."""
85 msg: str
86 """A human readable error message."""
87 input: _Any
88 """The input data at this `loc` that caused the error."""
89 ctx: _NotRequired[dict[str, _Any]]
90 """
91 Values which are required to render the error message, and could hence be useful in rendering custom error messages.
92 Also useful for passing custom error data forward.
93 """
94 url: _NotRequired[str]
95 """
96 The documentation URL giving information about the error. No URL is available if
97 a [`PydanticCustomError`][pydantic_core.PydanticCustomError] is used.
98 """
101class InitErrorDetails(_TypedDict):
102 type: str | PydanticCustomError
103 """The type of error that occurred, this should be a "slug" identifier that changes rarely or never."""
104 loc: _NotRequired[tuple[int | str, ...]]
105 """Tuple of strings and ints identifying where in the schema the error occurred."""
106 input: _Any
107 """The input data at this `loc` that caused the error."""
108 ctx: _NotRequired[dict[str, _Any]]
109 """
110 Values which are required to render the error message, and could hence be useful in rendering custom error messages.
111 Also useful for passing custom error data forward.
112 """
115class ErrorTypeInfo(_TypedDict):
116 """
117 Gives information about errors.
118 """
120 type: ErrorType
121 """The type of error that occurred, this should be a "slug" identifier that changes rarely or never."""
122 message_template_python: str
123 """String template to render a human readable error message from using context, when the input is Python."""
124 example_message_python: str
125 """Example of a human readable error message, when the input is Python."""
126 message_template_json: _NotRequired[str]
127 """String template to render a human readable error message from using context, when the input is JSON data."""
128 example_message_json: _NotRequired[str]
129 """Example of a human readable error message, when the input is JSON data."""
130 example_context: dict[str, _Any] | None
131 """Example of context values."""
134class MultiHostHost(_TypedDict):
135 """
136 A host part of a multi-host URL.
137 """
139 username: str | None
140 """The username part of this host, or `None`."""
141 password: str | None
142 """The password part of this host, or `None`."""
143 host: str | None
144 """The host part of this host, or `None`."""
145 port: int | None
146 """The port part of this host, or `None`."""
149MISSING = Sentinel('MISSING')
150"""
151/// version-added | v2.12
152///
154/// version-changed | v2.14
155The `MISSING` sentinel is no longer experimental.
156///
158The `MISSING` sentinel is a singleton indicating a field value was not provided during validation.
160This singleton can be used as a default value, as an alternative to `None` when it has an explicit
161meaning. During serialization, any field with `MISSING` as a value is excluded from the output.
163At runtime, the `MISSING` sentinel is implemented as a [`sentinel`](https://docs.python.org/3.15/library/functions.html#sentinel) instance.
165```python
166from pydantic import MISSING, BaseModel
169class Configuration(BaseModel):
170 timeout: int | None | MISSING = MISSING
173# configuration defaults, stored somewhere else:
174defaults = {'timeout': 200}
176conf = Configuration()
178# `timeout` is excluded from the serialization output:
179conf.model_dump()
180# {}
182# The `MISSING` value doesn't appear in the JSON Schema:
183Configuration.model_json_schema()['properties']['timeout']
184#> {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'title': 'Timeout'}
187# `is` can be used to discriminate between the sentinel and other values:
188timeout = conf.timeout if conf.timeout is not MISSING else defaults['timeout']
189```
191!!! note
192 When [applying constraints](./fields.md#field-constraints) to a union containing the `MISSING` sentinel,
193 such constraints are automatically applied to the remaining type(s) of the union.
194"""