'field',

'Field',

'FrozenInstanceError',

'InitVar',

'MISSING',

# Helper functions.

'fields',

'asdict',

'astuple',

'make_dataclass',

'replace',

'is_dataclass',

__slots__ = ('name',

'type',

'default',

'default_factory',

'repr',

'hash',

'init',

'compare',

'metadata',

'_field_type', # Private: not to be used by user code.

)

def __init__(self, default, default_factory, init, repr, hash, compare,

metadata):

self.name = None

self.type = None

self.default = default

self.default_factory = default_factory

self.init = init

self.repr = repr

self.hash = hash

self.compare = compare

self.metadata = (_EMPTY_METADATA

if metadata is None or len(metadata) == 0 else

types.MappingProxyType(metadata))

self._field_type = None

def __repr__(self):

return ('Field('

f'name={self.name!r},'

f'type={self.type},'

f'default={self.default},'

f'default_factory={self.default_factory},'

f'init={self.init},'

f'repr={self.repr},'

f'hash={self.hash},'

f'compare={self.compare},'

f'metadata={self.metadata}'

__slots__ = ('init',

'repr',

'eq',

'order',

'unsafe_hash',

'frozen',

)

def __init__(self, init, repr, eq, order, unsafe_hash, frozen):

self.init = init

self.repr = repr

self.eq = eq

self.order = order

self.unsafe_hash = unsafe_hash

self.frozen = frozen

def __repr__(self):

return ('_DataclassParams('

f'init={self.init},'

f'repr={self.repr},'

f'eq={self.eq},'

f'order={self.order},'

f'unsafe_hash={self.unsafe_hash},'

f'frozen={self.frozen}'

hash=None, compare=True, metadata=None):

"""Return an object to identify dataclass fields.

if default is not MISSING and default_factory is not MISSING:

raise ValueError('cannot specify both default and default_factory')

return Field(default, default_factory, init, repr, hash, compare,

# Return a string representing each field of obj_name as a tuple

# member. So, if fields is ['x', 'y'] and obj_name is "self",

# return "(self.x,self.y)".

# Special case for the 0-tuple.

if not fields:

return '()'

# Note the trailing comma, needed if this turns out to be a 1-tuple.

return_type=MISSING):

# Note that we mutate locals when exec() is called. Caller beware!

if locals is None:

locals = {}

return_annotation = ''

if return_type is not MISSING:

locals['_return_type'] = return_type

return_annotation = '->_return_type'

args = ','.join(args)

body = '\n'.join(f' {b}' for b in body)

# Compute the text of the entire function.

txt = f'def {name}({args}){return_annotation}:\n{body}'

exec(txt, globals, locals)

# If we're a frozen class, then assign to our fields in __init__

# via object.__setattr__. Otherwise, just use a simple

# assignment.

# self_name is what "self" is called in this function: don't

# hard-code "self", since that might be a field name.

if frozen:

return f'object.__setattr__({self_name},{name!r},{value})'

# Return the text of the line in the body of __init__ that will

# initialize this field.

default_name = f'_dflt_{f.name}'

if f.default_factory is not MISSING:

if f.init:

# This field has a default factory. If a parameter is

# given, use it. If not, call the factory.

globals[default_name] = f.default_factory

value = (f'{default_name}() '

f'if {f.name} is _HAS_DEFAULT_FACTORY '

f'else {f.name}')

else:

# This is a field that's not in the __init__ params, but

# has a default factory function. It needs to be

# initialized here by calling the factory function,

# because there's no other way to initialize it.

# For a field initialized with a default=defaultvalue, the

# class dict just has the default value

# (cls.fieldname=defaultvalue). But that won't work for a

# default factory, the factory must be called in __init__

# and we must assign that to self.fieldname. We can't

# fall back to the class dict's value, both because it's

# not set, and because it might be different per-class

# (which, after all, is why we have a factory function!).

globals[default_name] = f.default_factory

value = f'{default_name}()'

else:

# No default factory.

if f.init:

if f.default is MISSING:

# There's no default, just do an assignment.

value = f.name

elif f.default is not MISSING:

globals[default_name] = f.default

value = f.name

else:

# This field does not need initialization. Signify that to

# the caller by returning None.

return None

# Only test this now, so that we can create variables for the

# default. However, return None to signify that we're not going

# to actually do the assignment statement for InitVars.

if f._field_type == _FIELD_INITVAR:

return None

# Now, actually generate the field assignment.

# Return the __init__ parameter string for this field.

# For example, the equivalent of 'x:int=3' (except instead of 'int',

# reference a variable set to int, and instead of '3', reference a

# variable set to 3).

if f.default is MISSING and f.default_factory is MISSING:

# There's no default, and no default_factory, just

# output the variable name and type.

default = ''

elif f.default is not MISSING:

# There's a default, this will be the name that's used to look it up.

default = f'=_dflt_{f.name}'

elif f.default_factory is not MISSING:

# There's a factory function. Set a marker.

default = '=_HAS_DEFAULT_FACTORY'

# fields contains both real fields and InitVar pseudo-fields.

# Make sure we don't have fields without defaults following fields

# with defaults. This actually would be caught when exec-ing the

# function source code, but catching it here gives a better error

# message, and future-proofs us in case we build up the function

# using ast.

seen_default = False

for f in fields:

# Only consider fields in the __init__ call.

if f.init:

if not (f.default is MISSING and f.default_factory is MISSING):

seen_default = True

elif seen_default:

raise TypeError(f'non-default argument {f.name!r} '

'follows default argument')

globals = {'MISSING': MISSING,

'_HAS_DEFAULT_FACTORY': _HAS_DEFAULT_FACTORY}

body_lines = []

for f in fields:

# Do not initialize the pseudo-fields, only the real ones.

line = _field_init(f, frozen, globals, self_name)

if line is not None:

# line is None means that this field doesn't require

# initialization. Just skip it.

body_lines.append(line)

# Does this class have a post-init function?

if has_post_init:

params_str = ','.join(f.name for f in fields

if f._field_type is _FIELD_INITVAR)

body_lines += [f'{self_name}.{_POST_INIT_NAME}({params_str})']

# If no body lines, use 'pass'.

if not body_lines:

body_lines = ['pass']

locals = {f'_type_{f.name}': f.type for f in fields}

return _create_fn('__init__',

[self_name] +[_init_param(f) for f in fields if f.init],

body_lines,

locals=locals,

globals=globals,

return _create_fn('__repr__',

['self'],

['return self.__class__.__qualname__ + f"(' +

', '.join([f"{f.name}={{self.{f.name}!r}}"

for f in fields]) +

# XXX: globals is modified on the first call to _create_fn, then the

# modified version is used in the second call. Is this okay?

globals = {'cls': cls,

'FrozenInstanceError': FrozenInstanceError}

if fields:

fields_str = '(' + ','.join(repr(f.name) for f in fields) + ',)'

else:

# Special case for the zero-length tuple.

fields_str = '()'

return (_create_fn('__setattr__',

('self', 'name', 'value'),

(f'if type(self) is cls or name in {fields_str}:',

' raise FrozenInstanceError(f"cannot assign to field {name!r}")',

f'super(cls, self).__setattr__(name, value)'),

globals=globals),

_create_fn('__delattr__',

('self', 'name'),

(f'if type(self) is cls or name in {fields_str}:',

' raise FrozenInstanceError(f"cannot delete field {name!r}")',

f'super(cls, self).__delattr__(name)'),

globals=globals),

# Create a comparison function. If the fields in the object are

# named 'x' and 'y', then self_tuple is the string

# '(self.x,self.y)' and other_tuple is the string

# '(other.x,other.y)'.

return _create_fn(name,

['self', 'other'],

[ 'if other.__class__ is self.__class__:',

f' return {self_tuple}{op}{other_tuple}',

self_tuple = _tuple_str('self', fields)

return _create_fn('__hash__',

['self'],

# Return a Field object, for this field name and type. ClassVars

# and InitVars are also returned, but marked as such (see

# f._field_type).

# If the default value isn't derived from Field, then it's

# only a normal default value. Convert it to a Field().

default = getattr(cls, a_name, MISSING)

if isinstance(default, Field):

f = default

else:

if isinstance(default, types.MemberDescriptorType):

# This is a field in __slots__, so it has no default value.

default = MISSING

f = field(default=default)

# Assume it's a normal field until proven otherwise.

f._field_type = _FIELD

# Only at this point do we know the name and the type. Set them.

f.name = a_name

f.type = a_type

# If typing has not been imported, then it's impossible for

# any annotation to be a ClassVar. So, only look for ClassVar

# if typing has been imported.

typing = sys.modules.get('typing')

if typing is not None:

# This test uses a typing internal class, but it's the best

# way to test if this is a ClassVar.

if (type(a_type) is typing._GenericAlias and

a_type.__origin__ is typing.ClassVar):

# This field is a ClassVar, so it's not a field.

f._field_type = _FIELD_CLASSVAR

if f._field_type is _FIELD:

# Check if this is an InitVar.

if a_type is InitVar:

# InitVars are not fields, either.

f._field_type = _FIELD_INITVAR

# Validations for fields. This is delayed until now, instead of

# in the Field() constructor, since only here do we know the field

# name, which allows better error reporting.

# Special restrictions for ClassVar and InitVar.

if f._field_type in (_FIELD_CLASSVAR, _FIELD_INITVAR):

if f.default_factory is not MISSING:

raise TypeError(f'field {f.name} cannot have a '

'default factory')

# Should I check for other field settings? default_factory

# seems the most serious to check for. Maybe add others. For

# example, how about init=False (or really,

# init=<not-the-default-init-value>)? It makes no sense for

# ClassVar and InitVar to specify init=<anything>.

# For real fields, disallow mutable defaults for known types.

if f._field_type is _FIELD and isinstance(f.default, (list, dict, set)):

raise ValueError(f'mutable default {type(f.default)} for field '

f'{f.name} is not allowed: use default_factory')

# Return a list of Field objects, in order, for this class (and no

# base classes). Fields are found from the class dict's

# __annotations__ (which is guaranteed to be ordered). Default

# values are from class attributes, if a field has a default. If

# the default value is a Field(), then it contains additional

# info beyond (and possibly including) the actual default value.

# Pseudo-fields ClassVars and InitVars are included, despite the

# fact that they're not real fields. That's dealt with later.

# If __annotations__ isn't present, then this class adds no new

# annotations.

annotations = cls.__dict__.get('__annotations__', {})

# Never overwrites an existing attribute. Returns True if the

# attribute already exists.

if name in cls.__dict__:

return True

setattr(cls, name, value)

(False, False, False, True ): (''),

(False, False, True, False): (''),

(False, False, True, True ): (''),

(False, True, False, False): ('none'),

(False, True, False, True ): (''),

(False, True, True, False): ('add'),

(False, True, True, True ): (''),

(True, False, False, False): ('add'),

(True, False, False, True ): ('exception'),

(True, False, True, False): ('add'),

(True, False, True, True ): ('exception'),

(True, True, False, False): ('add'),

(True, True, False, True ): ('exception'),

(True, True, True, False): ('add'),

(True, True, True, True ): ('exception'),

# Now that dicts retain insertion order, there's no reason to use

# an ordered dict. I am leveraging that ordering here, because

# derived class fields overwrite base class fields, but the order

# is defined by the base class, which is found first.

fields = {}

setattr(cls, _PARAMS, _DataclassParams(init, repr, eq, order,

unsafe_hash, frozen))

# Find our base classes in reverse MRO order, and exclude

# ourselves. In reversed order so that more derived classes

# override earlier field definitions in base classes.

# As long as we're iterating over them, see if any are frozen.

any_frozen_base = False

has_dataclass_bases = False

for b in cls.__mro__[-1:0:-1]:

# Only process classes that have been processed by our

# decorator. That is, they have a _FIELDS attribute.

base_fields = getattr(b, _FIELDS, None)

if base_fields:

has_dataclass_bases = True

for f in base_fields.values():

fields[f.name] = f

if getattr(b, _PARAMS).frozen:

any_frozen_base = True

# Now find fields in our class. While doing so, validate some

# things, and set the default values (as class attributes)

# where we can.

for f in _find_fields(cls):

fields[f.name] = f

# If the class attribute (which is the default value for

# this field) exists and is of type 'Field', replace it

# with the real default. This is so that normal class

# introspection sees a real default value, not a Field.

if isinstance(getattr(cls, f.name, None), Field):

if f.default is MISSING:

# If there's no default, delete the class attribute.

# This happens if we specify field(repr=False), for

# example (that is, we specified a field object, but

# no default value). Also if we're using a default

# factory. The class attribute should not be set at

# all in the post-processed class.

delattr(cls, f.name)

else:

setattr(cls, f.name, f.default)

# Check rules that apply if we are derived from any dataclasses.

if has_dataclass_bases:

# Raise an exception if any of our bases are frozen, but we're not.

if any_frozen_base and not frozen:

raise TypeError('cannot inherit non-frozen dataclass from a '

'frozen one')

# Raise an exception if we're frozen, but none of our bases are.

if not any_frozen_base and frozen:

raise TypeError('cannot inherit frozen dataclass from a '

'non-frozen one')

# Remember all of the fields on our class (including bases). This also

# marks this class as being a dataclass.

setattr(cls, _FIELDS, fields)

# Was this class defined with an explicit __hash__? Note that if

# __eq__ is defined in this class, then python will automatically

# set __hash__ to None. This is a heuristic, as it's possible

# that such a __hash__ == None was not auto-generated, but it

# close enough.

class_hash = cls.__dict__.get('__hash__', MISSING)

has_explicit_hash = not (class_hash is MISSING or

(class_hash is None and '__eq__' in cls.__dict__))

# If we're generating ordering methods, we must be generating

# the eq methods.

if order and not eq:

raise ValueError('eq must be true if order is true')

if init:

# Does this class have a post-init function?

has_post_init = hasattr(cls, _POST_INIT_NAME)

# Include InitVars and regular fields (so, not ClassVars).

flds = [f for f in fields.values()

if f._field_type in (_FIELD, _FIELD_INITVAR)]

_set_new_attribute(cls, '__init__',

_init_fn(flds,

frozen,

has_post_init,

# The name to use for the "self" param

# in __init__. Use "self" if possible.

'__dataclass_self__' if 'self' in fields

else 'self',

))

# Get the fields as a list, and include only real fields. This is

# used in all of the following methods.

field_list = [f for f in fields.values() if f._field_type is _FIELD]

if repr:

flds = [f for f in field_list if f.repr]

_set_new_attribute(cls, '__repr__', _repr_fn(flds))

if eq:

# Create _eq__ method. There's no need for a __ne__ method,

# since python will call __eq__ and negate it.

flds = [f for f in field_list if f.compare]

self_tuple = _tuple_str('self', flds)

other_tuple = _tuple_str('other', flds)

_set_new_attribute(cls, '__eq__',

_cmp_fn('__eq__', '==',

self_tuple, other_tuple))

if order:

# Create and set the ordering methods.

flds = [f for f in field_list if f.compare]

self_tuple = _tuple_str('self', flds)

other_tuple = _tuple_str('other', flds)

for name, op in [('__lt__', '<'),

('__le__', '<='),

('__gt__', '>'),

('__ge__', '>='),

]:

if _set_new_attribute(cls, name,

_cmp_fn(name, op, self_tuple, other_tuple)):

raise TypeError(f'Cannot overwrite attribute {name} '

f'in class {cls.__name__}. Consider using '

'functools.total_ordering')

if frozen:

# XXX: Which fields are frozen? InitVar? ClassVar? hashed-only?

for fn in _frozen_get_del_attr(cls, field_list):

if _set_new_attribute(cls, fn.__name__, fn):

raise TypeError(f'Cannot overwrite attribute {fn.__name__} '

f'in class {cls.__name__}')

# Decide if/how we're going to create a hash function.

hash_action = _hash_action[bool(unsafe_hash),

bool(eq),

bool(frozen),

has_explicit_hash]

# No need to call _set_new_attribute here, since we already know if

# we're overwriting a __hash__ or not.

if hash_action == '':

# Do nothing.

pass

elif hash_action == 'none':

cls.__hash__ = None

elif hash_action == 'add':

flds = [f for f in field_list if (f.compare if f.hash is None else f.hash)]

cls.__hash__ = _hash_fn(flds)

elif hash_action == 'exception':

# Raise an exception.

raise TypeError(f'Cannot overwrite attribute __hash__ '

f'in class {cls.__name__}')

else:

assert False, f"can't get here: {hash_action}"

if not getattr(cls, '__doc__'):

# Create a class doc-string.

cls.__doc__ = (cls.__name__ +

str(inspect.signature(cls)).replace(' -> None', ''))

unsafe_hash=False, frozen=False):

"""Returns the same class as was passed in, with dunder methods

def wrap(cls):

return _process_class(cls, init, repr, eq, order, unsafe_hash, frozen)

# See if we're being called as @dataclass or @dataclass().

if _cls is None:

# We're called with parens.

return wrap

# We're called as @dataclass without parens.

"""Return a tuple describing the fields of this dataclass.

# Might it be worth caching this, per class?

try:

fields = getattr(class_or_instance, _FIELDS)

except AttributeError:

raise TypeError('must be called with a dataclass type or instance')

# Exclude pseudo-fields. Note that fields is sorted by insertion

# order, so the order of the tuple is as the fields were defined.

"""Return the fields of a dataclass instance as a new dictionary mapping

if not _is_dataclass_instance(obj):

raise TypeError("asdict() should be called on dataclass instances")

if _is_dataclass_instance(obj):

result = []

for f in fields(obj):

value = _asdict_inner(getattr(obj, f.name), dict_factory)

result.append((f.name, value))

return dict_factory(result)

elif isinstance(obj, (list, tuple)):

return type(obj)(_asdict_inner(v, dict_factory) for v in obj)

elif isinstance(obj, dict):

return type(obj)((_asdict_inner(k, dict_factory), _asdict_inner(v, dict_factory))

for k, v in obj.items())

else:

"""Return the fields of a dataclass instance as a new tuple of field values.

if not _is_dataclass_instance(obj):

raise TypeError("astuple() should be called on dataclass instances")

if _is_dataclass_instance(obj):

result = []

for f in fields(obj):

value = _astuple_inner(getattr(obj, f.name), tuple_factory)

result.append(value)

return tuple_factory(result)

elif isinstance(obj, (list, tuple)):

return type(obj)(_astuple_inner(v, tuple_factory) for v in obj)

elif isinstance(obj, dict):

return type(obj)((_astuple_inner(k, tuple_factory), _astuple_inner(v, tuple_factory))

for k, v in obj.items())

else:

repr=True, eq=True, order=False, unsafe_hash=False,

frozen=False):

"""Return a new dynamically created dataclass.

if namespace is None:

namespace = {}

else:

# Copy namespace since we're going to mutate it.

namespace = namespace.copy()

anns = {}

for item in fields:

if isinstance(item, str):

name = item

tp = 'typing.Any'

elif len(item) == 2:

name, tp, = item

elif len(item) == 3:

name, tp, spec = item

namespace[name] = spec

anns[name] = tp

namespace['__annotations__'] = anns

cls = type(cls_name, bases, namespace)

return dataclass(cls, init=init, repr=repr, eq=eq, order=order,

"""Return a new object replacing specified fields with new values.