dataclasses
1import re 2import sys 3import copy 4import types 5import inspect 6import keyword 7import functools 8import itertools 9import abc 10import _thread 11from 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. 172class 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. 177class _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. 184class _MISSING_TYPE: 185 pass 186MISSING = _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. 190class _KW_ONLY_TYPE: 191 pass 192KW_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. 199class _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. 250def _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 268class InitVar: 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. 295class 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}' 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 359class _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. 404def 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 428def _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 437def _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 449def _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 477def _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 489def _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 549def _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 568def _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 627def _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 638def _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 661def _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 675def _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 683def _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 691def _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 697def _is_kw_only(a_type, dataclasses): 698 return a_type is dataclasses.KW_ONLY 699 700 701def _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 760def _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 857def _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 864def _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 879def _hash_set_none(cls, fields, globals): 880 return None 881 882def _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 886def _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 921def _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. 1159def _dataclass_getstate(self): 1160 return [getattr(self, f.name) for f in fields(self)] 1161 1162 1163def _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 1169def _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 1183def _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 1238def 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 1269def 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 1287def _is_dataclass_instance(obj): 1288 """Returns True if obj is an instance of a dataclass.""" 1289 return hasattr(type(obj), _FIELDS) 1290 1291 1292def 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 1299def 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 1323def _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 1380def 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 1404def _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 1441def 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 1531def 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)
1239def dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False, 1240 unsafe_hash=False, frozen=False, match_args=True, 1241 kw_only=False, slots=False, weakref_slot=False): 1242 """Add dunder methods based on the fields defined in the class. 1243 1244 Examines PEP 526 __annotations__ to determine fields. 1245 1246 If init is true, an __init__() method is added to the class. If repr 1247 is true, a __repr__() method is added. If order is true, rich 1248 comparison dunder methods are added. If unsafe_hash is true, a 1249 __hash__() method is added. If frozen is true, fields may not be 1250 assigned to after instance creation. If match_args is true, the 1251 __match_args__ tuple is added. If kw_only is true, then by default 1252 all fields are keyword-only. If slots is true, a new class with a 1253 __slots__ attribute is returned. 1254 """ 1255 1256 def wrap(cls): 1257 return _process_class(cls, init, repr, eq, order, unsafe_hash, 1258 frozen, match_args, kw_only, slots, 1259 weakref_slot) 1260 1261 # See if we're being called as @dataclass or @dataclass(). 1262 if cls is None: 1263 # We're called with parens. 1264 return wrap 1265 1266 # We're called as @dataclass without parens. 1267 return wrap(cls)
Add dunder methods based on the fields defined in the class.
Examines PEP 526 __annotations__ to determine fields.
If init is true, an __init__() method is added to the class. If repr is true, a __repr__() method is added. If order is true, rich comparison dunder methods are added. If unsafe_hash is true, a __hash__() method is added. If frozen is true, fields may not be assigned to after instance creation. If match_args is true, the __match_args__ tuple is added. If kw_only is true, then by default all fields are keyword-only. If slots is true, a new class with a __slots__ attribute is returned.
405def field(*, default=MISSING, default_factory=MISSING, init=True, repr=True, 406 hash=None, compare=True, metadata=None, kw_only=MISSING): 407 """Return an object to identify dataclass fields. 408 409 default is the default value of the field. default_factory is a 410 0-argument function called to initialize a field's value. If init 411 is true, the field will be a parameter to the class's __init__() 412 function. If repr is true, the field will be included in the 413 object's repr(). If hash is true, the field will be included in the 414 object's hash(). If compare is true, the field will be used in 415 comparison functions. metadata, if specified, must be a mapping 416 which is stored but not otherwise examined by dataclass. If kw_only 417 is true, the field will become a keyword-only parameter to 418 __init__(). 419 420 It is an error to specify both default and default_factory. 421 """ 422 423 if default is not MISSING and default_factory is not MISSING: 424 raise ValueError('cannot specify both default and default_factory') 425 return Field(default, default_factory, init, repr, hash, compare, 426 metadata, kw_only)
Return an object to identify dataclass fields.
default is the default value of the field. default_factory is a 0-argument function called to initialize a field's value. If init is true, the field will be a parameter to the class's __init__() function. If repr is true, the field will be included in the object's repr(). If hash is true, the field will be included in the object's hash(). If compare is true, the field will be used in comparison functions. metadata, if specified, must be a mapping which is stored but not otherwise examined by dataclass. If kw_only is true, the field will become a keyword-only parameter to __init__().
It is an error to specify both default and default_factory.
296class Field: 297 __slots__ = ('name', 298 'type', 299 'default', 300 'default_factory', 301 'repr', 302 'hash', 303 'init', 304 'compare', 305 'metadata', 306 'kw_only', 307 '_field_type', # Private: not to be used by user code. 308 ) 309 310 def __init__(self, default, default_factory, init, repr, hash, compare, 311 metadata, kw_only): 312 self.name = None 313 self.type = None 314 self.default = default 315 self.default_factory = default_factory 316 self.init = init 317 self.repr = repr 318 self.hash = hash 319 self.compare = compare 320 self.metadata = (_EMPTY_METADATA 321 if metadata is None else 322 types.MappingProxyType(metadata)) 323 self.kw_only = kw_only 324 self._field_type = None 325 326 @_recursive_repr 327 def __repr__(self): 328 return ('Field(' 329 f'name={self.name!r},' 330 f'type={self.type!r},' 331 f'default={self.default!r},' 332 f'default_factory={self.default_factory!r},' 333 f'init={self.init!r},' 334 f'repr={self.repr!r},' 335 f'hash={self.hash!r},' 336 f'compare={self.compare!r},' 337 f'metadata={self.metadata!r},' 338 f'kw_only={self.kw_only!r},' 339 f'_field_type={self._field_type}' 340 ')') 341 342 # This is used to support the PEP 487 __set_name__ protocol in the 343 # case where we're using a field that contains a descriptor as a 344 # default value. For details on __set_name__, see 345 # https://peps.python.org/pep-0487/#implementation-details. 346 # 347 # Note that in _process_class, this Field object is overwritten 348 # with the default value, so the end result is a descriptor that 349 # had __set_name__ called on it at the right time. 350 def __set_name__(self, owner, name): 351 func = getattr(type(self.default), '__set_name__', None) 352 if func: 353 # There is a __set_name__ method on the descriptor, call 354 # it. 355 func(self.default, owner, name) 356 357 __class_getitem__ = classmethod(GenericAlias)
310 def __init__(self, default, default_factory, init, repr, hash, compare, 311 metadata, kw_only): 312 self.name = None 313 self.type = None 314 self.default = default 315 self.default_factory = default_factory 316 self.init = init 317 self.repr = repr 318 self.hash = hash 319 self.compare = compare 320 self.metadata = (_EMPTY_METADATA 321 if metadata is None else 322 types.MappingProxyType(metadata)) 323 self.kw_only = kw_only 324 self._field_type = None
173class FrozenInstanceError(AttributeError): pass
Attribute not found.
Inherited Members
- builtins.AttributeError
- AttributeError
- name
- obj
- builtins.BaseException
- with_traceback
- add_note
- args
269class InitVar: 270 __slots__ = ('type', ) 271 272 def __init__(self, type): 273 self.type = type 274 275 def __repr__(self): 276 if isinstance(self.type, type): 277 type_name = self.type.__name__ 278 else: 279 # typing objects, e.g. List[int] 280 type_name = repr(self.type) 281 return f'dataclasses.InitVar[{type_name}]' 282 283 def __class_getitem__(cls, type): 284 return InitVar(type)
1270def fields(class_or_instance): 1271 """Return a tuple describing the fields of this dataclass. 1272 1273 Accepts a dataclass or an instance of one. Tuple elements are of 1274 type Field. 1275 """ 1276 1277 # Might it be worth caching this, per class? 1278 try: 1279 fields = getattr(class_or_instance, _FIELDS) 1280 except AttributeError: 1281 raise TypeError('must be called with a dataclass type or instance') from None 1282 1283 # Exclude pseudo-fields. Note that fields is sorted by insertion 1284 # order, so the order of the tuple is as the fields were defined. 1285 return tuple(f for f in fields.values() if f._field_type is _FIELD)
Return a tuple describing the fields of this dataclass.
Accepts a dataclass or an instance of one. Tuple elements are of type Field.
1300def asdict(obj, *, dict_factory=dict): 1301 """Return the fields of a dataclass instance as a new dictionary mapping 1302 field names to field values. 1303 1304 Example usage:: 1305 1306 @dataclass 1307 class C: 1308 x: int 1309 y: int 1310 1311 c = C(1, 2) 1312 assert asdict(c) == {'x': 1, 'y': 2} 1313 1314 If given, 'dict_factory' will be used instead of built-in dict. 1315 The function applies recursively to field values that are 1316 dataclass instances. This will also look into built-in containers: 1317 tuples, lists, and dicts. Other objects are copied with 'copy.deepcopy()'. 1318 """ 1319 if not _is_dataclass_instance(obj): 1320 raise TypeError("asdict() should be called on dataclass instances") 1321 return _asdict_inner(obj, dict_factory)
Return the fields of a dataclass instance as a new dictionary mapping field names to field values.
Example usage::
@dataclass class C: x: int y: int
c = C(1, 2) assert asdict(c) == {'x': 1, 'y': 2}
If given, 'dict_factory' will be used instead of built-in dict. The function applies recursively to field values that are dataclass instances. This will also look into built-in containers: tuples, lists, and dicts. Other objects are copied with 'copy.deepcopy()'.
1381def astuple(obj, *, tuple_factory=tuple): 1382 """Return the fields of a dataclass instance as a new tuple of field values. 1383 1384 Example usage:: 1385 1386 @dataclass 1387 class C: 1388 x: int 1389 y: int 1390 1391 c = C(1, 2) 1392 assert astuple(c) == (1, 2) 1393 1394 If given, 'tuple_factory' will be used instead of built-in tuple. 1395 The function applies recursively to field values that are 1396 dataclass instances. This will also look into built-in containers: 1397 tuples, lists, and dicts. Other objects are copied with 'copy.deepcopy()'. 1398 """ 1399 1400 if not _is_dataclass_instance(obj): 1401 raise TypeError("astuple() should be called on dataclass instances") 1402 return _astuple_inner(obj, tuple_factory)
Return the fields of a dataclass instance as a new tuple of field values.
Example usage::
@dataclass class C: x: int y: int
c = C(1, 2) assert astuple(c) == (1, 2)
If given, 'tuple_factory' will be used instead of built-in tuple. The function applies recursively to field values that are dataclass instances. This will also look into built-in containers: tuples, lists, and dicts. Other objects are copied with 'copy.deepcopy()'.
1442def make_dataclass(cls_name, fields, *, bases=(), namespace=None, init=True, 1443 repr=True, eq=True, order=False, unsafe_hash=False, 1444 frozen=False, match_args=True, kw_only=False, slots=False, 1445 weakref_slot=False, module=None): 1446 """Return a new dynamically created dataclass. 1447 1448 The dataclass name will be 'cls_name'. 'fields' is an iterable 1449 of either (name), (name, type) or (name, type, Field) objects. If type is 1450 omitted, use the string 'typing.Any'. Field objects are created by 1451 the equivalent of calling 'field(name, type [, Field-info])'.:: 1452 1453 C = make_dataclass('C', ['x', ('y', int), ('z', int, field(init=False))], bases=(Base,)) 1454 1455 is equivalent to:: 1456 1457 @dataclass 1458 class C(Base): 1459 x: 'typing.Any' 1460 y: int 1461 z: int = field(init=False) 1462 1463 For the bases and namespace parameters, see the builtin type() function. 1464 1465 The parameters init, repr, eq, order, unsafe_hash, frozen, match_args, kw_only, 1466 slots, and weakref_slot are passed to dataclass(). 1467 1468 If module parameter is defined, the '__module__' attribute of the dataclass is 1469 set to that value. 1470 """ 1471 1472 if namespace is None: 1473 namespace = {} 1474 1475 # While we're looking through the field names, validate that they 1476 # are identifiers, are not keywords, and not duplicates. 1477 seen = set() 1478 annotations = {} 1479 defaults = {} 1480 for item in fields: 1481 if isinstance(item, str): 1482 name = item 1483 tp = 'typing.Any' 1484 elif len(item) == 2: 1485 name, tp, = item 1486 elif len(item) == 3: 1487 name, tp, spec = item 1488 defaults[name] = spec 1489 else: 1490 raise TypeError(f'Invalid field: {item!r}') 1491 1492 if not isinstance(name, str) or not name.isidentifier(): 1493 raise TypeError(f'Field names must be valid identifiers: {name!r}') 1494 if keyword.iskeyword(name): 1495 raise TypeError(f'Field names must not be keywords: {name!r}') 1496 if name in seen: 1497 raise TypeError(f'Field name duplicated: {name!r}') 1498 1499 seen.add(name) 1500 annotations[name] = tp 1501 1502 # Update 'ns' with the user-supplied namespace plus our calculated values. 1503 def exec_body_callback(ns): 1504 ns.update(namespace) 1505 ns.update(defaults) 1506 ns['__annotations__'] = annotations 1507 1508 # We use `types.new_class()` instead of simply `type()` to allow dynamic creation 1509 # of generic dataclasses. 1510 cls = types.new_class(cls_name, bases, {}, exec_body_callback) 1511 1512 # For pickling to work, the __module__ variable needs to be set to the frame 1513 # where the dataclass is created. 1514 if module is None: 1515 try: 1516 module = sys._getframemodulename(1) or '__main__' 1517 except AttributeError: 1518 try: 1519 module = sys._getframe(1).f_globals.get('__name__', '__main__') 1520 except (AttributeError, ValueError): 1521 pass 1522 if module is not None: 1523 cls.__module__ = module 1524 1525 # Apply the normal decorator. 1526 return dataclass(cls, init=init, repr=repr, eq=eq, order=order, 1527 unsafe_hash=unsafe_hash, frozen=frozen, 1528 match_args=match_args, kw_only=kw_only, slots=slots, 1529 weakref_slot=weakref_slot)
Return a new dynamically created dataclass.
The dataclass name will be 'cls_name'. 'fields' is an iterable of either (name), (name, type) or (name, type, Field) objects. If type is omitted, use the string 'typing.Any'. Field objects are created by the equivalent of calling 'field(name, type [, Field-info])'.::
C = make_dataclass('C', ['x', ('y', int), ('z', int, field(init=False))], bases=(Base,))
is equivalent to::
@dataclass class C(Base): x: 'typing.Any' y: int z: int = field(init=False)
For the bases and namespace parameters, see the builtin type() function.
The parameters init, repr, eq, order, unsafe_hash, frozen, match_args, kw_only, slots, and weakref_slot are passed to dataclass().
If module parameter is defined, the '__module__' attribute of the dataclass is set to that value.
1532def replace(obj, /, **changes): 1533 """Return a new object replacing specified fields with new values. 1534 1535 This is especially useful for frozen classes. Example usage:: 1536 1537 @dataclass(frozen=True) 1538 class C: 1539 x: int 1540 y: int 1541 1542 c = C(1, 2) 1543 c1 = replace(c, x=3) 1544 assert c1.x == 3 and c1.y == 2 1545 """ 1546 1547 # We're going to mutate 'changes', but that's okay because it's a 1548 # new dict, even if called with 'replace(obj, **my_changes)'. 1549 1550 if not _is_dataclass_instance(obj): 1551 raise TypeError("replace() should be called on dataclass instances") 1552 1553 # It's an error to have init=False fields in 'changes'. 1554 # If a field is not in 'changes', read its value from the provided obj. 1555 1556 for f in getattr(obj, _FIELDS).values(): 1557 # Only consider normal fields or InitVars. 1558 if f._field_type is _FIELD_CLASSVAR: 1559 continue 1560 1561 if not f.init: 1562 # Error if this field is specified in changes. 1563 if f.name in changes: 1564 raise ValueError(f'field {f.name} is declared with ' 1565 'init=False, it cannot be specified with ' 1566 'replace()') 1567 continue 1568 1569 if f.name not in changes: 1570 if f._field_type is _FIELD_INITVAR and f.default is MISSING: 1571 raise ValueError(f"InitVar {f.name!r} " 1572 'must be specified with replace()') 1573 changes[f.name] = getattr(obj, f.name) 1574 1575 # Create the new object, which calls __init__() and 1576 # __post_init__() (if defined), using all of the init fields we've 1577 # added and/or left in 'changes'. If there are values supplied in 1578 # changes that aren't fields, this will correctly raise a 1579 # TypeError. 1580 return obj.__class__(**changes)
Return a new object replacing specified fields with new values.
This is especially useful for frozen classes. Example usage::
@dataclass(frozen=True) class C: x: int y: int
c = C(1, 2) c1 = replace(c, x=3) assert c1.x == 3 and c1.y == 2
1293def is_dataclass(obj): 1294 """Returns True if obj is a dataclass or an instance of a 1295 dataclass.""" 1296 cls = obj if isinstance(obj, type) else type(obj) 1297 return hasattr(cls, _FIELDS)
Returns True if obj is a dataclass or an instance of a dataclass.