1 import re
2 import sys
3 import copy
4 import types
5 import inspect
6 import keyword
7 import functools
8 import itertools
9 import abc
10 import _thread
11 from types import FunctionType, GenericAlias
12
13
14 __all__ = ['dataclass',
15 'field',
16 'Field',
17 'FrozenInstanceError',
18 'InitVar',
19 'KW_ONLY',
20 'MISSING',
21
22 # Helper functions.
23 'fields',
24 'asdict',
25 'astuple',
26 'make_dataclass',
27 'replace',
28 'is_dataclass',
29 ]
30
31 # Conditions for adding methods. The boxes indicate what action the
32 # dataclass decorator takes. For all of these tables, when I talk
33 # about init=, repr=, eq=, order=, unsafe_hash=, or frozen=, I'm
34 # referring to the arguments to the @dataclass decorator. When
35 # checking if a dunder method already exists, I mean check for an
36 # entry in the class's __dict__. I never check to see if an attribute
37 # is defined in a base class.
38
39 # Key:
40 # +=========+=========================================+
41 # + Value | Meaning |
42 # +=========+=========================================+
43 # | <blank> | No action: no method is added. |
44 # +---------+-----------------------------------------+
45 # | add | Generated method is added. |
46 # +---------+-----------------------------------------+
47 # | raise | TypeError is raised. |
48 # +---------+-----------------------------------------+
49 # | None | Attribute is set to None. |
50 # +=========+=========================================+
51
52 # __init__
53 #
54 # +--- init= parameter
55 # |
56 # v | | |
57 # | no | yes | <--- class has __init__ in __dict__?
58 # +=======+=======+=======+
59 # | False | | |
60 # +-------+-------+-------+
61 # | True | add | | <- the default
62 # +=======+=======+=======+
63
64 # __repr__
65 #
66 # +--- repr= parameter
67 # |
68 # v | | |
69 # | no | yes | <--- class has __repr__ in __dict__?
70 # +=======+=======+=======+
71 # | False | | |
72 # +-------+-------+-------+
73 # | True | add | | <- the default
74 # +=======+=======+=======+
75
76
77 # __setattr__
78 # __delattr__
79 #
80 # +--- frozen= parameter
81 # |
82 # v | | |
83 # | no | yes | <--- class has __setattr__ or __delattr__ in __dict__?
84 # +=======+=======+=======+
85 # | False | | | <- the default
86 # +-------+-------+-------+
87 # | True | add | raise |
88 # +=======+=======+=======+
89 # Raise because not adding these methods would break the "frozen-ness"
90 # of the class.
91
92 # __eq__
93 #
94 # +--- eq= parameter
95 # |
96 # v | | |
97 # | no | yes | <--- class has __eq__ in __dict__?
98 # +=======+=======+=======+
99 # | False | | |
100 # +-------+-------+-------+
101 # | True | add | | <- the default
102 # +=======+=======+=======+
103
104 # __lt__
105 # __le__
106 # __gt__
107 # __ge__
108 #
109 # +--- order= parameter
110 # |
111 # v | | |
112 # | no | yes | <--- class has any comparison method in __dict__?
113 # +=======+=======+=======+
114 # | False | | | <- the default
115 # +-------+-------+-------+
116 # | True | add | raise |
117 # +=======+=======+=======+
118 # Raise because to allow this case would interfere with using
119 # functools.total_ordering.
120
121 # __hash__
122
123 # +------------------- unsafe_hash= parameter
124 # | +----------- eq= parameter
125 # | | +--- frozen= parameter
126 # | | |
127 # v v v | | |
128 # | no | yes | <--- class has explicitly defined __hash__
129 # +=======+=======+=======+========+========+
130 # | False | False | False | | | No __eq__, use the base class __hash__
131 # +-------+-------+-------+--------+--------+
132 # | False | False | True | | | No __eq__, use the base class __hash__
133 # +-------+-------+-------+--------+--------+
134 # | False | True | False | None | | <-- the default, not hashable
135 # +-------+-------+-------+--------+--------+
136 # | False | True | True | add | | Frozen, so hashable, allows override
137 # +-------+-------+-------+--------+--------+
138 # | True | False | False | add | raise | Has no __eq__, but hashable
139 # +-------+-------+-------+--------+--------+
140 # | True | False | True | add | raise | Has no __eq__, but hashable
141 # +-------+-------+-------+--------+--------+
142 # | True | True | False | add | raise | Not frozen, but hashable
143 # +-------+-------+-------+--------+--------+
144 # | True | True | True | add | raise | Frozen, so hashable
145 # +=======+=======+=======+========+========+
146 # For boxes that are blank, __hash__ is untouched and therefore
147 # inherited from the base class. If the base is object, then
148 # id-based hashing is used.
149 #
150 # Note that a class may already have __hash__=None if it specified an
151 # __eq__ method in the class body (not one that was created by
152 # @dataclass).
153 #
154 # See _hash_action (below) for a coded version of this table.
155
156 # __match_args__
157 #
158 # +--- match_args= parameter
159 # |
160 # v | | |
161 # | no | yes | <--- class has __match_args__ in __dict__?
162 # +=======+=======+=======+
163 # | False | | |
164 # +-------+-------+-------+
165 # | True | add | | <- the default
166 # +=======+=======+=======+
167 # __match_args__ is always added unless the class already defines it. It is a
168 # tuple of __init__ parameter names; non-init fields must be matched by keyword.
169
170
171 # Raised when an attempt is made to modify a frozen class.
172 class ESC[4;38;5;81mFrozenInstanceError(ESC[4;38;5;149mAttributeError): pass
173
174 # A sentinel object for default values to signal that a default
175 # factory will be used. This is given a nice repr() which will appear
176 # in the function signature of dataclasses' constructors.
177 class ESC[4;38;5;81m_HAS_DEFAULT_FACTORY_CLASS:
178 def __repr__(self):
179 return '<factory>'
180 _HAS_DEFAULT_FACTORY = _HAS_DEFAULT_FACTORY_CLASS()
181
182 # A sentinel object to detect if a parameter is supplied or not. Use
183 # a class to give it a better repr.
184 class ESC[4;38;5;81m_MISSING_TYPE:
185 pass
186 MISSING = _MISSING_TYPE()
187
188 # A sentinel object to indicate that following fields are keyword-only by
189 # default. Use a class to give it a better repr.
190 class ESC[4;38;5;81m_KW_ONLY_TYPE:
191 pass
192 KW_ONLY = _KW_ONLY_TYPE()
193
194 # Since most per-field metadata will be unused, create an empty
195 # read-only proxy that can be shared among all fields.
196 _EMPTY_METADATA = types.MappingProxyType({})
197
198 # Markers for the various kinds of fields and pseudo-fields.
199 class ESC[4;38;5;81m_FIELD_BASE:
200 def __init__(self, name):
201 self.name = name
202 def __repr__(self):
203 return self.name
204 _FIELD = _FIELD_BASE('_FIELD')
205 _FIELD_CLASSVAR = _FIELD_BASE('_FIELD_CLASSVAR')
206 _FIELD_INITVAR = _FIELD_BASE('_FIELD_INITVAR')
207
208 # The name of an attribute on the class where we store the Field
209 # objects. Also used to check if a class is a Data Class.
210 _FIELDS = '__dataclass_fields__'
211
212 # The name of an attribute on the class that stores the parameters to
213 # @dataclass.
214 _PARAMS = '__dataclass_params__'
215
216 # The name of the function, that if it exists, is called at the end of
217 # __init__.
218 _POST_INIT_NAME = '__post_init__'
219
220 # String regex that string annotations for ClassVar or InitVar must match.
221 # Allows "identifier.identifier[" or "identifier[".
222 # https://bugs.python.org/issue33453 for details.
223 _MODULE_IDENTIFIER_RE = re.compile(r'^(?:\s*(\w+)\s*\.)?\s*(\w+)')
224
225 # Atomic immutable types which don't require any recursive handling and for which deepcopy
226 # returns the same object. We can provide a fast-path for these types in asdict and astuple.
227 _ATOMIC_TYPES = frozenset({
228 # Common JSON Serializable types
229 types.NoneType,
230 bool,
231 int,
232 float,
233 str,
234 # Other common types
235 complex,
236 bytes,
237 # Other types that are also unaffected by deepcopy
238 types.EllipsisType,
239 types.NotImplementedType,
240 types.CodeType,
241 types.BuiltinFunctionType,
242 types.FunctionType,
243 type,
244 range,
245 property,
246 })
247
248 # This function's logic is copied from "recursive_repr" function in
249 # reprlib module to avoid dependency.
250 def _recursive_repr(user_function):
251 # Decorator to make a repr function return "..." for a recursive
252 # call.
253 repr_running = set()
254
255 @functools.wraps(user_function)
256 def wrapper(self):
257 key = id(self), _thread.get_ident()
258 if key in repr_running:
259 return '...'
260 repr_running.add(key)
261 try:
262 result = user_function(self)
263 finally:
264 repr_running.discard(key)
265 return result
266 return wrapper
267
268 class ESC[4;38;5;81mInitVar:
269 __slots__ = ('type', )
270
271 def __init__(self, type):
272 self.type = type
273
274 def __repr__(self):
275 if isinstance(self.type, type):
276 type_name = self.type.__name__
277 else:
278 # typing objects, e.g. List[int]
279 type_name = repr(self.type)
280 return f'dataclasses.InitVar[{type_name}]'
281
282 def __class_getitem__(cls, type):
283 return InitVar(type)
284
285 # Instances of Field are only ever created from within this module,
286 # and only from the field() function, although Field instances are
287 # exposed externally as (conceptually) read-only objects.
288 #
289 # name and type are filled in after the fact, not in __init__.
290 # They're not known at the time this class is instantiated, but it's
291 # convenient if they're available later.
292 #
293 # When cls._FIELDS is filled in with a list of Field objects, the name
294 # and type fields will have been populated.
295 class ESC[4;38;5;81mField:
296 __slots__ = ('name',
297 'type',
298 'default',
299 'default_factory',
300 'repr',
301 'hash',
302 'init',
303 'compare',
304 'metadata',
305 'kw_only',
306 '_field_type', # Private: not to be used by user code.
307 )
308
309 def __init__(self, default, default_factory, init, repr, hash, compare,
310 metadata, kw_only):
311 self.name = None
312 self.type = None
313 self.default = default
314 self.default_factory = default_factory
315 self.init = init
316 self.repr = repr
317 self.hash = hash
318 self.compare = compare
319 self.metadata = (_EMPTY_METADATA
320 if metadata is None else
321 types.MappingProxyType(metadata))
322 self.kw_only = kw_only
323 self._field_type = None
324
325 @_recursive_repr
326 def __repr__(self):
327 return ('Field('
328 f'name={self.name!r},'
329 f'type={self.type!r},'
330 f'default={self.default!r},'
331 f'default_factory={self.default_factory!r},'
332 f'init={self.init!r},'
333 f'repr={self.repr!r},'
334 f'hash={self.hash!r},'
335 f'compare={self.compare!r},'
336 f'metadata={self.metadata!r},'
337 f'kw_only={self.kw_only!r},'
338 f'_field_type={self._field_type}'
339 ')')
340
341 # This is used to support the PEP 487 __set_name__ protocol in the
342 # case where we're using a field that contains a descriptor as a
343 # default value. For details on __set_name__, see
344 # https://peps.python.org/pep-0487/#implementation-details.
345 #
346 # Note that in _process_class, this Field object is overwritten
347 # with the default value, so the end result is a descriptor that
348 # had __set_name__ called on it at the right time.
349 def __set_name__(self, owner, name):
350 func = getattr(type(self.default), '__set_name__', None)
351 if func:
352 # There is a __set_name__ method on the descriptor, call
353 # it.
354 func(self.default, owner, name)
355
356 __class_getitem__ = classmethod(GenericAlias)
357
358
359 class ESC[4;38;5;81m_DataclassParams:
360 __slots__ = ('init',
361 'repr',
362 'eq',
363 'order',
364 'unsafe_hash',
365 'frozen',
366 'match_args',
367 'kw_only',
368 'slots',
369 'weakref_slot',
370 )
371
372 def __init__(self,
373 init, repr, eq, order, unsafe_hash, frozen,
374 match_args, kw_only, slots, weakref_slot):
375 self.init = init
376 self.repr = repr
377 self.eq = eq
378 self.order = order
379 self.unsafe_hash = unsafe_hash
380 self.frozen = frozen
381 self.match_args = match_args
382 self.kw_only = kw_only
383 self.slots = slots
384 self.weakref_slot = weakref_slot
385
386 def __repr__(self):
387 return ('_DataclassParams('
388 f'init={self.init!r},'
389 f'repr={self.repr!r},'
390 f'eq={self.eq!r},'
391 f'order={self.order!r},'
392 f'unsafe_hash={self.unsafe_hash!r},'
393 f'frozen={self.frozen!r},'
394 f'match_args={self.match_args!r},'
395 f'kw_only={self.kw_only!r},'
396 f'slots={self.slots!r},'
397 f'weakref_slot={self.weakref_slot!r}'
398 ')')
399
400
401 # This function is used instead of exposing Field creation directly,
402 # so that a type checker can be told (via overloads) that this is a
403 # function whose type depends on its parameters.
404 def field(*, default=MISSING, default_factory=MISSING, init=True, repr=True,
405 hash=None, compare=True, metadata=None, kw_only=MISSING):
406 """Return an object to identify dataclass fields.
407
408 default is the default value of the field. default_factory is a
409 0-argument function called to initialize a field's value. If init
410 is true, the field will be a parameter to the class's __init__()
411 function. If repr is true, the field will be included in the
412 object's repr(). If hash is true, the field will be included in the
413 object's hash(). If compare is true, the field will be used in
414 comparison functions. metadata, if specified, must be a mapping
415 which is stored but not otherwise examined by dataclass. If kw_only
416 is true, the field will become a keyword-only parameter to
417 __init__().
418
419 It is an error to specify both default and default_factory.
420 """
421
422 if default is not MISSING and default_factory is not MISSING:
423 raise ValueError('cannot specify both default and default_factory')
424 return Field(default, default_factory, init, repr, hash, compare,
425 metadata, kw_only)
426
427
428 def _fields_in_init_order(fields):
429 # Returns the fields as __init__ will output them. It returns 2 tuples:
430 # the first for normal args, and the second for keyword args.
431
432 return (tuple(f for f in fields if f.init and not f.kw_only),
433 tuple(f for f in fields if f.init and f.kw_only)
434 )
435
436
437 def _tuple_str(obj_name, fields):
438 # Return a string representing each field of obj_name as a tuple
439 # member. So, if fields is ['x', 'y'] and obj_name is "self",
440 # return "(self.x,self.y)".
441
442 # Special case for the 0-tuple.
443 if not fields:
444 return '()'
445 # Note the trailing comma, needed if this turns out to be a 1-tuple.
446 return f'({",".join([f"{obj_name}.{f.name}" for f in fields])},)'
447
448
449 def _create_fn(name, args, body, *, globals=None, locals=None,
450 return_type=MISSING):
451 # Note that we may mutate locals. Callers beware!
452 # The only callers are internal to this module, so no
453 # worries about external callers.
454 if locals is None:
455 locals = {}
456 return_annotation = ''
457 if return_type is not MISSING:
458 locals['__dataclass_return_type__'] = return_type
459 return_annotation = '->__dataclass_return_type__'
460 args = ','.join(args)
461 body = '\n'.join(f' {b}' for b in body)
462
463 # Compute the text of the entire function.
464 txt = f' def {name}({args}){return_annotation}:\n{body}'
465
466 # Free variables in exec are resolved in the global namespace.
467 # The global namespace we have is user-provided, so we can't modify it for
468 # our purposes. So we put the things we need into locals and introduce a
469 # scope to allow the function we're creating to close over them.
470 local_vars = ', '.join(locals.keys())
471 txt = f"def __create_fn__({local_vars}):\n{txt}\n return {name}"
472 ns = {}
473 exec(txt, globals, ns)
474 return ns['__create_fn__'](**locals)
475
476
477 def _field_assign(frozen, name, value, self_name):
478 # If we're a frozen class, then assign to our fields in __init__
479 # via object.__setattr__. Otherwise, just use a simple
480 # assignment.
481 #
482 # self_name is what "self" is called in this function: don't
483 # hard-code "self", since that might be a field name.
484 if frozen:
485 return f'__dataclass_builtins_object__.__setattr__({self_name},{name!r},{value})'
486 return f'{self_name}.{name}={value}'
487
488
489 def _field_init(f, frozen, globals, self_name, slots):
490 # Return the text of the line in the body of __init__ that will
491 # initialize this field.
492
493 default_name = f'__dataclass_dflt_{f.name}__'
494 if f.default_factory is not MISSING:
495 if f.init:
496 # This field has a default factory. If a parameter is
497 # given, use it. If not, call the factory.
498 globals[default_name] = f.default_factory
499 value = (f'{default_name}() '
500 f'if {f.name} is __dataclass_HAS_DEFAULT_FACTORY__ '
501 f'else {f.name}')
502 else:
503 # This is a field that's not in the __init__ params, but
504 # has a default factory function. It needs to be
505 # initialized here by calling the factory function,
506 # because there's no other way to initialize it.
507
508 # For a field initialized with a default=defaultvalue, the
509 # class dict just has the default value
510 # (cls.fieldname=defaultvalue). But that won't work for a
511 # default factory, the factory must be called in __init__
512 # and we must assign that to self.fieldname. We can't
513 # fall back to the class dict's value, both because it's
514 # not set, and because it might be different per-class
515 # (which, after all, is why we have a factory function!).
516
517 globals[default_name] = f.default_factory
518 value = f'{default_name}()'
519 else:
520 # No default factory.
521 if f.init:
522 if f.default is MISSING:
523 # There's no default, just do an assignment.
524 value = f.name
525 elif f.default is not MISSING:
526 globals[default_name] = f.default
527 value = f.name
528 else:
529 # If the class has slots, then initialize this field.
530 if slots and f.default is not MISSING:
531 globals[default_name] = f.default
532 value = default_name
533 else:
534 # This field does not need initialization: reading from it will
535 # just use the class attribute that contains the default.
536 # Signify that to the caller by returning None.
537 return None
538
539 # Only test this now, so that we can create variables for the
540 # default. However, return None to signify that we're not going
541 # to actually do the assignment statement for InitVars.
542 if f._field_type is _FIELD_INITVAR:
543 return None
544
545 # Now, actually generate the field assignment.
546 return _field_assign(frozen, f.name, value, self_name)
547
548
549 def _init_param(f):
550 # Return the __init__ parameter string for this field. For
551 # example, the equivalent of 'x:int=3' (except instead of 'int',
552 # reference a variable set to int, and instead of '3', reference a
553 # variable set to 3).
554 if f.default is MISSING and f.default_factory is MISSING:
555 # There's no default, and no default_factory, just output the
556 # variable name and type.
557 default = ''
558 elif f.default is not MISSING:
559 # There's a default, this will be the name that's used to look
560 # it up.
561 default = f'=__dataclass_dflt_{f.name}__'
562 elif f.default_factory is not MISSING:
563 # There's a factory function. Set a marker.
564 default = '=__dataclass_HAS_DEFAULT_FACTORY__'
565 return f'{f.name}:__dataclass_type_{f.name}__{default}'
566
567
568 def _init_fn(fields, std_fields, kw_only_fields, frozen, has_post_init,
569 self_name, globals, slots):
570 # fields contains both real fields and InitVar pseudo-fields.
571
572 # Make sure we don't have fields without defaults following fields
573 # with defaults. This actually would be caught when exec-ing the
574 # function source code, but catching it here gives a better error
575 # message, and future-proofs us in case we build up the function
576 # using ast.
577
578 seen_default = False
579 for f in std_fields:
580 # Only consider the non-kw-only fields in the __init__ call.
581 if f.init:
582 if not (f.default is MISSING and f.default_factory is MISSING):
583 seen_default = True
584 elif seen_default:
585 raise TypeError(f'non-default argument {f.name!r} '
586 'follows default argument')
587
588 locals = {f'__dataclass_type_{f.name}__': f.type for f in fields}
589 locals.update({
590 '__dataclass_HAS_DEFAULT_FACTORY__': _HAS_DEFAULT_FACTORY,
591 '__dataclass_builtins_object__': object,
592 })
593
594 body_lines = []
595 for f in fields:
596 line = _field_init(f, frozen, locals, self_name, slots)
597 # line is None means that this field doesn't require
598 # initialization (it's a pseudo-field). Just skip it.
599 if line:
600 body_lines.append(line)
601
602 # Does this class have a post-init function?
603 if has_post_init:
604 params_str = ','.join(f.name for f in fields
605 if f._field_type is _FIELD_INITVAR)
606 body_lines.append(f'{self_name}.{_POST_INIT_NAME}({params_str})')
607
608 # If no body lines, use 'pass'.
609 if not body_lines:
610 body_lines = ['pass']
611
612 _init_params = [_init_param(f) for f in std_fields]
613 if kw_only_fields:
614 # Add the keyword-only args. Because the * can only be added if
615 # there's at least one keyword-only arg, there needs to be a test here
616 # (instead of just concatenting the lists together).
617 _init_params += ['*']
618 _init_params += [_init_param(f) for f in kw_only_fields]
619 return _create_fn('__init__',
620 [self_name] + _init_params,
621 body_lines,
622 locals=locals,
623 globals=globals,
624 return_type=None)
625
626
627 def _repr_fn(fields, globals):
628 fn = _create_fn('__repr__',
629 ('self',),
630 ['return self.__class__.__qualname__ + f"(' +
631 ', '.join([f"{f.name}={{self.{f.name}!r}}"
632 for f in fields]) +
633 ')"'],
634 globals=globals)
635 return _recursive_repr(fn)
636
637
638 def _frozen_get_del_attr(cls, fields, globals):
639 locals = {'cls': cls,
640 'FrozenInstanceError': FrozenInstanceError}
641 condition = 'type(self) is cls'
642 if fields:
643 condition += ' or name in {' + ', '.join(repr(f.name) for f in fields) + '}'
644 return (_create_fn('__setattr__',
645 ('self', 'name', 'value'),
646 (f'if {condition}:',
647 ' raise FrozenInstanceError(f"cannot assign to field {name!r}")',
648 f'super(cls, self).__setattr__(name, value)'),
649 locals=locals,
650 globals=globals),
651 _create_fn('__delattr__',
652 ('self', 'name'),
653 (f'if {condition}:',
654 ' raise FrozenInstanceError(f"cannot delete field {name!r}")',
655 f'super(cls, self).__delattr__(name)'),
656 locals=locals,
657 globals=globals),
658 )
659
660
661 def _cmp_fn(name, op, self_tuple, other_tuple, globals):
662 # Create a comparison function. If the fields in the object are
663 # named 'x' and 'y', then self_tuple is the string
664 # '(self.x,self.y)' and other_tuple is the string
665 # '(other.x,other.y)'.
666
667 return _create_fn(name,
668 ('self', 'other'),
669 [ 'if other.__class__ is self.__class__:',
670 f' return {self_tuple}{op}{other_tuple}',
671 'return NotImplemented'],
672 globals=globals)
673
674
675 def _hash_fn(fields, globals):
676 self_tuple = _tuple_str('self', fields)
677 return _create_fn('__hash__',
678 ('self',),
679 [f'return hash({self_tuple})'],
680 globals=globals)
681
682
683 def _is_classvar(a_type, typing):
684 # This test uses a typing internal class, but it's the best way to
685 # test if this is a ClassVar.
686 return (a_type is typing.ClassVar
687 or (type(a_type) is typing._GenericAlias
688 and a_type.__origin__ is typing.ClassVar))
689
690
691 def _is_initvar(a_type, dataclasses):
692 # The module we're checking against is the module we're
693 # currently in (dataclasses.py).
694 return (a_type is dataclasses.InitVar
695 or type(a_type) is dataclasses.InitVar)
696
697 def _is_kw_only(a_type, dataclasses):
698 return a_type is dataclasses.KW_ONLY
699
700
701 def _is_type(annotation, cls, a_module, a_type, is_type_predicate):
702 # Given a type annotation string, does it refer to a_type in
703 # a_module? For example, when checking that annotation denotes a
704 # ClassVar, then a_module is typing, and a_type is
705 # typing.ClassVar.
706
707 # It's possible to look up a_module given a_type, but it involves
708 # looking in sys.modules (again!), and seems like a waste since
709 # the caller already knows a_module.
710
711 # - annotation is a string type annotation
712 # - cls is the class that this annotation was found in
713 # - a_module is the module we want to match
714 # - a_type is the type in that module we want to match
715 # - is_type_predicate is a function called with (obj, a_module)
716 # that determines if obj is of the desired type.
717
718 # Since this test does not do a local namespace lookup (and
719 # instead only a module (global) lookup), there are some things it
720 # gets wrong.
721
722 # With string annotations, cv0 will be detected as a ClassVar:
723 # CV = ClassVar
724 # @dataclass
725 # class C0:
726 # cv0: CV
727
728 # But in this example cv1 will not be detected as a ClassVar:
729 # @dataclass
730 # class C1:
731 # CV = ClassVar
732 # cv1: CV
733
734 # In C1, the code in this function (_is_type) will look up "CV" in
735 # the module and not find it, so it will not consider cv1 as a
736 # ClassVar. This is a fairly obscure corner case, and the best
737 # way to fix it would be to eval() the string "CV" with the
738 # correct global and local namespaces. However that would involve
739 # a eval() penalty for every single field of every dataclass
740 # that's defined. It was judged not worth it.
741
742 match = _MODULE_IDENTIFIER_RE.match(annotation)
743 if match:
744 ns = None
745 module_name = match.group(1)
746 if not module_name:
747 # No module name, assume the class's module did
748 # "from dataclasses import InitVar".
749 ns = sys.modules.get(cls.__module__).__dict__
750 else:
751 # Look up module_name in the class's module.
752 module = sys.modules.get(cls.__module__)
753 if module and module.__dict__.get(module_name) is a_module:
754 ns = sys.modules.get(a_type.__module__).__dict__
755 if ns and is_type_predicate(ns.get(match.group(2)), a_module):
756 return True
757 return False
758
759
760 def _get_field(cls, a_name, a_type, default_kw_only):
761 # Return a Field object for this field name and type. ClassVars and
762 # InitVars are also returned, but marked as such (see f._field_type).
763 # default_kw_only is the value of kw_only to use if there isn't a field()
764 # that defines it.
765
766 # If the default value isn't derived from Field, then it's only a
767 # normal default value. Convert it to a Field().
768 default = getattr(cls, a_name, MISSING)
769 if isinstance(default, Field):
770 f = default
771 else:
772 if isinstance(default, types.MemberDescriptorType):
773 # This is a field in __slots__, so it has no default value.
774 default = MISSING
775 f = field(default=default)
776
777 # Only at this point do we know the name and the type. Set them.
778 f.name = a_name
779 f.type = a_type
780
781 # Assume it's a normal field until proven otherwise. We're next
782 # going to decide if it's a ClassVar or InitVar, everything else
783 # is just a normal field.
784 f._field_type = _FIELD
785
786 # In addition to checking for actual types here, also check for
787 # string annotations. get_type_hints() won't always work for us
788 # (see https://github.com/python/typing/issues/508 for example),
789 # plus it's expensive and would require an eval for every string
790 # annotation. So, make a best effort to see if this is a ClassVar
791 # or InitVar using regex's and checking that the thing referenced
792 # is actually of the correct type.
793
794 # For the complete discussion, see https://bugs.python.org/issue33453
795
796 # If typing has not been imported, then it's impossible for any
797 # annotation to be a ClassVar. So, only look for ClassVar if
798 # typing has been imported by any module (not necessarily cls's
799 # module).
800 typing = sys.modules.get('typing')
801 if typing:
802 if (_is_classvar(a_type, typing)
803 or (isinstance(f.type, str)
804 and _is_type(f.type, cls, typing, typing.ClassVar,
805 _is_classvar))):
806 f._field_type = _FIELD_CLASSVAR
807
808 # If the type is InitVar, or if it's a matching string annotation,
809 # then it's an InitVar.
810 if f._field_type is _FIELD:
811 # The module we're checking against is the module we're
812 # currently in (dataclasses.py).
813 dataclasses = sys.modules[__name__]
814 if (_is_initvar(a_type, dataclasses)
815 or (isinstance(f.type, str)
816 and _is_type(f.type, cls, dataclasses, dataclasses.InitVar,
817 _is_initvar))):
818 f._field_type = _FIELD_INITVAR
819
820 # Validations for individual fields. This is delayed until now,
821 # instead of in the Field() constructor, since only here do we
822 # know the field name, which allows for better error reporting.
823
824 # Special restrictions for ClassVar and InitVar.
825 if f._field_type in (_FIELD_CLASSVAR, _FIELD_INITVAR):
826 if f.default_factory is not MISSING:
827 raise TypeError(f'field {f.name} cannot have a '
828 'default factory')
829 # Should I check for other field settings? default_factory
830 # seems the most serious to check for. Maybe add others. For
831 # example, how about init=False (or really,
832 # init=<not-the-default-init-value>)? It makes no sense for
833 # ClassVar and InitVar to specify init=<anything>.
834
835 # kw_only validation and assignment.
836 if f._field_type in (_FIELD, _FIELD_INITVAR):
837 # For real and InitVar fields, if kw_only wasn't specified use the
838 # default value.
839 if f.kw_only is MISSING:
840 f.kw_only = default_kw_only
841 else:
842 # Make sure kw_only isn't set for ClassVars
843 assert f._field_type is _FIELD_CLASSVAR
844 if f.kw_only is not MISSING:
845 raise TypeError(f'field {f.name} is a ClassVar but specifies '
846 'kw_only')
847
848 # For real fields, disallow mutable defaults. Use unhashable as a proxy
849 # indicator for mutability. Read the __hash__ attribute from the class,
850 # not the instance.
851 if f._field_type is _FIELD and f.default.__class__.__hash__ is None:
852 raise ValueError(f'mutable default {type(f.default)} for field '
853 f'{f.name} is not allowed: use default_factory')
854
855 return f
856
857 def _set_qualname(cls, value):
858 # Ensure that the functions returned from _create_fn uses the proper
859 # __qualname__ (the class they belong to).
860 if isinstance(value, FunctionType):
861 value.__qualname__ = f"{cls.__qualname__}.{value.__name__}"
862 return value
863
864 def _set_new_attribute(cls, name, value):
865 # Never overwrites an existing attribute. Returns True if the
866 # attribute already exists.
867 if name in cls.__dict__:
868 return True
869 _set_qualname(cls, value)
870 setattr(cls, name, value)
871 return False
872
873
874 # Decide if/how we're going to create a hash function. Key is
875 # (unsafe_hash, eq, frozen, does-hash-exist). Value is the action to
876 # take. The common case is to do nothing, so instead of providing a
877 # function that is a no-op, use None to signify that.
878
879 def _hash_set_none(cls, fields, globals):
880 return None
881
882 def _hash_add(cls, fields, globals):
883 flds = [f for f in fields if (f.compare if f.hash is None else f.hash)]
884 return _set_qualname(cls, _hash_fn(flds, globals))
885
886 def _hash_exception(cls, fields, globals):
887 # Raise an exception.
888 raise TypeError(f'Cannot overwrite attribute __hash__ '
889 f'in class {cls.__name__}')
890
891 #
892 # +-------------------------------------- unsafe_hash?
893 # | +------------------------------- eq?
894 # | | +------------------------ frozen?
895 # | | | +---------------- has-explicit-hash?
896 # | | | |
897 # | | | | +------- action
898 # | | | | |
899 # v v v v v
900 _hash_action = {(False, False, False, False): None,
901 (False, False, False, True ): None,
902 (False, False, True, False): None,
903 (False, False, True, True ): None,
904 (False, True, False, False): _hash_set_none,
905 (False, True, False, True ): None,
906 (False, True, True, False): _hash_add,
907 (False, True, True, True ): None,
908 (True, False, False, False): _hash_add,
909 (True, False, False, True ): _hash_exception,
910 (True, False, True, False): _hash_add,
911 (True, False, True, True ): _hash_exception,
912 (True, True, False, False): _hash_add,
913 (True, True, False, True ): _hash_exception,
914 (True, True, True, False): _hash_add,
915 (True, True, True, True ): _hash_exception,
916 }
917 # See https://bugs.python.org/issue32929#msg312829 for an if-statement
918 # version of this table.
919
920
921 def _process_class(cls, init, repr, eq, order, unsafe_hash, frozen,
922 match_args, kw_only, slots, weakref_slot):
923 # Now that dicts retain insertion order, there's no reason to use
924 # an ordered dict. I am leveraging that ordering here, because
925 # derived class fields overwrite base class fields, but the order
926 # is defined by the base class, which is found first.
927 fields = {}
928
929 if cls.__module__ in sys.modules:
930 globals = sys.modules[cls.__module__].__dict__
931 else:
932 # Theoretically this can happen if someone writes
933 # a custom string to cls.__module__. In which case
934 # such dataclass won't be fully introspectable
935 # (w.r.t. typing.get_type_hints) but will still function
936 # correctly.
937 globals = {}
938
939 setattr(cls, _PARAMS, _DataclassParams(init, repr, eq, order,
940 unsafe_hash, frozen,
941 match_args, kw_only,
942 slots, weakref_slot))
943
944 # Find our base classes in reverse MRO order, and exclude
945 # ourselves. In reversed order so that more derived classes
946 # override earlier field definitions in base classes. As long as
947 # we're iterating over them, see if any are frozen.
948 any_frozen_base = False
949 has_dataclass_bases = False
950 for b in cls.__mro__[-1:0:-1]:
951 # Only process classes that have been processed by our
952 # decorator. That is, they have a _FIELDS attribute.
953 base_fields = getattr(b, _FIELDS, None)
954 if base_fields is not None:
955 has_dataclass_bases = True
956 for f in base_fields.values():
957 fields[f.name] = f
958 if getattr(b, _PARAMS).frozen:
959 any_frozen_base = True
960
961 # Annotations defined specifically in this class (not in base classes).
962 #
963 # Fields are found from cls_annotations, which is guaranteed to be
964 # ordered. Default values are from class attributes, if a field
965 # has a default. If the default value is a Field(), then it
966 # contains additional info beyond (and possibly including) the
967 # actual default value. Pseudo-fields ClassVars and InitVars are
968 # included, despite the fact that they're not real fields. That's
969 # dealt with later.
970 cls_annotations = inspect.get_annotations(cls)
971
972 # Now find fields in our class. While doing so, validate some
973 # things, and set the default values (as class attributes) where
974 # we can.
975 cls_fields = []
976 # Get a reference to this module for the _is_kw_only() test.
977 KW_ONLY_seen = False
978 dataclasses = sys.modules[__name__]
979 for name, type in cls_annotations.items():
980 # See if this is a marker to change the value of kw_only.
981 if (_is_kw_only(type, dataclasses)
982 or (isinstance(type, str)
983 and _is_type(type, cls, dataclasses, dataclasses.KW_ONLY,
984 _is_kw_only))):
985 # Switch the default to kw_only=True, and ignore this
986 # annotation: it's not a real field.
987 if KW_ONLY_seen:
988 raise TypeError(f'{name!r} is KW_ONLY, but KW_ONLY '
989 'has already been specified')
990 KW_ONLY_seen = True
991 kw_only = True
992 else:
993 # Otherwise it's a field of some type.
994 cls_fields.append(_get_field(cls, name, type, kw_only))
995
996 for f in cls_fields:
997 fields[f.name] = f
998
999 # If the class attribute (which is the default value for this
1000 # field) exists and is of type 'Field', replace it with the
1001 # real default. This is so that normal class introspection
1002 # sees a real default value, not a Field.
1003 if isinstance(getattr(cls, f.name, None), Field):
1004 if f.default is MISSING:
1005 # If there's no default, delete the class attribute.
1006 # This happens if we specify field(repr=False), for
1007 # example (that is, we specified a field object, but
1008 # no default value). Also if we're using a default
1009 # factory. The class attribute should not be set at
1010 # all in the post-processed class.
1011 delattr(cls, f.name)
1012 else:
1013 setattr(cls, f.name, f.default)
1014
1015 # Do we have any Field members that don't also have annotations?
1016 for name, value in cls.__dict__.items():
1017 if isinstance(value, Field) and not name in cls_annotations:
1018 raise TypeError(f'{name!r} is a field but has no type annotation')
1019
1020 # Check rules that apply if we are derived from any dataclasses.
1021 if has_dataclass_bases:
1022 # Raise an exception if any of our bases are frozen, but we're not.
1023 if any_frozen_base and not frozen:
1024 raise TypeError('cannot inherit non-frozen dataclass from a '
1025 'frozen one')
1026
1027 # Raise an exception if we're frozen, but none of our bases are.
1028 if not any_frozen_base and frozen:
1029 raise TypeError('cannot inherit frozen dataclass from a '
1030 'non-frozen one')
1031
1032 # Remember all of the fields on our class (including bases). This
1033 # also marks this class as being a dataclass.
1034 setattr(cls, _FIELDS, fields)
1035
1036 # Was this class defined with an explicit __hash__? Note that if
1037 # __eq__ is defined in this class, then python will automatically
1038 # set __hash__ to None. This is a heuristic, as it's possible
1039 # that such a __hash__ == None was not auto-generated, but it
1040 # close enough.
1041 class_hash = cls.__dict__.get('__hash__', MISSING)
1042 has_explicit_hash = not (class_hash is MISSING or
1043 (class_hash is None and '__eq__' in cls.__dict__))
1044
1045 # If we're generating ordering methods, we must be generating the
1046 # eq methods.
1047 if order and not eq:
1048 raise ValueError('eq must be true if order is true')
1049
1050 # Include InitVars and regular fields (so, not ClassVars). This is
1051 # initialized here, outside of the "if init:" test, because std_init_fields
1052 # is used with match_args, below.
1053 all_init_fields = [f for f in fields.values()
1054 if f._field_type in (_FIELD, _FIELD_INITVAR)]
1055 (std_init_fields,
1056 kw_only_init_fields) = _fields_in_init_order(all_init_fields)
1057
1058 if init:
1059 # Does this class have a post-init function?
1060 has_post_init = hasattr(cls, _POST_INIT_NAME)
1061
1062 _set_new_attribute(cls, '__init__',
1063 _init_fn(all_init_fields,
1064 std_init_fields,
1065 kw_only_init_fields,
1066 frozen,
1067 has_post_init,
1068 # The name to use for the "self"
1069 # param in __init__. Use "self"
1070 # if possible.
1071 '__dataclass_self__' if 'self' in fields
1072 else 'self',
1073 globals,
1074 slots,
1075 ))
1076
1077 # Get the fields as a list, and include only real fields. This is
1078 # used in all of the following methods.
1079 field_list = [f for f in fields.values() if f._field_type is _FIELD]
1080
1081 if repr:
1082 flds = [f for f in field_list if f.repr]
1083 _set_new_attribute(cls, '__repr__', _repr_fn(flds, globals))
1084
1085 if eq:
1086 # Create __eq__ method. There's no need for a __ne__ method,
1087 # since python will call __eq__ and negate it.
1088 flds = [f for f in field_list if f.compare]
1089 self_tuple = _tuple_str('self', flds)
1090 other_tuple = _tuple_str('other', flds)
1091 _set_new_attribute(cls, '__eq__',
1092 _cmp_fn('__eq__', '==',
1093 self_tuple, other_tuple,
1094 globals=globals))
1095
1096 if order:
1097 # Create and set the ordering methods.
1098 flds = [f for f in field_list if f.compare]
1099 self_tuple = _tuple_str('self', flds)
1100 other_tuple = _tuple_str('other', flds)
1101 for name, op in [('__lt__', '<'),
1102 ('__le__', '<='),
1103 ('__gt__', '>'),
1104 ('__ge__', '>='),
1105 ]:
1106 if _set_new_attribute(cls, name,
1107 _cmp_fn(name, op, self_tuple, other_tuple,
1108 globals=globals)):
1109 raise TypeError(f'Cannot overwrite attribute {name} '
1110 f'in class {cls.__name__}. Consider using '
1111 'functools.total_ordering')
1112
1113 if frozen:
1114 for fn in _frozen_get_del_attr(cls, field_list, globals):
1115 if _set_new_attribute(cls, fn.__name__, fn):
1116 raise TypeError(f'Cannot overwrite attribute {fn.__name__} '
1117 f'in class {cls.__name__}')
1118
1119 # Decide if/how we're going to create a hash function.
1120 hash_action = _hash_action[bool(unsafe_hash),
1121 bool(eq),
1122 bool(frozen),
1123 has_explicit_hash]
1124 if hash_action:
1125 # No need to call _set_new_attribute here, since by the time
1126 # we're here the overwriting is unconditional.
1127 cls.__hash__ = hash_action(cls, field_list, globals)
1128
1129 if not getattr(cls, '__doc__'):
1130 # Create a class doc-string.
1131 try:
1132 # In some cases fetching a signature is not possible.
1133 # But, we surely should not fail in this case.
1134 text_sig = str(inspect.signature(cls)).replace(' -> None', '')
1135 except (TypeError, ValueError):
1136 text_sig = ''
1137 cls.__doc__ = (cls.__name__ + text_sig)
1138
1139 if match_args:
1140 # I could probably compute this once
1141 _set_new_attribute(cls, '__match_args__',
1142 tuple(f.name for f in std_init_fields))
1143
1144 # It's an error to specify weakref_slot if slots is False.
1145 if weakref_slot and not slots:
1146 raise TypeError('weakref_slot is True but slots is False')
1147 if slots:
1148 cls = _add_slots(cls, frozen, weakref_slot)
1149
1150 abc.update_abstractmethods(cls)
1151
1152 return cls
1153
1154
1155 # _dataclass_getstate and _dataclass_setstate are needed for pickling frozen
1156 # classes with slots. These could be slightly more performant if we generated
1157 # the code instead of iterating over fields. But that can be a project for
1158 # another day, if performance becomes an issue.
1159 def _dataclass_getstate(self):
1160 return [getattr(self, f.name) for f in fields(self)]
1161
1162
1163 def _dataclass_setstate(self, state):
1164 for field, value in zip(fields(self), state):
1165 # use setattr because dataclass may be frozen
1166 object.__setattr__(self, field.name, value)
1167
1168
1169 def _get_slots(cls):
1170 match cls.__dict__.get('__slots__'):
1171 case None:
1172 return
1173 case str(slot):
1174 yield slot
1175 # Slots may be any iterable, but we cannot handle an iterator
1176 # because it will already be (partially) consumed.
1177 case iterable if not hasattr(iterable, '__next__'):
1178 yield from iterable
1179 case _:
1180 raise TypeError(f"Slots of '{cls.__name__}' cannot be determined")
1181
1182
1183 def _add_slots(cls, is_frozen, weakref_slot):
1184 # Need to create a new class, since we can't set __slots__
1185 # after a class has been created.
1186
1187 # Make sure __slots__ isn't already set.
1188 if '__slots__' in cls.__dict__:
1189 raise TypeError(f'{cls.__name__} already specifies __slots__')
1190
1191 # Create a new dict for our new class.
1192 cls_dict = dict(cls.__dict__)
1193 field_names = tuple(f.name for f in fields(cls))
1194 # Make sure slots don't overlap with those in base classes.
1195 inherited_slots = set(
1196 itertools.chain.from_iterable(map(_get_slots, cls.__mro__[1:-1]))
1197 )
1198 # The slots for our class. Remove slots from our base classes. Add
1199 # '__weakref__' if weakref_slot was given, unless it is already present.
1200 cls_dict["__slots__"] = tuple(
1201 itertools.filterfalse(
1202 inherited_slots.__contains__,
1203 itertools.chain(
1204 # gh-93521: '__weakref__' also needs to be filtered out if
1205 # already present in inherited_slots
1206 field_names, ('__weakref__',) if weakref_slot else ()
1207 )
1208 ),
1209 )
1210
1211 for field_name in field_names:
1212 # Remove our attributes, if present. They'll still be
1213 # available in _MARKER.
1214 cls_dict.pop(field_name, None)
1215
1216 # Remove __dict__ itself.
1217 cls_dict.pop('__dict__', None)
1218
1219 # Clear existing `__weakref__` descriptor, it belongs to a previous type:
1220 cls_dict.pop('__weakref__', None) # gh-102069
1221
1222 # And finally create the class.
1223 qualname = getattr(cls, '__qualname__', None)
1224 cls = type(cls)(cls.__name__, cls.__bases__, cls_dict)
1225 if qualname is not None:
1226 cls.__qualname__ = qualname
1227
1228 if is_frozen:
1229 # Need this for pickling frozen classes with slots.
1230 if '__getstate__' not in cls_dict:
1231 cls.__getstate__ = _dataclass_getstate
1232 if '__setstate__' not in cls_dict:
1233 cls.__setstate__ = _dataclass_setstate
1234
1235 return cls
1236
1237
1238 def dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False,
1239 unsafe_hash=False, frozen=False, match_args=True,
1240 kw_only=False, slots=False, weakref_slot=False):
1241 """Add dunder methods based on the fields defined in the class.
1242
1243 Examines PEP 526 __annotations__ to determine fields.
1244
1245 If init is true, an __init__() method is added to the class. If repr
1246 is true, a __repr__() method is added. If order is true, rich
1247 comparison dunder methods are added. If unsafe_hash is true, a
1248 __hash__() method is added. If frozen is true, fields may not be
1249 assigned to after instance creation. If match_args is true, the
1250 __match_args__ tuple is added. If kw_only is true, then by default
1251 all fields are keyword-only. If slots is true, a new class with a
1252 __slots__ attribute is returned.
1253 """
1254
1255 def wrap(cls):
1256 return _process_class(cls, init, repr, eq, order, unsafe_hash,
1257 frozen, match_args, kw_only, slots,
1258 weakref_slot)
1259
1260 # See if we're being called as @dataclass or @dataclass().
1261 if cls is None:
1262 # We're called with parens.
1263 return wrap
1264
1265 # We're called as @dataclass without parens.
1266 return wrap(cls)
1267
1268
1269 def fields(class_or_instance):
1270 """Return a tuple describing the fields of this dataclass.
1271
1272 Accepts a dataclass or an instance of one. Tuple elements are of
1273 type Field.
1274 """
1275
1276 # Might it be worth caching this, per class?
1277 try:
1278 fields = getattr(class_or_instance, _FIELDS)
1279 except AttributeError:
1280 raise TypeError('must be called with a dataclass type or instance') from None
1281
1282 # Exclude pseudo-fields. Note that fields is sorted by insertion
1283 # order, so the order of the tuple is as the fields were defined.
1284 return tuple(f for f in fields.values() if f._field_type is _FIELD)
1285
1286
1287 def _is_dataclass_instance(obj):
1288 """Returns True if obj is an instance of a dataclass."""
1289 return hasattr(type(obj), _FIELDS)
1290
1291
1292 def is_dataclass(obj):
1293 """Returns True if obj is a dataclass or an instance of a
1294 dataclass."""
1295 cls = obj if isinstance(obj, type) else type(obj)
1296 return hasattr(cls, _FIELDS)
1297
1298
1299 def asdict(obj, *, dict_factory=dict):
1300 """Return the fields of a dataclass instance as a new dictionary mapping
1301 field names to field values.
1302
1303 Example usage::
1304
1305 @dataclass
1306 class C:
1307 x: int
1308 y: int
1309
1310 c = C(1, 2)
1311 assert asdict(c) == {'x': 1, 'y': 2}
1312
1313 If given, 'dict_factory' will be used instead of built-in dict.
1314 The function applies recursively to field values that are
1315 dataclass instances. This will also look into built-in containers:
1316 tuples, lists, and dicts. Other objects are copied with 'copy.deepcopy()'.
1317 """
1318 if not _is_dataclass_instance(obj):
1319 raise TypeError("asdict() should be called on dataclass instances")
1320 return _asdict_inner(obj, dict_factory)
1321
1322
1323 def _asdict_inner(obj, dict_factory):
1324 if type(obj) in _ATOMIC_TYPES:
1325 return obj
1326 elif _is_dataclass_instance(obj):
1327 # fast path for the common case
1328 if dict_factory is dict:
1329 return {
1330 f.name: _asdict_inner(getattr(obj, f.name), dict)
1331 for f in fields(obj)
1332 }
1333 else:
1334 result = []
1335 for f in fields(obj):
1336 value = _asdict_inner(getattr(obj, f.name), dict_factory)
1337 result.append((f.name, value))
1338 return dict_factory(result)
1339 elif isinstance(obj, tuple) and hasattr(obj, '_fields'):
1340 # obj is a namedtuple. Recurse into it, but the returned
1341 # object is another namedtuple of the same type. This is
1342 # similar to how other list- or tuple-derived classes are
1343 # treated (see below), but we just need to create them
1344 # differently because a namedtuple's __init__ needs to be
1345 # called differently (see bpo-34363).
1346
1347 # I'm not using namedtuple's _asdict()
1348 # method, because:
1349 # - it does not recurse in to the namedtuple fields and
1350 # convert them to dicts (using dict_factory).
1351 # - I don't actually want to return a dict here. The main
1352 # use case here is json.dumps, and it handles converting
1353 # namedtuples to lists. Admittedly we're losing some
1354 # information here when we produce a json list instead of a
1355 # dict. Note that if we returned dicts here instead of
1356 # namedtuples, we could no longer call asdict() on a data
1357 # structure where a namedtuple was used as a dict key.
1358
1359 return type(obj)(*[_asdict_inner(v, dict_factory) for v in obj])
1360 elif isinstance(obj, (list, tuple)):
1361 # Assume we can create an object of this type by passing in a
1362 # generator (which is not true for namedtuples, handled
1363 # above).
1364 return type(obj)(_asdict_inner(v, dict_factory) for v in obj)
1365 elif isinstance(obj, dict):
1366 if hasattr(type(obj), 'default_factory'):
1367 # obj is a defaultdict, which has a different constructor from
1368 # dict as it requires the default_factory as its first arg.
1369 result = type(obj)(getattr(obj, 'default_factory'))
1370 for k, v in obj.items():
1371 result[_asdict_inner(k, dict_factory)] = _asdict_inner(v, dict_factory)
1372 return result
1373 return type(obj)((_asdict_inner(k, dict_factory),
1374 _asdict_inner(v, dict_factory))
1375 for k, v in obj.items())
1376 else:
1377 return copy.deepcopy(obj)
1378
1379
1380 def astuple(obj, *, tuple_factory=tuple):
1381 """Return the fields of a dataclass instance as a new tuple of field values.
1382
1383 Example usage::
1384
1385 @dataclass
1386 class C:
1387 x: int
1388 y: int
1389
1390 c = C(1, 2)
1391 assert astuple(c) == (1, 2)
1392
1393 If given, 'tuple_factory' will be used instead of built-in tuple.
1394 The function applies recursively to field values that are
1395 dataclass instances. This will also look into built-in containers:
1396 tuples, lists, and dicts. Other objects are copied with 'copy.deepcopy()'.
1397 """
1398
1399 if not _is_dataclass_instance(obj):
1400 raise TypeError("astuple() should be called on dataclass instances")
1401 return _astuple_inner(obj, tuple_factory)
1402
1403
1404 def _astuple_inner(obj, tuple_factory):
1405 if type(obj) in _ATOMIC_TYPES:
1406 return obj
1407 elif _is_dataclass_instance(obj):
1408 result = []
1409 for f in fields(obj):
1410 value = _astuple_inner(getattr(obj, f.name), tuple_factory)
1411 result.append(value)
1412 return tuple_factory(result)
1413 elif isinstance(obj, tuple) and hasattr(obj, '_fields'):
1414 # obj is a namedtuple. Recurse into it, but the returned
1415 # object is another namedtuple of the same type. This is
1416 # similar to how other list- or tuple-derived classes are
1417 # treated (see below), but we just need to create them
1418 # differently because a namedtuple's __init__ needs to be
1419 # called differently (see bpo-34363).
1420 return type(obj)(*[_astuple_inner(v, tuple_factory) for v in obj])
1421 elif isinstance(obj, (list, tuple)):
1422 # Assume we can create an object of this type by passing in a
1423 # generator (which is not true for namedtuples, handled
1424 # above).
1425 return type(obj)(_astuple_inner(v, tuple_factory) for v in obj)
1426 elif isinstance(obj, dict):
1427 obj_type = type(obj)
1428 if hasattr(obj_type, 'default_factory'):
1429 # obj is a defaultdict, which has a different constructor from
1430 # dict as it requires the default_factory as its first arg.
1431 result = obj_type(getattr(obj, 'default_factory'))
1432 for k, v in obj.items():
1433 result[_astuple_inner(k, tuple_factory)] = _astuple_inner(v, tuple_factory)
1434 return result
1435 return obj_type((_astuple_inner(k, tuple_factory), _astuple_inner(v, tuple_factory))
1436 for k, v in obj.items())
1437 else:
1438 return copy.deepcopy(obj)
1439
1440
1441 def make_dataclass(cls_name, fields, *, bases=(), namespace=None, init=True,
1442 repr=True, eq=True, order=False, unsafe_hash=False,
1443 frozen=False, match_args=True, kw_only=False, slots=False,
1444 weakref_slot=False, module=None):
1445 """Return a new dynamically created dataclass.
1446
1447 The dataclass name will be 'cls_name'. 'fields' is an iterable
1448 of either (name), (name, type) or (name, type, Field) objects. If type is
1449 omitted, use the string 'typing.Any'. Field objects are created by
1450 the equivalent of calling 'field(name, type [, Field-info])'.::
1451
1452 C = make_dataclass('C', ['x', ('y', int), ('z', int, field(init=False))], bases=(Base,))
1453
1454 is equivalent to::
1455
1456 @dataclass
1457 class C(Base):
1458 x: 'typing.Any'
1459 y: int
1460 z: int = field(init=False)
1461
1462 For the bases and namespace parameters, see the builtin type() function.
1463
1464 The parameters init, repr, eq, order, unsafe_hash, frozen, match_args, kw_only,
1465 slots, and weakref_slot are passed to dataclass().
1466
1467 If module parameter is defined, the '__module__' attribute of the dataclass is
1468 set to that value.
1469 """
1470
1471 if namespace is None:
1472 namespace = {}
1473
1474 # While we're looking through the field names, validate that they
1475 # are identifiers, are not keywords, and not duplicates.
1476 seen = set()
1477 annotations = {}
1478 defaults = {}
1479 for item in fields:
1480 if isinstance(item, str):
1481 name = item
1482 tp = 'typing.Any'
1483 elif len(item) == 2:
1484 name, tp, = item
1485 elif len(item) == 3:
1486 name, tp, spec = item
1487 defaults[name] = spec
1488 else:
1489 raise TypeError(f'Invalid field: {item!r}')
1490
1491 if not isinstance(name, str) or not name.isidentifier():
1492 raise TypeError(f'Field names must be valid identifiers: {name!r}')
1493 if keyword.iskeyword(name):
1494 raise TypeError(f'Field names must not be keywords: {name!r}')
1495 if name in seen:
1496 raise TypeError(f'Field name duplicated: {name!r}')
1497
1498 seen.add(name)
1499 annotations[name] = tp
1500
1501 # Update 'ns' with the user-supplied namespace plus our calculated values.
1502 def exec_body_callback(ns):
1503 ns.update(namespace)
1504 ns.update(defaults)
1505 ns['__annotations__'] = annotations
1506
1507 # We use `types.new_class()` instead of simply `type()` to allow dynamic creation
1508 # of generic dataclasses.
1509 cls = types.new_class(cls_name, bases, {}, exec_body_callback)
1510
1511 # For pickling to work, the __module__ variable needs to be set to the frame
1512 # where the dataclass is created.
1513 if module is None:
1514 try:
1515 module = sys._getframemodulename(1) or '__main__'
1516 except AttributeError:
1517 try:
1518 module = sys._getframe(1).f_globals.get('__name__', '__main__')
1519 except (AttributeError, ValueError):
1520 pass
1521 if module is not None:
1522 cls.__module__ = module
1523
1524 # Apply the normal decorator.
1525 return dataclass(cls, init=init, repr=repr, eq=eq, order=order,
1526 unsafe_hash=unsafe_hash, frozen=frozen,
1527 match_args=match_args, kw_only=kw_only, slots=slots,
1528 weakref_slot=weakref_slot)
1529
1530
1531 def replace(obj, /, **changes):
1532 """Return a new object replacing specified fields with new values.
1533
1534 This is especially useful for frozen classes. Example usage::
1535
1536 @dataclass(frozen=True)
1537 class C:
1538 x: int
1539 y: int
1540
1541 c = C(1, 2)
1542 c1 = replace(c, x=3)
1543 assert c1.x == 3 and c1.y == 2
1544 """
1545
1546 # We're going to mutate 'changes', but that's okay because it's a
1547 # new dict, even if called with 'replace(obj, **my_changes)'.
1548
1549 if not _is_dataclass_instance(obj):
1550 raise TypeError("replace() should be called on dataclass instances")
1551
1552 # It's an error to have init=False fields in 'changes'.
1553 # If a field is not in 'changes', read its value from the provided obj.
1554
1555 for f in getattr(obj, _FIELDS).values():
1556 # Only consider normal fields or InitVars.
1557 if f._field_type is _FIELD_CLASSVAR:
1558 continue
1559
1560 if not f.init:
1561 # Error if this field is specified in changes.
1562 if f.name in changes:
1563 raise ValueError(f'field {f.name} is declared with '
1564 'init=False, it cannot be specified with '
1565 'replace()')
1566 continue
1567
1568 if f.name not in changes:
1569 if f._field_type is _FIELD_INITVAR and f.default is MISSING:
1570 raise ValueError(f"InitVar {f.name!r} "
1571 'must be specified with replace()')
1572 changes[f.name] = getattr(obj, f.name)
1573
1574 # Create the new object, which calls __init__() and
1575 # __post_init__() (if defined), using all of the init fields we've
1576 # added and/or left in 'changes'. If there are values supplied in
1577 # changes that aren't fields, this will correctly raise a
1578 # TypeError.
1579 return obj.__class__(**changes)