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 '__version__',
45 'UNSET',
46 'CoreConfig',
47 'CoreSchema',
48 'CoreSchemaType',
49 'SchemaValidator',
50 'SchemaSerializer',
51 'Some',
52 'Url',
53 'MultiHostUrl',
54 'ArgsKwargs',
55 'PydanticUndefined',
56 'PydanticUndefinedType',
57 'SchemaError',
58 'ErrorDetails',
59 'InitErrorDetails',
60 'ValidationError',
61 'PydanticCustomError',
62 'PydanticKnownError',
63 'PydanticOmit',
64 'PydanticUseDefault',
65 'PydanticSerializationError',
66 'PydanticSerializationUnexpectedValue',
67 'TzInfo',
68 'to_json',
69 'from_json',
70 'to_jsonable_python',
71]
74class ErrorDetails(_TypedDict):
75 type: str
76 """
77 The type of error that occurred, this is an identifier designed for
78 programmatic use that will change rarely or never.
80 `type` is unique for each error message, and can hence be used as an identifier to build custom error messages.
81 """
82 loc: tuple[int | str, ...]
83 """Tuple of strings and ints identifying where in the schema the error occurred."""
84 msg: str
85 """A human readable error message."""
86 input: _Any
87 """The input data at this `loc` that caused the error."""
88 ctx: _NotRequired[dict[str, _Any]]
89 """
90 Values which are required to render the error message, and could hence be useful in rendering custom error messages.
91 Also useful for passing custom error data forward.
92 """
93 url: _NotRequired[str]
94 """
95 The documentation URL giving information about the error. No URL is available if
96 a [`PydanticCustomError`][pydantic_core.PydanticCustomError] is used.
97 """
100class InitErrorDetails(_TypedDict):
101 type: str | PydanticCustomError
102 """The type of error that occurred, this should be a "slug" identifier that changes rarely or never."""
103 loc: _NotRequired[tuple[int | str, ...]]
104 """Tuple of strings and ints identifying where in the schema the error occurred."""
105 input: _Any
106 """The input data at this `loc` that caused the error."""
107 ctx: _NotRequired[dict[str, _Any]]
108 """
109 Values which are required to render the error message, and could hence be useful in rendering custom error messages.
110 Also useful for passing custom error data forward.
111 """
114class ErrorTypeInfo(_TypedDict):
115 """
116 Gives information about errors.
117 """
119 type: ErrorType
120 """The type of error that occurred, this should be a "slug" identifier that changes rarely or never."""
121 message_template_python: str
122 """String template to render a human readable error message from using context, when the input is Python."""
123 example_message_python: str
124 """Example of a human readable error message, when the input is Python."""
125 message_template_json: _NotRequired[str]
126 """String template to render a human readable error message from using context, when the input is JSON data."""
127 example_message_json: _NotRequired[str]
128 """Example of a human readable error message, when the input is JSON data."""
129 example_context: dict[str, _Any] | None
130 """Example of context values."""
133class MultiHostHost(_TypedDict):
134 """
135 A host part of a multi-host URL.
136 """
138 username: str | None
139 """The username part of this host, or `None`."""
140 password: str | None
141 """The password part of this host, or `None`."""
142 host: str | None
143 """The host part of this host, or `None`."""
144 port: int | None
145 """The port part of this host, or `None`."""
148MISSING = Sentinel('MISSING')
149"""
150/// version-added | v2.12
151///
153/// version-changed | v2.14
154The `MISSING` sentinel is no longer experimental.
155///
157The `MISSING` sentinel is a singleton indicating a field value was not provided during validation.
159This singleton can be used as a default value, as an alternative to `None` when it has an explicit
160meaning. During serialization, any field with `MISSING` as a value is excluded from the output.
162At runtime, the `MISSING` sentinel is implemented as a [`sentinel`](https://docs.python.org/3.15/library/functions.html#sentinel) instance.
164```python
165from pydantic import MISSING, BaseModel
168class Configuration(BaseModel):
169 timeout: int | None | MISSING = MISSING
172# configuration defaults, stored somewhere else:
173defaults = {'timeout': 200}
175conf = Configuration()
177# `timeout` is excluded from the serialization output:
178conf.model_dump()
179# {}
181# The `MISSING` value doesn't appear in the JSON Schema:
182Configuration.model_json_schema()['properties']['timeout']
183#> {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'title': 'Timeout'}
186# `is` can be used to discriminate between the sentinel and other values:
187timeout = conf.timeout if conf.timeout is not MISSING else defaults['timeout']
188```
190!!! note
191 When [applying constraints](./fields.md#field-constraints) to a union containing the `MISSING` sentinel,
192 such constraints are automatically applied to the remaining type(s) of the union.
193"""