dataclasses.py
3
import copy
4
import types
5
import inspect
6
import keyword
11
from types import FunctionType, GenericAlias
13
14
__all__ = ['dataclass',
15
'field',
17
'FrozenInstanceError',
18
'InitVar',
19
'KW_ONLY',
21
22
# Helper functions.
23
'fields',
24
'asdict',
25
'astuple',
26
'make_dataclass',
27
'replace',
28
'is_dataclass',
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.
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.
171
# Raised when an attempt is made to modify a frozen class.
172
class FrozenInstanceError(AttributeError): 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 _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 _MISSING_TYPE:
185
pass
186
MISSING = _MISSING_TYPE()
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 _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 _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+)')
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
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}]'
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 Field:
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}'
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)
352
# There is a __set_name__ method on the descriptor, call
353
# it.
354
func(self.default, owner, name)
356
__class_getitem__ = classmethod(GenericAlias)
357
359
class _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',
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}'
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)
463
# Compute the text of the entire function.
464
txt = f' def {name}({args}){return_annotation}:\n{body}'
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.
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}'
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.
578
seen_default = None
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 = f
584
elif seen_default:
585
raise TypeError(f'non-default argument {f.name!r} '
586
f'follows default argument {seen_default.name!r}')
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,
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 f"{self.__class__.__qualname__}(' +
631
', '.join([f"{f.name}={{self.{f.name}!r}}"
632
for f in fields]) +
633
')"'],
634
globals=globals)
635
return _recursive_repr(fn)
638
def _frozen_get_del_attr(cls, fields, globals):
639
locals = {'cls': cls,
640
'FrozenInstanceError': FrozenInstanceError}
641
condition = 'type(self) is cls'
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
)
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)
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)
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)
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.
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>.
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
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__:
869
_set_qualname(cls, value)
870
setattr(cls, name, value)
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.
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))
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.
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.
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))
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
961
# Annotations defined specifically in this class (not in base classes).
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)
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