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        # `__dictoffset__` and `__weakrefoffset__` can tell us whether
1172        # the base type has dict/weakref slots, in a way that works correctly
1173        # for both Python classes and C extension types. Extension types
1174        # don't use `__slots__` for slot creation
1175        case None:
1176            slots = []
1177            if getattr(cls, '__weakrefoffset__', -1) != 0:
1178                slots.append('__weakref__')
1179            if getattr(cls, '__dictoffset__', -1) != 0:
1180                slots.append('__dict__')
1181            yield from slots
1182        case str(slot):
1183            yield slot
1184        # Slots may be any iterable, but we cannot handle an iterator
1185        # because it will already be (partially) consumed.
1186        case iterable if not hasattr(iterable, '__next__'):
1187            yield from iterable
1188        case _:
1189            raise TypeError(f"Slots of '{cls.__name__}' cannot be determined")
1190
1191
1192def _add_slots(cls, is_frozen, weakref_slot):
1193    # Need to create a new class, since we can't set __slots__
1194    #  after a class has been created.
1195
1196    # Make sure __slots__ isn't already set.
1197    if '__slots__' in cls.__dict__:
1198        raise TypeError(f'{cls.__name__} already specifies __slots__')
1199
1200    # Create a new dict for our new class.
1201    cls_dict = dict(cls.__dict__)
1202    field_names = tuple(f.name for f in fields(cls))
1203    # Make sure slots don't overlap with those in base classes.
1204    inherited_slots = set(
1205        itertools.chain.from_iterable(map(_get_slots, cls.__mro__[1:-1]))
1206    )
1207    # The slots for our class.  Remove slots from our base classes.  Add
1208    # '__weakref__' if weakref_slot was given, unless it is already present.
1209    cls_dict["__slots__"] = tuple(
1210        itertools.filterfalse(
1211            inherited_slots.__contains__,
1212            itertools.chain(
1213                # gh-93521: '__weakref__' also needs to be filtered out if
1214                # already present in inherited_slots
1215                field_names, ('__weakref__',) if weakref_slot else ()
1216            )
1217        ),
1218    )
1219
1220    for field_name in field_names:
1221        # Remove our attributes, if present. They'll still be
1222        #  available in _MARKER.
1223        cls_dict.pop(field_name, None)
1224
1225    # Remove __dict__ itself.
1226    cls_dict.pop('__dict__', None)
1227
1228    # Clear existing `__weakref__` descriptor, it belongs to a previous type:
1229    cls_dict.pop('__weakref__', None)  # gh-102069
1230
1231    # And finally create the class.
1232    qualname = getattr(cls, '__qualname__', None)
1233    cls = type(cls)(cls.__name__, cls.__bases__, cls_dict)
1234    if qualname is not None:
1235        cls.__qualname__ = qualname
1236
1237    if is_frozen:
1238        # Need this for pickling frozen classes with slots.
1239        if '__getstate__' not in cls_dict:
1240            cls.__getstate__ = _dataclass_getstate
1241        if '__setstate__' not in cls_dict:
1242            cls.__setstate__ = _dataclass_setstate
1243
1244    return cls
1245
1246
1247def dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False,
1248              unsafe_hash=False, frozen=False, match_args=True,
1249              kw_only=False, slots=False, weakref_slot=False):
1250    """Add dunder methods based on the fields defined in the class.
1251
1252    Examines PEP 526 __annotations__ to determine fields.
1253
1254    If init is true, an __init__() method is added to the class. If repr
1255    is true, a __repr__() method is added. If order is true, rich
1256    comparison dunder methods are added. If unsafe_hash is true, a
1257    __hash__() method is added. If frozen is true, fields may not be
1258    assigned to after instance creation. If match_args is true, the
1259    __match_args__ tuple is added. If kw_only is true, then by default
1260    all fields are keyword-only. If slots is true, a new class with a
1261    __slots__ attribute is returned.
1262    """
1263
1264    def wrap(cls):
1265        return _process_class(cls, init, repr, eq, order, unsafe_hash,
1266                              frozen, match_args, kw_only, slots,
1267                              weakref_slot)
1268
1269    # See if we're being called as @dataclass or @dataclass().
1270    if cls is None:
1271        # We're called with parens.
1272        return wrap
1273
1274    # We're called as @dataclass without parens.
1275    return wrap(cls)
1276
1277
1278def fields(class_or_instance):
1279    """Return a tuple describing the fields of this dataclass.
1280
1281    Accepts a dataclass or an instance of one. Tuple elements are of
1282    type Field.
1283    """
1284
1285    # Might it be worth caching this, per class?
1286    try:
1287        fields = getattr(class_or_instance, _FIELDS)
1288    except AttributeError:
1289        raise TypeError('must be called with a dataclass type or instance') from None
1290
1291    # Exclude pseudo-fields.  Note that fields is sorted by insertion
1292    # order, so the order of the tuple is as the fields were defined.
1293    return tuple(f for f in fields.values() if f._field_type is _FIELD)
1294
1295
1296def _is_dataclass_instance(obj):
1297    """Returns True if obj is an instance of a dataclass."""
1298    return hasattr(type(obj), _FIELDS)
1299
1300
1301def is_dataclass(obj):
1302    """Returns True if obj is a dataclass or an instance of a
1303    dataclass."""
1304    cls = obj if isinstance(obj, type) else type(obj)
1305    return hasattr(cls, _FIELDS)
1306
1307
1308def asdict(obj, *, dict_factory=dict):
1309    """Return the fields of a dataclass instance as a new dictionary mapping
1310    field names to field values.
1311
1312    Example usage::
1313
1314      @dataclass
1315      class C:
1316          x: int
1317          y: int
1318
1319      c = C(1, 2)
1320      assert asdict(c) == {'x': 1, 'y': 2}
1321
1322    If given, 'dict_factory' will be used instead of built-in dict.
1323    The function applies recursively to field values that are
1324    dataclass instances. This will also look into built-in containers:
1325    tuples, lists, and dicts. Other objects are copied with 'copy.deepcopy()'.
1326    """
1327    if not _is_dataclass_instance(obj):
1328        raise TypeError("asdict() should be called on dataclass instances")
1329    return _asdict_inner(obj, dict_factory)
1330
1331
1332def _asdict_inner(obj, dict_factory):
1333    if type(obj) in _ATOMIC_TYPES:
1334        return obj
1335    elif _is_dataclass_instance(obj):
1336        # fast path for the common case
1337        if dict_factory is dict:
1338            return {
1339                f.name: _asdict_inner(getattr(obj, f.name), dict)
1340                for f in fields(obj)
1341            }
1342        else:
1343            result = []
1344            for f in fields(obj):
1345                value = _asdict_inner(getattr(obj, f.name), dict_factory)
1346                result.append((f.name, value))
1347            return dict_factory(result)
1348    elif isinstance(obj, tuple) and hasattr(obj, '_fields'):
1349        # obj is a namedtuple.  Recurse into it, but the returned
1350        # object is another namedtuple of the same type.  This is
1351        # similar to how other list- or tuple-derived classes are
1352        # treated (see below), but we just need to create them
1353        # differently because a namedtuple's __init__ needs to be
1354        # called differently (see bpo-34363).
1355
1356        # I'm not using namedtuple's _asdict()
1357        # method, because:
1358        # - it does not recurse in to the namedtuple fields and
1359        #   convert them to dicts (using dict_factory).
1360        # - I don't actually want to return a dict here.  The main
1361        #   use case here is json.dumps, and it handles converting
1362        #   namedtuples to lists.  Admittedly we're losing some
1363        #   information here when we produce a json list instead of a
1364        #   dict.  Note that if we returned dicts here instead of
1365        #   namedtuples, we could no longer call asdict() on a data
1366        #   structure where a namedtuple was used as a dict key.
1367
1368        return type(obj)(*[_asdict_inner(v, dict_factory) for v in obj])
1369    elif isinstance(obj, (list, tuple)):
1370        # Assume we can create an object of this type by passing in a
1371        # generator (which is not true for namedtuples, handled
1372        # above).
1373        return type(obj)(_asdict_inner(v, dict_factory) for v in obj)
1374    elif isinstance(obj, dict):
1375        if hasattr(type(obj), 'default_factory'):
1376            # obj is a defaultdict, which has a different constructor from
1377            # dict as it requires the default_factory as its first arg.
1378            result = type(obj)(getattr(obj, 'default_factory'))
1379            for k, v in obj.items():
1380                result[_asdict_inner(k, dict_factory)] = _asdict_inner(v, dict_factory)
1381            return result
1382        return type(obj)((_asdict_inner(k, dict_factory),
1383                          _asdict_inner(v, dict_factory))
1384                         for k, v in obj.items())
1385    else:
1386        return copy.deepcopy(obj)
1387
1388
1389def astuple(obj, *, tuple_factory=tuple):
1390    """Return the fields of a dataclass instance as a new tuple of field values.
1391
1392    Example usage::
1393
1394      @dataclass
1395      class C:
1396          x: int
1397          y: int
1398
1399      c = C(1, 2)
1400      assert astuple(c) == (1, 2)
1401
1402    If given, 'tuple_factory' will be used instead of built-in tuple.
1403    The function applies recursively to field values that are
1404    dataclass instances. This will also look into built-in containers:
1405    tuples, lists, and dicts. Other objects are copied with 'copy.deepcopy()'.
1406    """
1407
1408    if not _is_dataclass_instance(obj):
1409        raise TypeError("astuple() should be called on dataclass instances")
1410    return _astuple_inner(obj, tuple_factory)
1411
1412
1413def _astuple_inner(obj, tuple_factory):
1414    if type(obj) in _ATOMIC_TYPES:
1415        return obj
1416    elif _is_dataclass_instance(obj):
1417        result = []
1418        for f in fields(obj):
1419            value = _astuple_inner(getattr(obj, f.name), tuple_factory)
1420            result.append(value)
1421        return tuple_factory(result)
1422    elif isinstance(obj, tuple) and hasattr(obj, '_fields'):
1423        # obj is a namedtuple.  Recurse into it, but the returned
1424        # object is another namedtuple of the same type.  This is
1425        # similar to how other list- or tuple-derived classes are
1426        # treated (see below), but we just need to create them
1427        # differently because a namedtuple's __init__ needs to be
1428        # called differently (see bpo-34363).
1429        return type(obj)(*[_astuple_inner(v, tuple_factory) for v in obj])
1430    elif isinstance(obj, (list, tuple)):
1431        # Assume we can create an object of this type by passing in a
1432        # generator (which is not true for namedtuples, handled
1433        # above).
1434        return type(obj)(_astuple_inner(v, tuple_factory) for v in obj)
1435    elif isinstance(obj, dict):
1436        obj_type = type(obj)
1437        if hasattr(obj_type, 'default_factory'):
1438            # obj is a defaultdict, which has a different constructor from
1439            # dict as it requires the default_factory as its first arg.
1440            result = obj_type(getattr(obj, 'default_factory'))
1441            for k, v in obj.items():
1442                result[_astuple_inner(k, tuple_factory)] = _astuple_inner(v, tuple_factory)
1443            return result
1444        return obj_type((_astuple_inner(k, tuple_factory), _astuple_inner(v, tuple_factory))
1445                          for k, v in obj.items())
1446    else:
1447        return copy.deepcopy(obj)
1448
1449
1450def make_dataclass(cls_name, fields, *, bases=(), namespace=None, init=True,
1451                   repr=True, eq=True, order=False, unsafe_hash=False,
1452                   frozen=False, match_args=True, kw_only=False, slots=False,
1453                   weakref_slot=False, module=None):
1454    """Return a new dynamically created dataclass.
1455
1456    The dataclass name will be 'cls_name'.  'fields' is an iterable
1457    of either (name), (name, type) or (name, type, Field) objects. If type is
1458    omitted, use the string 'typing.Any'.  Field objects are created by
1459    the equivalent of calling 'field(name, type [, Field-info])'.::
1460
1461      C = make_dataclass('C', ['x', ('y', int), ('z', int, field(init=False))], bases=(Base,))
1462
1463    is equivalent to::
1464
1465      @dataclass
1466      class C(Base):
1467          x: 'typing.Any'
1468          y: int
1469          z: int = field(init=False)
1470
1471    For the bases and namespace parameters, see the builtin type() function.
1472
1473    The parameters init, repr, eq, order, unsafe_hash, frozen, match_args, kw_only,
1474    slots, and weakref_slot are passed to dataclass().
1475
1476    If module parameter is defined, the '__module__' attribute of the dataclass is
1477    set to that value.
1478    """
1479
1480    if namespace is None:
1481        namespace = {}
1482
1483    # While we're looking through the field names, validate that they
1484    # are identifiers, are not keywords, and not duplicates.
1485    seen = set()
1486    annotations = {}
1487    defaults = {}
1488    for item in fields:
1489        if isinstance(item, str):
1490            name = item
1491            tp = 'typing.Any'
1492        elif len(item) == 2:
1493            name, tp, = item
1494        elif len(item) == 3:
1495            name, tp, spec = item
1496            defaults[name] = spec
1497        else:
1498            raise TypeError(f'Invalid field: {item!r}')
1499
1500        if not isinstance(name, str) or not name.isidentifier():
1501            raise TypeError(f'Field names must be valid identifiers: {name!r}')
1502        if keyword.iskeyword(name):
1503            raise TypeError(f'Field names must not be keywords: {name!r}')
1504        if name in seen:
1505            raise TypeError(f'Field name duplicated: {name!r}')
1506
1507        seen.add(name)
1508        annotations[name] = tp
1509
1510    # Update 'ns' with the user-supplied namespace plus our calculated values.
1511    def exec_body_callback(ns):
1512        ns.update(namespace)
1513        ns.update(defaults)
1514        ns['__annotations__'] = annotations
1515
1516    # We use `types.new_class()` instead of simply `type()` to allow dynamic creation
1517    # of generic dataclasses.
1518    cls = types.new_class(cls_name, bases, {}, exec_body_callback)
1519
1520    # For pickling to work, the __module__ variable needs to be set to the frame
1521    # where the dataclass is created.
1522    if module is None:
1523        try:
1524            module = sys._getframemodulename(1) or '__main__'
1525        except AttributeError:
1526            try:
1527                module = sys._getframe(1).f_globals.get('__name__', '__main__')
1528            except (AttributeError, ValueError):
1529                pass
1530    if module is not None:
1531        cls.__module__ = module
1532
1533    # Apply the normal decorator.
1534    return dataclass(cls, init=init, repr=repr, eq=eq, order=order,
1535                     unsafe_hash=unsafe_hash, frozen=frozen,
1536                     match_args=match_args, kw_only=kw_only, slots=slots,
1537                     weakref_slot=weakref_slot)
1538
1539
1540def replace(obj, /, **changes):
1541    """Return a new object replacing specified fields with new values.
1542
1543    This is especially useful for frozen classes.  Example usage::
1544
1545      @dataclass(frozen=True)
1546      class C:
1547          x: int
1548          y: int
1549
1550      c = C(1, 2)
1551      c1 = replace(c, x=3)
1552      assert c1.x == 3 and c1.y == 2
1553    """
1554
1555    # We're going to mutate 'changes', but that's okay because it's a
1556    # new dict, even if called with 'replace(obj, **my_changes)'.
1557
1558    if not _is_dataclass_instance(obj):
1559        raise TypeError("replace() should be called on dataclass instances")
1560
1561    # It's an error to have init=False fields in 'changes'.
1562    # If a field is not in 'changes', read its value from the provided obj.
1563
1564    for f in getattr(obj, _FIELDS).values():
1565        # Only consider normal fields or InitVars.
1566        if f._field_type is _FIELD_CLASSVAR:
1567            continue
1568
1569        if not f.init:
1570            # Error if this field is specified in changes.
1571            if f.name in changes:
1572                raise ValueError(f'field {f.name} is declared with '
1573                                 'init=False, it cannot be specified with '
1574                                 'replace()')
1575            continue
1576
1577        if f.name not in changes:
1578            if f._field_type is _FIELD_INITVAR and f.default is MISSING:
1579                raise ValueError(f"InitVar {f.name!r} "
1580                                 'must be specified with replace()')
1581            changes[f.name] = getattr(obj, f.name)
1582
1583    # Create the new object, which calls __init__() and
1584    # __post_init__() (if defined), using all of the init fields we've
1585    # added and/or left in 'changes'.  If there are values supplied in
1586    # changes that aren't fields, this will correctly raise a
1587    # TypeError.
1588    return obj.__class__(**changes)