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