attrs

asdict(inst, *, recurse=True, filter=None, value_serializer=None)[source]#

Same as attr.asdict, except that collections types are always retained and dict is always used as dict_factory.

Added in version 21.3.0.

assoc(inst, **changes)[source]#

Copy inst and apply changes.

This is different from evolve that applies the changes to the arguments that create the new instance.

evolve’s behavior is preferable, but there are edge cases where it doesn’t work. Therefore assoc is deprecated, but will not be removed.

Args:

inst: Instance of a class with attrs attributes.

changes: Keyword changes in the new copy.

Returns:

A copy of inst with changes incorporated.

Raises:

attrs.exceptions.AttrsAttributeNotFoundError:: If attr_name couldn’t be found on cls.
attrs.exceptions.NotAnAttrsClassError:: If cls is not an attrs class.

Deprecated since version 17.1.0: Use attrs.evolve instead if you can. This function will not be removed du to the slightly different approach compared to attrs.evolve, though.

astuple(inst, *, recurse=True, filter=None)[source]#

Same as attr.astuple, except that collections types are always retained and tuple is always used as the tuple_factory.

Added in version 21.3.0.

class Attribute[source]#

Read-only representation of an attribute.

Warning

You should never instantiate this class yourself.

The class has all arguments of attr.ib (except for factory which is only syntactic sugar for default=Factory(...) plus the following:

name (str): The name of the attribute.
alias (str): The __init__ parameter name of the attribute, after any explicit overrides and default private-attribute-name handling.
inherited (bool): Whether or not that attribute has been inherited from a base class.
eq_key and order_key (typing.Callable or None): The callables that are used for comparing and ordering objects by this attribute, respectively. These are set by passing a callable to attr.ib’s eq, order, or cmp arguments. See also comparison customization.

Instances of this class are frequently used for introspection purposes like:

fields returns a tuple of them.
Validators get them passed as the first argument.
The field transformer hook receives a list of them.
The alias property exposes the __init__ parameter name of the field, with any overrides and default private-attribute handling applied.

Added in version 20.1.0: inherited

Added in version 20.1.0: on_setattr

Changed in version 20.2.0: inherited is not taken into account for equality checks and hashing anymore.

Added in version 21.1.0: eq_key and order_key

Added in version 22.2.0: alias

For the full version history of the fields, see attr.ib.

__init__(name, default, validator, repr, cmp, hash, init, inherited, metadata=None, type=None, converter=None, kw_only=False, eq=None, eq_key=None, order=None, order_key=None, on_setattr=None, alias=None)[source]#

classmethod from_counting_attr(name, ca, type=None)[source]#

evolve(**changes)[source]#

Copy self and apply changes.

This works similarly to attrs.evolve but that function does not work with {class}`Attribute`.

It is mainly meant to be used for transform-fields.

Added in version 20.3.0.

__getstate__()[source]#: Play nice with pickle.

__setstate__(state)[source]#: Play nice with pickle.

name#

default#

validator#

repr#

eq#

eq_key#

order#

order_key#

hash#

init#

metadata#

type#

converter#

kw_only#

inherited#

on_setattr#

alias#

class AttrsInstance[source]#

__init__(*args, **kwargs)#

cmp_using(eq=None, lt=None, le=None, gt=None, ge=None, require_same_type=True, class_name='Comparable')[source]#

Create a class that can be passed into attrs.field’s eq, order, and cmp arguments to customize field comparison.

The resulting class will have a full set of ordering methods if at least one of {lt, le, gt, ge} and eq are provided.

Args:

eq (typing.Callable | None):: Callable used to evaluate equality of two objects.
lt (typing.Callable | None):: Callable used to evaluate whether one object is less than another object.
le (typing.Callable | None):: Callable used to evaluate whether one object is less than or equal to another object.
gt (typing.Callable | None):: Callable used to evaluate whether one object is greater than another object.
ge (typing.Callable | None):: Callable used to evaluate whether one object is greater than or equal to another object.
require_same_type (bool):: When True, equality and ordering methods will return NotImplemented if objects are not of the same type.

class_name (str | None): Name of class. Defaults to “Comparable”.

See comparison for more details.

Added in version 21.1.0.

class Converter[source]#

Stores a converter callable.

Allows for the wrapped converter to take additional arguments. The arguments are passed in the order they are documented.

Args:

converter (Callable): A callable that converts the passed value.

takes_self (bool):: Pass the partially initialized instance that is being initialized as a positional argument. (default: False)
takes_field (bool):: Pass the field definition (an Attribute) into the converter as a positional argument. (default: False)

Added in version 24.1.0.

__init__(converter, *, takes_self=False, takes_field=False)[source]#

converter#

takes_self#

takes_field#

__getstate__()[source]#: Return a dict containing only converter and takes_self – the rest gets computed when loading.

__setstate__(state)[source]#: Load instance from state.

define(maybe_cls=None, *, these=None, repr=None, unsafe_hash=None, hash=None, init=None, slots=True, frozen=False, weakref_slot=True, str=False, auto_attribs=None, kw_only=False, cache_hash=False, auto_exc=True, eq=None, order=False, auto_detect=True, getstate_setstate=None, on_setattr=None, field_transformer=None, match_args=True)[source]#

A class decorator that adds dunder methods according to fields specified using type annotations, field() calls, or the these argument.

Since attrs patches or replaces an existing class, you cannot use object.__init_subclass__ with attrs classes, because it runs too early. As a replacement, you can define __attrs_init_subclass__ on your class. It will be called by attrs classes that subclass it after they’re created. See also init-subclass.

Args:

slots (bool):

Create a slotted class that’s more memory-efficient. Slotted classes are generally superior to the default dict classes, but have some gotchas you should know about, so we encourage you to read the glossary entry.

auto_detect (bool):

Instead of setting the init, repr, eq, and hash arguments explicitly, assume they are set to True unless any of the involved methods for one of the arguments is implemented in the current class (meaning, it is not inherited from some base class).

So, for example by implementing __eq__ on a class yourself, attrs will deduce eq=False and will create neither __eq__ nor __ne__ (but Python classes come with a sensible __ne__ by default, so it should be enough to only implement __eq__ in most cases).

Passing True or False` to init, repr, eq, cmp, or hash overrides whatever auto_detect would determine.

auto_exc (bool):

If the class subclasses BaseException (which implicitly includes any subclass of any exception), the following happens to behave like a well-behaved Python exception class:

the values for eq, order, and hash are ignored and the instances compare and hash by the instance’s ids [1] ,
all attributes that are either passed into __init__ or have a default value are additionally available as a tuple in the args attribute,
the value of str is ignored leaving __str__ to base classes.

on_setattr (~typing.Callable | list[~typing.Callable] | None | ~typing.Literal[attrs.setters.NO_OP]):

A callable that is run whenever the user attempts to set an attribute (either by assignment like i.x = 42 or by using setattr like setattr(i, "x", 42)). It receives the same arguments as validators: the instance, the attribute that is being modified, and the new value.

If no exception is raised, the attribute is set to the return value of the callable.

If a list of callables is passed, they’re automatically wrapped in an attrs.setters.pipe.

If left None, the default behavior is to run converters and validators whenever an attribute is set.

init (bool):

Create a __init__ method that initializes the attrs attributes. Leading underscores are stripped for the argument name, unless an alias is set on the attribute.

See also

init shows advanced ways to customize the generated __init__ method, including executing code before and after.

repr(bool):

Create a __repr__ method with a human readable representation of attrs attributes.

str (bool):

Create a __str__ method that is identical to __repr__. This is usually not necessary except for Exceptions.

eq (bool | None):

If True or None (default), add __eq__ and __ne__ methods that check two instances for equality.

See also

comparison describes how to customize the comparison behavior going as far comparing NumPy arrays.

order (bool | None):

If True, add __lt__, __le__, __gt__, and __ge__ methods that behave like eq above and allow instances to be ordered.

They compare the instances as if they were tuples of their attrs attributes if and only if the types of both classes are identical.

If None mirror value of eq.

See also

comparison

cmp (bool | None):

Setting cmp is equivalent to setting eq and order to the same value. Must not be mixed with eq or order.

unsafe_hash (bool | None):

If None (default), the __hash__ method is generated according how eq and frozen are set.

If both are True, attrs will generate a __hash__ for you.
If eq is True and frozen is False, __hash__ will be set to None, marking it unhashable (which it is).
If eq is False, __hash__ will be left untouched meaning the __hash__ method of the base class will be used. If the base class is object, this means it will fall back to id-based hashing.

Although not recommended, you can decide for yourself and force attrs to create one (for example, if the class is immutable even though you didn’t freeze it programmatically) by passing True or not. Both of these cases are rather special and should be used carefully.

See also

Our documentation on hashing,
Python’s documentation on object.__hash__,
and the GitHub issue that led to the default behavior for more details.

hash (bool | None):

Deprecated alias for unsafe_hash. unsafe_hash takes precedence.

cache_hash (bool):

Ensure that the object’s hash code is computed only once and stored on the object. If this is set to True, hashing must be either explicitly or implicitly enabled for this class. If the hash code is cached, avoid any reassignments of fields involved in hash code computation or mutations of the objects those fields point to after object creation. If such changes occur, the behavior of the object’s hash code is undefined.

frozen (bool):

Make instances immutable after initialization. If someone attempts to modify a frozen instance, attrs.exceptions.FrozenInstanceError is raised.

Note

This is achieved by installing a custom __setattr__ method on your class, so you can’t implement your own.
True immutability is impossible in Python.
This does have a minor a runtime performance impact <how-frozen> when initializing new instances. In other words: __init__ is slightly slower with frozen=True.
If a class is frozen, you cannot modify self in __attrs_post_init__ or a self-written __init__. You can circumvent that limitation by using object.__setattr__(self, "attribute_name", value).
Subclasses of a frozen class are frozen too.

kw_only (bool):

Make all attributes keyword-only in the generated __init__ (if init is False, this parameter is ignored).

weakref_slot (bool):

Make instances weak-referenceable. This has no effect unless slots is True.

field_transformer (~typing.Callable | None):

A function that is called with the original class object and all fields right before attrs finalizes the class. You can use this, for example, to automatically add converters or validators to fields based on their types.

See also

transform-fields

match_args (bool):

If True (default), set __match_args__ on the class to support PEP 634 (Structural Pattern Matching). It is a tuple of all non-keyword-only __init__ parameter names on Python 3.10 and later. Ignored on older Python versions.

collect_by_mro (bool):

If True, attrs collects attributes from base classes correctly according to the method resolution order. If False, attrs will mimic the (wrong) behavior of dataclasses and PEP 681.

See also

defaults

factory (~typing.Callable):

Syntactic sugar for default=attr.Factory(factory).

validator (~typing.Callable | list[~typing.Callable]):

Callable that is called by attrs-generated __init__ methods after the instance has been initialized. They receive the initialized instance, the Attribute(), and the passed value.

The return value is not inspected so the validator has to throw an exception itself.

If a list is passed, its items are treated as validators and must all pass.

Validators can be globally disabled and re-enabled using attrs.validators.get_disabled / attrs.validators.set_disabled.

The validator can also be set using decorator notation as shown below.

See also

validators

repr (bool | ~typing.Callable):

Include this attribute in the generated __repr__ method. If True, include the attribute; if False, omit it. By default, the built-in repr() function is used. To override how the attribute value is formatted, pass a callable that takes a single value and returns a string. Note that the resulting string is used as-is, which means it will be used directly instead of calling repr() (the default).

eq (bool | ~typing.Callable):

If True (default), include this attribute in the generated __eq__ and __ne__ methods that check two instances for equality. To override how the attribute value is compared, pass a callable that takes a single value and returns the value to be compared.

See also

comparison

order (bool | ~typing.Callable):

If True (default), include this attributes in the generated __lt__, __le__, __gt__ and __ge__ methods. To override how the attribute value is ordered, pass a callable that takes a single value and returns the value to be ordered.

See also

comparison

cmp(bool | ~typing.Callable):

Setting cmp is equivalent to setting eq and order to the same value. Must not be mixed with eq or order.

See also

comparison

hash (bool | None):

Include this attribute in the generated __hash__ method. If None (default), mirror eq’s value. This is the correct behavior according the Python spec. Setting this value to anything else than None is discouraged.

See also

hashing

init (bool):

Include this attribute in the generated __init__ method.

It is possible to set this to False and set a default value. In that case this attributed is unconditionally initialized with the specified default value or factory.

See also

init

converter (typing.Callable | Converter):

A callable that is called by attrs-generated __init__ methods to convert attribute’s value to the desired format.

If a vanilla callable is passed, it is given the passed-in value as the only positional argument. It is possible to receive additional arguments by wrapping the callable in a Converter.

Either way, the returned value will be used as the new value of the attribute. The value is converted before being passed to the validator, if any.

See also

converters

metadata (dict | None):

An arbitrary mapping, to be used by third-party code.

See also

extending-metadata.

type (type):

The type of the attribute. Nowadays, the preferred method to specify the type is using a variable annotation (see PEP 526). This argument is provided for backwards-compatibility and for usage with make_class. Regardless of the approach used, the type will be stored on Attribute.type.

Please note that attrs doesn’t do anything with this metadata by itself. You can use it as part of your own code or for static type checking <types>.

kw_only (bool):

Make this attribute keyword-only in the generated __init__ (if init is False, this parameter is ignored).

on_setattr (~typing.Callable | list[~typing.Callable] | None | ~typing.Literal[attrs.setters.NO_OP]):

Allows to overwrite the on_setattr setting from attr.s. If left None, the on_setattr value from attr.s is used. Set to attrs.setters.NO_OP to run no setattr hooks for this attribute – regardless of the setting in define().

alias (str | None):

Override this attribute’s parameter name in the generated __init__ method. If left None, default to name stripped of leading underscores. See private-attributes.

Added in version 20.1.0.

Changed in version 21.1.0: eq, order, and cmp also accept a custom callable

Added in version 22.2.0: alias

Added in version 23.1.0: The type parameter has been re-added; mostly for attrs.make_class. Please note that type checkers ignore this metadata.

See also

attr.ib

fields_dict(cls)[source]#

Return an ordered dictionary of attrs attributes for a class, whose keys are the attribute names.

Args:

cls (type): Class to introspect.

Raises:

TypeError: If cls is not a class.

attrs.exceptions.NotAnAttrsClassError:: If cls is not an attrs class.

Returns:

dict[str, attrs.Attribute]: Dict of attribute name to definition

Added in version 18.1.0.

fields(cls)[source]#

Return the tuple of attrs attributes for a class.

The tuple also allows accessing the fields by their names (see below for examples).

Args:

cls (type): Class to introspect.

Raises:

TypeError: If cls is not a class.

attrs.exceptions.NotAnAttrsClassError:: If cls is not an attrs class.

Returns:

tuple (with name accessors) of attrs.Attribute

Changed in version 16.2.0: Returned tuple allows accessing the fields by name.

Changed in version 23.1.0: Add support for generic classes.

frozen(maybe_cls=None, *, these=None, repr=None, unsafe_hash=None, hash=None, init=None, slots=True, frozen=True, weakref_slot=True, str=False, auto_attribs=None, kw_only=False, cache_hash=False, auto_exc=True, eq=None, order=False, auto_detect=True, getstate_setstate=None, on_setattr=None, field_transformer=None, match_args=True)#

A class decorator that adds dunder methods according to fields specified using type annotations, field() calls, or the these argument.

Since attrs patches or replaces an existing class, you cannot use object.__init_subclass__ with attrs classes, because it runs too early. As a replacement, you can define __attrs_init_subclass__ on your class. It will be called by attrs classes that subclass it after they’re created. See also init-subclass.

Args:

slots (bool):

Create a slotted class that’s more memory-efficient. Slotted classes are generally superior to the default dict classes, but have some gotchas you should know about, so we encourage you to read the glossary entry.

auto_detect (bool):

Instead of setting the init, repr, eq, and hash arguments explicitly, assume they are set to True unless any of the involved methods for one of the arguments is implemented in the current class (meaning, it is not inherited from some base class).

So, for example by implementing __eq__ on a class yourself, attrs will deduce eq=False and will create neither __eq__ nor __ne__ (but Python classes come with a sensible __ne__ by default, so it should be enough to only implement __eq__ in most cases).

Passing True or False` to init, repr, eq, cmp, or hash overrides whatever auto_detect would determine.

auto_exc (bool):

If the class subclasses BaseException (which implicitly includes any subclass of any exception), the following happens to behave like a well-behaved Python exception class:

the values for eq, order, and hash are ignored and the instances compare and hash by the instance’s ids [2] ,
all attributes that are either passed into __init__ or have a default value are additionally available as a tuple in the args attribute,
the value of str is ignored leaving __str__ to base classes.

on_setattr (~typing.Callable | list[~typing.Callable] | None | ~typing.Literal[attrs.setters.NO_OP]):

A callable that is run whenever the user attempts to set an attribute (either by assignment like i.x = 42 or by using setattr like setattr(i, "x", 42)). It receives the same arguments as validators: the instance, the attribute that is being modified, and the new value.

If no exception is raised, the attribute is set to the return value of the callable.

If a list of callables is passed, they’re automatically wrapped in an attrs.setters.pipe.

If left None, the default behavior is to run converters and validators whenever an attribute is set.

init (bool):

Create a __init__ method that initializes the attrs attributes. Leading underscores are stripped for the argument name, unless an alias is set on the attribute.

See also

init shows advanced ways to customize the generated __init__ method, including executing code before and after.

repr(bool):

Create a __repr__ method with a human readable representation of attrs attributes.

str (bool):

Create a __str__ method that is identical to __repr__. This is usually not necessary except for Exceptions.

eq (bool | None):

If True or None (default), add __eq__ and __ne__ methods that check two instances for equality.

See also

comparison describes how to customize the comparison behavior going as far comparing NumPy arrays.

order (bool | None):

If True, add __lt__, __le__, __gt__, and __ge__ methods that behave like eq above and allow instances to be ordered.

They compare the instances as if they were tuples of their attrs attributes if and only if the types of both classes are identical.

If None mirror value of eq.

See also

comparison

cmp (bool | None):

Setting cmp is equivalent to setting eq and order to the same value. Must not be mixed with eq or order.

unsafe_hash (bool | None):

If None (default), the __hash__ method is generated according how eq and frozen are set.

If both are True, attrs will generate a __hash__ for you.
If eq is True and frozen is False, __hash__ will be set to None, marking it unhashable (which it is).
If eq is False, __hash__ will be left untouched meaning the __hash__ method of the base class will be used. If the base class is object, this means it will fall back to id-based hashing.

Although not recommended, you can decide for yourself and force attrs to create one (for example, if the class is immutable even though you didn’t freeze it programmatically) by passing True or not. Both of these cases are rather special and should be used carefully.

See also

Our documentation on hashing,
Python’s documentation on object.__hash__,
and the GitHub issue that led to the default behavior for more details.

hash (bool | None):

Deprecated alias for unsafe_hash. unsafe_hash takes precedence.

cache_hash (bool):

Ensure that the object’s hash code is computed only once and stored on the object. If this is set to True, hashing must be either explicitly or implicitly enabled for this class. If the hash code is cached, avoid any reassignments of fields involved in hash code computation or mutations of the objects those fields point to after object creation. If such changes occur, the behavior of the object’s hash code is undefined.

frozen (bool):

Make instances immutable after initialization. If someone attempts to modify a frozen instance, attrs.exceptions.FrozenInstanceError is raised.

Note

This is achieved by installing a custom __setattr__ method on your class, so you can’t implement your own.
True immutability is impossible in Python.
This does have a minor a runtime performance impact <how-frozen> when initializing new instances. In other words: __init__ is slightly slower with frozen=True.
If a class is frozen, you cannot modify self in __attrs_post_init__ or a self-written __init__. You can circumvent that limitation by using object.__setattr__(self, "attribute_name", value).
Subclasses of a frozen class are frozen too.

kw_only (bool):

Make all attributes keyword-only in the generated __init__ (if init is False, this parameter is ignored).

weakref_slot (bool):

Make instances weak-referenceable. This has no effect unless slots is True.

field_transformer (~typing.Callable | None):

A function that is called with the original class object and all fields right before attrs finalizes the class. You can use this, for example, to automatically add converters or validators to fields based on their types.

See also

transform-fields

match_args (bool):

If True (default), set __match_args__ on the class to support PEP 634 (Structural Pattern Matching). It is a tuple of all non-keyword-only __init__ parameter names on Python 3.10 and later. Ignored on older Python versions.

collect_by_mro (bool):

If True, attrs collects attributes from base classes correctly according to the method resolution order. If False, attrs will mimic the (wrong) behavior of dataclasses and PEP 681.

See also

init shows advanced ways to customize the generated __init__ method, including executing code before and after.

repr(bool):

Create a __repr__ method with a human readable representation of attrs attributes.

str (bool):

Create a __str__ method that is identical to __repr__. This is usually not necessary except for Exceptions.

eq (bool | None):

If True or None (default), add __eq__ and __ne__ methods that check two instances for equality.

See also

comparison describes how to customize the comparison behavior going as far comparing NumPy arrays.

order (bool | None):

If True, add __lt__, __le__, __gt__, and __ge__ methods that behave like eq above and allow instances to be ordered.

They compare the instances as if they were tuples of their attrs attributes if and only if the types of both classes are identical.

If None mirror value of eq.

See also

comparison

cmp (bool | None):

Setting cmp is equivalent to setting eq and order to the same value. Must not be mixed with eq or order.

unsafe_hash (bool | None):

If None (default), the __hash__ method is generated according how eq and frozen are set.

If both are True, attrs will generate a __hash__ for you.
If eq is True and frozen is False, __hash__ will be set to None, marking it unhashable (which it is).
If eq is False, __hash__ will be left untouched meaning the __hash__ method of the base class will be used. If the base class is object, this means it will fall back to id-based hashing.

Although not recommended, you can decide for yourself and force attrs to create one (for example, if the class is immutable even though you didn’t freeze it programmatically) by passing True or not. Both of these cases are rather special and should be used carefully.

See also

Our documentation on hashing,
Python’s documentation on object.__hash__,
and the GitHub issue that led to the default behavior for more details.

hash (bool | None):

Deprecated alias for unsafe_hash. unsafe_hash takes precedence.

cache_hash (bool):

Ensure that the object’s hash code is computed only once and stored on the object. If this is set to True, hashing must be either explicitly or implicitly enabled for this class. If the hash code is cached, avoid any reassignments of fields involved in hash code computation or mutations of the objects those fields point to after object creation. If such changes occur, the behavior of the object’s hash code is undefined.

frozen (bool):

Make instances immutable after initialization. If someone attempts to modify a frozen instance, attrs.exceptions.FrozenInstanceError is raised.

Note

This is achieved by installing a custom __setattr__ method on your class, so you can’t implement your own.
True immutability is impossible in Python.
This does have a minor a runtime performance impact <how-frozen> when initializing new instances. In other words: __init__ is slightly slower with frozen=True.
If a class is frozen, you cannot modify self in __attrs_post_init__ or a self-written __init__. You can circumvent that limitation by using object.__setattr__(self, "attribute_name", value).
Subclasses of a frozen class are frozen too.

kw_only (bool):

Make all attributes keyword-only in the generated __init__ (if init is False, this parameter is ignored).

weakref_slot (bool):

Make instances weak-referenceable. This has no effect unless slots is True.

field_transformer (~typing.Callable | None):

A function that is called with the original class object and all fields right before attrs finalizes the class. You can use this, for example, to automatically add converters or validators to fields based on their types.

See also

transform-fields

match_args (bool):

If True (default), set __match_args__ on the class to support PEP 634 (Structural Pattern Matching). It is a tuple of all non-keyword-only __init__ parameter names on Python 3.10 and later. Ignored on older Python versions.

collect_by_mro (bool):

If True, attrs collects attributes from base classes correctly according to the method resolution order. If False, attrs will mimic the (wrong) behavior of dataclasses and PEP 681.

Contents

attrs#