API¶
attrs
works by decorating a class using attr.s()
and then optionally defining attributes on the class using attr.ib()
.
Note
When this documentation speaks about “attrs
attributes” it means those attributes that are defined using attr.ib()
in the class body.
What follows is the API explanation, if you’d like a more hands-on introduction, have a look at Examples.
Core¶
-
attr.
s
(these=None, repr_ns=None, repr=True, cmp=True, hash=True, init=True, slots=False, frozen=False, str=False)¶ A class decorator that adds dunder-methods according to the specified attributes using
attr.ib()
or the these argument.Parameters: - these (
dict
ofstr
toattr.ib()
) –A dictionary of name to
attr.ib()
mappings. This is useful to avoid the definition of your attributes within the class body because you can’t (e.g. if you want to add__repr__
methods to Django models) or don’t want to (e.g. if you want to useproperties
).If these is not
None
, the class body is ignored. - repr_ns (str) – When using nested classes, there’s no way in Python 2
to automatically detect that. Therefore it’s possible to set the
namespace explicitly for a more meaningful
repr
output. - repr (bool) – Create a
__repr__
method with a human readable represantation ofattrs
attributes.. - str (bool) – Create a
__str__
method that is identical to__repr__
. This is usually not necessary except forException
s. - cmp (bool) – Create
__eq__
,__ne__
,__lt__
,__le__
,__gt__
, and__ge__
methods that compare the class as if it were a tuple of itsattrs
attributes. But the attributes are only compared, if the type of both classes is identical! - hash (bool) – Create a
__hash__
method that returns thehash()
of a tuple of allattrs
attribute values. - init (bool) – Create a
__init__
method that initialiazes theattrs
attributes. Leading underscores are stripped for the argument name. If a__attrs_post_init__
method exists on the class, it will be called after the class is fully initialized. - slots (bool) – Create a slots-style class that’s more memory-efficient. See Slots for further ramifications.
- frozen (bool) –
Make instances immutable after initialization. If someone attempts to modify a frozen instance,
attr.exceptions.FrozenInstanceError
is raised.Please note:
- This is achieved by installing a custom
__setattr__
method on your class so you can’t implement an own one. - True immutability is impossible in Python.
- This does have a minor a runtime performance impact when initializing new instances. In other words:
__init__
is slightly slower withfrozen=True
.
- This is achieved by installing a custom
New in version 16.0.0: slots
New in version 16.1.0: frozen
New in version 16.3.0: str, and support for
__attrs_post_init__
.Note
attrs
also comes with a serious business aliasattr.attrs
.For example:
>>> import attr >>> @attr.s ... class C(object): ... _private = attr.ib() >>> C(private=42) C(_private=42) >>> class D(object): ... def __init__(self, x): ... self.x = x >>> D(1) <D object at ...> >>> D = attr.s(these={"x": attr.ib()}, init=False)(D) >>> D(1) D(x=1)
- these (
-
attr.
ib
(default=NOTHING, validator=None, repr=True, cmp=True, hash=True, init=True, convert=None, metadata={})¶ Create a new attribute on a class.
Warning
Does not do anything unless the class is also decorated with
attr.s()
!Parameters: - default (Any value.) –
A value that is used if an
attrs
-generated__init__
is used and no value is passed while instantiating or the attribute is excluded usinginit=False
.If the value is an instance of
Factory
, its callable will be used to construct a new value (useful for mutable datatypes like lists or dicts).If a default is not set (or set manually to
attr.NOTHING
), a value must be supplied when instantiating; otherwise aTypeError
will be raised. - validator (callable) –
callable()
that is called byattrs
-generated__init__
methods after the instance has been initialized. They receive the initialized instance, theAttribute
, and the passed value.The return value is not inspected so the validator has to throw an exception itself.
They can be globally disabled and re-enabled using
get_run_validators()
. - repr (bool) – Include this attribute in the generated
__repr__
method. - cmp (bool) – Include this attribute in the generated comparison methods
(
__eq__
et al). - hash (bool) – Include this attribute in the generated
__hash__
method. - init (bool) – Include this attribute in the generated
__init__
method. It is possible to set this toFalse
and set a default value. In that case this attributed is unconditionally initialized with the specified default value or factory. - convert (callable) –
callable()
that is called byattrs
-generated__init__
methods to convert attribute’s value to the desired format. It is given the passed-in value, and 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. - metadata – An arbitrary mapping, to be used by third-party components.
Note
attrs
also comes with a serious business aliasattr.attrib
.- default (Any value.) –
-
class
attr.
Attribute
(name, default, validator, repr, cmp, hash, init, convert=None, metadata=None)¶ Read-only representation of an attribute.
Attribute name: The name of the attribute. Plus all arguments of
attr.ib()
.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.
Warning
You should never instantiate this class yourself!
>>> import attr >>> @attr.s ... class C(object): ... x = attr.ib() >>> C.x Attribute(name='x', default=NOTHING, validator=None, repr=True, cmp=True, hash=True, init=True, convert=None, metadata=mappingproxy({}))
-
attr.
make_class
(name, attrs, **attributes_arguments)¶ A quick way to create a new class called name with attrs.
Parameters: Returns: A new class with attrs.
Return type: This is handy if you want to programmatically create classes.
For example:
>>> C1 = attr.make_class("C1", ["x", "y"]) >>> C1(1, 2) C1(x=1, y=2) >>> C2 = attr.make_class("C2", {"x": attr.ib(default=42), ... "y": attr.ib(default=attr.Factory(list))}) >>> C2() C2(x=42, y=[])
-
class
attr.
Factory
(factory)¶ Stores a factory callable.
If passed as the default value to
attr.ib()
, the factory is used to generate a new value.For example:
>>> @attr.s ... class C(object): ... x = attr.ib(default=attr.Factory(list)) >>> C() C(x=[])
-
exception
attr.exceptions.
FrozenInstanceError
¶ A frozen/immutable instance has been attempted to be modified.
It mirrors the behavior of
namedtuples
by using the same error message and subclassingAttributeError
.New in version 16.1.0.
-
exception
attr.exceptions.
AttrsAttributeNotFoundError
¶ An
attrs
function couldn’t find an attribute that the user asked for.New in version 16.2.0.
-
exception
attr.exceptions.
NotAnAttrsClassError
¶ A non-
attrs
class has been passed into anattrs
function.New in version 16.2.0.
Helpers¶
attrs
comes with a bunch of helper methods that make working with it easier:
-
attr.
fields
(cls)¶ Returns the tuple of
attrs
attributes for a class.The tuple also allows accessing the fields by their names (see below for examples).
Parameters: cls (type) – Class to introspect.
Raises: - TypeError – If cls is not a class.
- attr.exceptions.NotAnAttrsClassError – If cls is not an
attrs
class.
Return type: tuple (with name accesors) of
attr.Attribute
Changed in version 16.2.0: Returned tuple allows accessing the fields by name.
For example:
>>> @attr.s ... class C(object): ... x = attr.ib() ... y = attr.ib() >>> attr.fields(C) (Attribute(name='x', default=NOTHING, validator=None, repr=True, cmp=True, hash=True, init=True, convert=None, metadata=mappingproxy({})), Attribute(name='y', default=NOTHING, validator=None, repr=True, cmp=True, hash=True, init=True, convert=None, metadata=mappingproxy({}))) >>> attr.fields(C)[1] Attribute(name='y', default=NOTHING, validator=None, repr=True, cmp=True, hash=True, init=True, convert=None, metadata=mappingproxy({})) >>> attr.fields(C).y is attr.fields(C)[1] True
-
attr.
has
(cls)¶ Check whether cls is a class with
attrs
attributes.Parameters: cls (type) – Class to introspect. Raises: TypeError – If cls is not a class. Return type: bool
For example:
>>> @attr.s ... class C(object): ... pass >>> attr.has(C) True >>> attr.has(object) False
-
attr.
asdict
(inst, recurse=True, filter=None, dict_factory=<class 'dict'>, retain_collection_types=False)¶ Return the
attrs
attribute values of inst as a dict.Optionally recurse into other
attrs
-decorated classes.Parameters: - inst – Instance of an
attrs
-decorated class. - recurse (bool) – Recurse into classes that are also
attrs
-decorated. - filter (callable) – A callable whose return code deteremines whether an
attribute or element is included (
True
) or dropped (False
). Is called with theattr.Attribute
as the first argument and the value as the second argument. - dict_factory (callable) – A callable to produce dictionaries from. For
example, to produce ordered dictionaries instead of normal Python
dictionaries, pass in
collections.OrderedDict
. - retain_collection_types (bool) – Do not convert to
list
when encountering an attribute whose type istuple
orset
. Only meaningful ifrecurse
isTrue
.
Return type: return type of dict_factory
Raises: attr.exceptions.NotAnAttrsClassError – If cls is not an
attrs
class.New in version 16.0.0: dict_factory
New in version 16.1.0: retain_collection_types
For example:
>>> @attr.s ... class C(object): ... x = attr.ib() ... y = attr.ib() >>> attr.asdict(C(1, C(2, 3))) {'y': {'y': 3, 'x': 2}, 'x': 1}
- inst – Instance of an
-
attr.
astuple
(inst, recurse=True, filter=None, tuple_factory=<class 'tuple'>, retain_collection_types=False)¶ Return the
attrs
attribute values of inst as a tuple.Optionally recurse into other
attrs
-decorated classes.Parameters: - inst – Instance of an
attrs
-decorated class. - recurse (bool) – Recurse into classes that are also
attrs
-decorated. - filter (callable) – A callable whose return code determines whether an
attribute or element is included (
True
) or dropped (False
). Is called with theattr.Attribute
as the first argument and the value as the second argument. - tuple_factory (callable) – A callable to produce tuples from. For example, to produce lists instead of tuples.
- retain_collection_types (bool) – Do not convert to
list
ordict
when encountering an attribute which type istuple
,dict
orset
. Only meaningful ifrecurse
isTrue
.
Return type: return type of tuple_factory
Raises: attr.exceptions.NotAnAttrsClassError – If cls is not an
attrs
class.New in version 16.2.0.
For example:
>>> @attr.s ... class C(object): ... x = attr.ib() ... y = attr.ib() >>> attr.astuple(C(1,2)) (1, 2)
- inst – Instance of an
attrs
includes some handy helpers for filtering:
-
attr.filters.
include
(*what)¶ Whitelist what.
Parameters: what ( list
oftype
orattr.Attribute
s) – What to whitelist.Return type: callable
-
attr.filters.
exclude
(*what)¶ Blacklist what.
Parameters: what ( list
of classes orattr.Attribute
s.) – What to blacklist.Return type: callable
See Converting to Collections Types for examples.
-
attr.
assoc
(inst, **changes)¶ Copy inst and apply changes.
Parameters: - inst – Instance of a class with
attrs
attributes. - changes – Keyword changes in the new copy.
Returns: A copy of inst with changes incorporated.
Raises: - attr.exceptions.AttrsAttributeNotFoundError – If attr_name couldn’t be found on cls.
- attr.exceptions.NotAnAttrsClassError – If cls is not an
attrs
class.
For example:
>>> @attr.s ... class C(object): ... x = attr.ib() ... y = attr.ib() >>> i1 = C(1, 2) >>> i1 C(x=1, y=2) >>> i2 = attr.assoc(i1, y=3) >>> i2 C(x=1, y=3) >>> i1 == i2 False
- inst – Instance of a class with
-
attr.
validate
(inst)¶ Validate all attributes on inst that have a validator.
Leaves all exceptions through.
Parameters: inst – Instance of a class with attrs
attributes.For example:
>>> @attr.s ... class C(object): ... x = attr.ib(validator=attr.validators.instance_of(int)) >>> i = C(1) >>> i.x = "1" >>> attr.validate(i) Traceback (most recent call last): ... TypeError: ("'x' must be <type 'int'> (got '1' that is a <type 'str'>).", Attribute(name='x', default=NOTHING, validator=<instance_of validator for type <type 'int'>>, repr=True, cmp=True, hash=True, init=True), <type 'int'>, '1')
Validators can be globally disabled if you want to run them only in development and tests but not in production because you fear their performance impact:
-
attr.
set_run_validators
(run)¶ Set whether or not validators are run. By default, they are run.
-
attr.
get_run_validators
()¶ Return whether or not validators are run.
Validators¶
attrs
comes with some common validators in the attrs.validators
module:
-
attr.validators.
instance_of
(type)¶ A validator that raises a
TypeError
if the initializer is called with a wrong type for this particular attribute (checks are perfomed usingisinstance()
therefore it’s also valid to pass a tuple of types).Parameters: type (type or tuple of types) – The type to check for. The
TypeError
is raised with a human readable error message, the attribute (of typeattr.Attribute
), the expected type, and the value it got.For example:
>>> @attr.s ... class C(object): ... x = attr.ib(validator=attr.validators.instance_of(int)) >>> C(42) C(x=42) >>> C("42") Traceback (most recent call last): ... TypeError: ("'x' must be <type 'int'> (got '42' that is a <type 'str'>).", Attribute(name='x', default=NOTHING, validator=<instance_of validator for type <type 'int'>>), <type 'int'>, '42') >>> C(None) Traceback (most recent call last): ... TypeError: ("'x' must be <type 'int'> (got None that is a <type 'NoneType'>).", Attribute(name='x', default=NOTHING, validator=<instance_of validator for type <type 'int'>>, repr=True, cmp=True, hash=True, init=True), <type 'int'>, None)
-
attr.validators.
provides
(interface)¶ A validator that raises a
TypeError
if the initializer is called with an object that does not provide the requested interface (checks are performed usinginterface.providedBy(value)
(see zope.interface).Parameters: interface (zope.interface.Interface) – The interface to check for. The
TypeError
is raised with a human readable error message, the attribute (of typeattr.Attribute
), the expected interface, and the value it got.
-
attr.validators.
optional
(validator)¶ A validator that makes an attribute optional. An optional attribute is one which can be set to
None
in addition to satisfying the requirements of the sub-validator.Parameters: validator – A validator that is used for non- None
values.For example:
>>> @attr.s ... class C(object): ... x = attr.ib(validator=attr.validators.optional(attr.validators.instance_of(int))) >>> C(42) C(x=42) >>> C("42") Traceback (most recent call last): ... TypeError: ("'x' must be <type 'int'> (got '42' that is a <type 'str'>).", Attribute(name='x', default=NOTHING, validator=<instance_of validator for type <type 'int'>>), <type 'int'>, '42') >>> C(None) C(x=None)
Deprecated APIs¶
The serious business aliases used to be called attr.attributes
and attr.attr
.
There are no plans to remove them but they shouldn’t be used in new code.