98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313 | @dataclass_transform(field_specifiers=(dataclasses.field, Field, PrivateAttr))
def dataclass(
_cls: type[_T] | None = None,
*,
init: Literal[False] = False,
repr: bool = True,
eq: bool = True,
order: bool = False,
unsafe_hash: bool = False,
frozen: bool | None = None,
config: ConfigDict | type[object] | None = None,
validate_on_init: bool | None = None,
kw_only: bool = False,
slots: bool = False,
) -> Callable[[type[_T]], type[PydanticDataclass]] | type[PydanticDataclass]:
"""!!! abstract "Usage Documentation"
[`dataclasses`](../concepts/dataclasses.md)
A decorator used to create a Pydantic-enhanced dataclass, similar to the standard Python `dataclass`,
but with added validation.
This function should be used similarly to `dataclasses.dataclass`.
Args:
_cls: The target `dataclass`.
init: Included for signature compatibility with `dataclasses.dataclass`, and is passed through to
`dataclasses.dataclass` when appropriate. If specified, must be set to `False`, as pydantic inserts its
own `__init__` function.
repr: A boolean indicating whether to include the field in the `__repr__` output.
eq: Determines if a `__eq__` method should be generated for the class.
order: Determines if comparison magic methods should be generated, such as `__lt__`, but not `__eq__`.
unsafe_hash: Determines if a `__hash__` method should be included in the class, as in `dataclasses.dataclass`.
frozen: Determines if the generated class should be a 'frozen' `dataclass`, which does not allow its
attributes to be modified after it has been initialized. If not set, the value from the provided `config` argument will be used (and will default to `False` otherwise).
config: The Pydantic config to use for the `dataclass`.
validate_on_init: A deprecated parameter included for backwards compatibility; in V2, all Pydantic dataclasses
are validated on init.
kw_only: Determines if `__init__` method parameters must be specified by keyword only. Defaults to `False`.
slots: Determines if the generated class should be a 'slots' `dataclass`, which does not allow the addition of
new attributes after instantiation.
Returns:
A decorator that accepts a class as its argument and returns a Pydantic `dataclass`.
Raises:
AssertionError: Raised if `init` is not `False` or `validate_on_init` is `False`.
"""
assert init is False, 'pydantic.dataclasses.dataclass only supports init=False'
assert validate_on_init is not False, 'validate_on_init=False is no longer supported'
if sys.version_info >= (3, 10):
kwargs = {'kw_only': kw_only, 'slots': slots}
else:
kwargs = {}
def create_dataclass(cls: type[Any]) -> type[PydanticDataclass]:
"""Create a Pydantic dataclass from a regular dataclass.
Args:
cls: The class to create the Pydantic dataclass from.
Returns:
A Pydantic dataclass.
"""
from ._internal._utils import is_model_class
if is_model_class(cls):
raise PydanticUserError(
f'Cannot create a Pydantic dataclass from {cls.__name__} as it is already a Pydantic model',
code='dataclass-on-model',
)
original_cls = cls
# we warn on conflicting config specifications, but only if the class doesn't have a dataclass base
# because a dataclass base might provide a __pydantic_config__ attribute that we don't want to warn about
has_dataclass_base = any(dataclasses.is_dataclass(base) for base in cls.__bases__)
if not has_dataclass_base and config is not None and hasattr(cls, '__pydantic_config__'):
warn(
f'`config` is set via both the `dataclass` decorator and `__pydantic_config__` for dataclass {cls.__name__}. '
f'The `config` specification from `dataclass` decorator will take priority.',
category=UserWarning,
stacklevel=2,
)
# if config is not explicitly provided, try to read it from the type
config_dict = config if config is not None else getattr(cls, '__pydantic_config__', None)
config_wrapper = _config.ConfigWrapper(config_dict)
decorators = _decorators.DecoratorInfos.build(cls)
decorators.update_from_config(config_wrapper)
# Keep track of the original __doc__ so that we can restore it after applying the dataclasses decorator
# Otherwise, classes with no __doc__ will have their signature added into the JSON schema description,
# since dataclasses.dataclass will set this as the __doc__
original_doc = cls.__doc__
if _pydantic_dataclasses.is_stdlib_dataclass(cls):
# Vanilla dataclasses include a default docstring (representing the class signature),
# which we don't want to preserve.
original_doc = None
# We don't want to add validation to the existing std lib dataclass, so we will subclass it
# If the class is generic, we need to make sure the subclass also inherits from Generic
# with all the same parameters.
bases = (cls,)
if issubclass(cls, Generic):
generic_base = Generic[cls.__parameters__] # type: ignore
bases = bases + (generic_base,)
cls = types.new_class(cls.__name__, bases)
# Respect frozen setting from dataclass constructor and fallback to config setting if not provided
if frozen is not None:
frozen_ = frozen
if config_wrapper.frozen:
# It's not recommended to define both, as the setting from the dataclass decorator will take priority.
warn(
f'`frozen` is set via both the `dataclass` decorator and `config` for dataclass {cls.__name__!r}.'
'This is not recommended. The `frozen` specification on `dataclass` will take priority.',
category=UserWarning,
stacklevel=2,
)
else:
frozen_ = config_wrapper.frozen or False
# Make Pydantic's `Field()` function compatible with stdlib dataclasses. As we'll decorate
# `cls` with the stdlib `@dataclass` decorator first, there are two attributes, `kw_only` and
# `repr` that need to be understood *during* the stdlib creation. We do so in two steps:
# 1. On the decorated class, wrap `Field()` assignment with `dataclass.field()`, with the
# two attributes set (done in `as_dataclass_field()`)
cls_anns = _typing_extra.safe_get_annotations(cls)
for field_name in cls_anns:
# We should look for assignments in `__dict__` instead, but for now we follow
# the same behavior as stdlib dataclasses (see https://github.com/python/cpython/issues/88609)
field_value = getattr(cls, field_name, None)
if isinstance(field_value, FieldInfo):
setattr(cls, field_name, _pydantic_dataclasses.as_dataclass_field(field_value))
# 2. For bases of `cls` that are stdlib dataclasses, we temporarily patch their fields
# (see the docstring of the context manager):
with _pydantic_dataclasses.patch_base_fields(cls):
cls = dataclasses.dataclass( # pyright: ignore[reportCallIssue]
cls,
# the value of init here doesn't affect anything except that it makes it easier to generate a signature
init=True,
repr=repr,
eq=eq,
order=order,
unsafe_hash=unsafe_hash,
frozen=frozen_,
**kwargs,
)
if config_wrapper.validate_assignment:
original_setattr = cls.__setattr__
@functools.wraps(cls.__setattr__)
def validated_setattr(instance: PydanticDataclass, name: str, value: Any, /) -> None:
if frozen_:
return original_setattr(instance, name, value) # pyright: ignore[reportCallIssue]
inst_cls = type(instance)
attr = getattr(inst_cls, name, None)
if isinstance(attr, property):
attr.__set__(instance, value)
elif isinstance(attr, functools.cached_property):
instance.__dict__.__setitem__(name, value)
else:
inst_cls.__pydantic_validator__.validate_assignment(instance, name, value)
cls.__setattr__ = validated_setattr.__get__(None, cls) # type: ignore
if slots and not hasattr(cls, '__setstate__'):
# If slots is set, `pickle` (relied on by `copy.copy()`) will use
# `__setattr__()` to reconstruct the dataclass. However, the custom
# `__setattr__()` set above relies on `validate_assignment()`, which
# in turn expects all the field values to be already present on the
# instance, resulting in attribute errors.
# As such, we make use of `object.__setattr__()` instead.
# Note that we do so only if `__setstate__()` isn't already set (this is the
# case if on top of `slots`, `frozen` is used).
# Taken from `dataclasses._dataclass_get/setstate()`:
def _dataclass_getstate(self: Any) -> list[Any]:
return [getattr(self, f.name) for f in dataclasses.fields(self)]
def _dataclass_setstate(self: Any, state: list[Any]) -> None:
for field, value in zip(dataclasses.fields(self), state):
object.__setattr__(self, field.name, value)
cls.__getstate__ = _dataclass_getstate # pyright: ignore[reportAttributeAccessIssue]
cls.__setstate__ = _dataclass_setstate # pyright: ignore[reportAttributeAccessIssue]
# This is an undocumented attribute to distinguish stdlib/Pydantic dataclasses.
# It should be set as early as possible:
cls.__is_pydantic_dataclass__ = True
cls.__pydantic_decorators__ = decorators # type: ignore
cls.__doc__ = original_doc
# Can be non-existent for dynamically created classes:
firstlineno = getattr(original_cls, '__firstlineno__', None)
cls.__module__ = original_cls.__module__
if sys.version_info >= (3, 13) and firstlineno is not None:
# As per https://docs.python.org/3/reference/datamodel.html#type.__firstlineno__:
# Setting the `__module__` attribute removes the `__firstlineno__` item from the type’s dictionary.
original_cls.__firstlineno__ = firstlineno
cls.__firstlineno__ = firstlineno
cls.__qualname__ = original_cls.__qualname__
cls.__pydantic_fields_complete__ = classmethod(_pydantic_fields_complete)
cls.__pydantic_complete__ = False # `complete_dataclass` will set it to `True` if successful.
# TODO `parent_namespace` is currently None, but we could do the same thing as Pydantic models:
# fetch the parent ns using `parent_frame_namespace` (if the dataclass was defined in a function),
# and possibly cache it (see the `__pydantic_parent_namespace__` logic for models).
_pydantic_dataclasses.complete_dataclass(cls, config_wrapper, raise_errors=False)
return cls
return create_dataclass if _cls is None else create_dataclass(_cls)
|