dataclasses

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