dataclasses

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