2017-10-26 15:55:45 +00:00
API Reference
=============
2015-01-28 13:36:11 +00:00
.. currentmodule :: attr
2021-12-25 14:15:10 +00:00
`` attrs `` works by decorating a class using `attrs.define` or `attr.s` and then optionally defining attributes on the class using `attrs.field` , `attr.ib` , or a type annotation.
2015-01-28 13:36:11 +00:00
2021-11-24 08:39:41 +00:00
If you're confused by the many names, please check out `names` for clarification.
2015-01-28 15:02:18 +00:00
2019-09-09 13:02:16 +00:00
What follows is the API explanation, if you'd like a more hands-on introduction, have a look at `examples` .
2015-01-28 13:36:11 +00:00
2022-05-06 18:09:28 +00:00
As of version 21.3.0, `` attrs `` consists of **two** top-level package names:
2021-12-25 14:15:10 +00:00
- The classic `` attr `` that powered the venerable `attr.s` and `attr.ib`
- The modern `` attrs `` that only contains most modern APIs and relies on `attrs.define` and `attrs.field` to define your classes.
Additionally it offers some `` attr `` APIs with nicer defaults (e.g. `attrs.asdict` ).
2021-12-27 08:21:11 +00:00
The `` attrs `` namespace is built *on top of* `` attr `` which will *never* go away.
2021-12-25 14:15:10 +00:00
2015-01-28 13:36:11 +00:00
Core
----
2021-04-09 18:36:10 +00:00
.. note ::
2021-12-29 06:42:51 +00:00
Please note that the `` attrs `` namespace has been added in version 21.3.0.
2021-12-25 14:15:10 +00:00
Most of the objects are simply re-imported from `` attr `` .
Therefore if a class, method, or function claims that it has been added in an older version, it is only available in the `` attr `` namespace.
.. autodata :: attrs.NOTHING
2022-08-27 15:41:56 +00:00
:no-value:
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.define
.. function :: attrs.mutable(same_as_define)
2020-08-17 14:22:33 +00:00
2021-12-25 14:15:10 +00:00
Alias for `attrs.define` .
.. versionadded :: 20.1.0
.. function :: attrs.frozen(same_as_define)
Behaves the same as `attrs.define` but sets *frozen=True* and *on_setattr=None* .
.. versionadded :: 20.1.0
2020-08-17 14:22:33 +00:00
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.field
.. function :: define
Old import path for `attrs.define` .
.. function :: mutable
Old import path for `attrs.mutable` .
.. function :: frozen
Old import path for `attrs.frozen` .
.. function :: field
Old import path for `attrs.field` .
.. autoclass :: attrs.Attribute
:members: evolve
For example:
.. doctest ::
>>> import attr
>>> @attr.s
2022-03-21 09:35:44 +00:00
... class C:
2021-12-25 14:15:10 +00:00
... x = attr.ib()
>>> attr.fields(C).x
2022-11-30 14:39:57 +00:00
Attribute(name='x', default=NOTHING, validator=None, repr=True, eq=True, eq_key=None, order=True, order_key=None, hash=None, init=True, metadata=mappingproxy({}), type=None, converter=None, kw_only=False, inherited=False, on_setattr=None, alias='x')
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.make_class
This is handy if you want to programmatically create classes.
For example:
.. doctest ::
>>> 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=[])
.. autoclass :: attrs.Factory
For example:
.. doctest ::
>>> @attr.s
2022-03-21 09:35:44 +00:00
... class C:
2021-12-25 14:15:10 +00:00
... x = attr.ib(default=attr.Factory(list))
... y = attr.ib(default=attr.Factory(
... lambda self: set(self.x),
... takes_self=True)
... )
>>> C()
C(x=[], y=set())
>>> C([1, 2, 3])
C(x=[1, 2, 3], y={1, 2, 3})
Classic
~~~~~~~
.. data :: attr.NOTHING
Same as `attrs.NOTHING` .
2020-07-20 10:43:10 +00:00
2021-05-18 05:02:06 +00:00
.. autofunction :: attr.s(these=None, repr_ns=None, repr=None, cmp=None, hash=None, init=None, slots=False, frozen=False, weakref_slot=True, str=False, auto_attribs=False, kw_only=False, cache_hash=False, auto_exc=False, eq=None, order=None, auto_detect=False, collect_by_mro=False, getstate_setstate=None, on_setattr=None, field_transformer=None, match_args=True)
2015-01-28 13:36:11 +00:00
2015-01-29 09:17:08 +00:00
.. note ::
2022-07-28 07:23:44 +00:00
`` attrs `` also comes with a serious-business alias `` attr.attrs `` .
2015-01-29 09:17:08 +00:00
2015-02-08 11:32:32 +00:00
For example:
.. doctest ::
>>> import attr
>>> @attr.s
2022-03-21 09:35:44 +00:00
... class C:
2015-02-08 11:32:32 +00:00
... _private = attr.ib()
>>> C(private=42)
C(_private=42)
2022-03-21 09:35:44 +00:00
>>> class D:
2015-02-08 11:32:32 +00:00
... def __init__(self, x):
... self.x = x
>>> D(1)
<D object at ...>
2015-02-20 12:29:47 +00:00
>>> D = attr.s(these={"x": attr.ib()}, init=False)(D)
2015-02-08 11:32:32 +00:00
>>> D(1)
D(x=1)
2019-02-25 17:51:36 +00:00
>>> @attr.s(auto_exc=True)
... class Error(Exception):
... x = attr.ib()
... y = attr.ib(default=42, init=False)
>>> Error("foo")
Error(x='foo', y=42)
>>> raise Error("foo")
Traceback (most recent call last):
...
Error: ('foo', 42)
>>> raise ValueError("foo", 42) # for comparison
Traceback (most recent call last):
...
ValueError: ('foo', 42)
2015-02-08 11:32:32 +00:00
2015-01-28 13:36:11 +00:00
.. autofunction :: attr.ib
2015-01-29 09:17:08 +00:00
.. note ::
2022-07-28 07:23:44 +00:00
`` attrs `` also comes with a serious-business alias `` attr.attrib `` .
2015-01-29 09:17:08 +00:00
2019-09-09 13:02:16 +00:00
The object returned by `attr.ib` also allows for setting the default and the validator using decorators:
2017-02-11 15:55:39 +00:00
2017-05-22 23:42:40 +00:00
.. doctest ::
>>> @attr.s
2022-03-21 09:35:44 +00:00
... class C:
2017-05-22 23:42:40 +00:00
... x = attr.ib()
... y = attr.ib()
... @x.validator
2019-06-17 07:17:29 +00:00
... def _any_name_except_a_name_of_an_attribute(self, attribute, value):
2017-05-22 23:42:40 +00:00
... if value < 0:
... raise ValueError("x must be positive")
... @y.default
2019-06-17 07:17:29 +00:00
... def _any_name_except_a_name_of_an_attribute(self):
2017-05-22 23:42:40 +00:00
... return self.x + 1
>>> C(1)
C(x=1, y=2)
>>> C(-1)
Traceback (most recent call last):
...
ValueError: x must be positive
2015-01-28 13:36:11 +00:00
2015-01-29 22:10:56 +00:00
2015-01-30 07:57:33 +00:00
2021-12-25 14:15:10 +00:00
Exceptions
----------
2015-01-29 22:10:56 +00:00
2021-12-25 14:15:10 +00:00
All exceptions are available from both `` attr.exceptions `` and `` attrs.exceptions `` and are the same thing.
That means that it doesn't matter from from which namespace they've been raised and/or caught:
2015-01-29 11:20:17 +00:00
2021-12-25 14:15:10 +00:00
.. doctest ::
2015-01-29 11:20:17 +00:00
2021-12-25 14:15:10 +00:00
>>> import attrs, attr
>>> try:
... raise attrs.exceptions.FrozenError()
... except attr.exceptions.FrozenError:
... print("this works!")
this works!
2020-01-06 11:34:58 +00:00
2021-12-25 14:15:10 +00:00
.. autoexception :: attrs.exceptions.PythonTooOldError
.. autoexception :: attrs.exceptions.FrozenError
.. autoexception :: attrs.exceptions.FrozenInstanceError
.. autoexception :: attrs.exceptions.FrozenAttributeError
.. autoexception :: attrs.exceptions.AttrsAttributeNotFoundError
.. autoexception :: attrs.exceptions.NotAnAttrsClassError
.. autoexception :: attrs.exceptions.DefaultAlreadySetError
.. autoexception :: attrs.exceptions.UnannotatedAttributeError
.. autoexception :: attrs.exceptions.NotCallableError
2017-11-08 10:15:21 +00:00
For example::
@attr.s(auto_attribs=True)
class C:
x: int
2018-05-01 10:18:26 +00:00
y = attr.ib() # <- ERROR!
2016-08-20 16:45:15 +00:00
2016-08-30 10:12:02 +00:00
.. _helpers:
2015-01-28 13:36:11 +00:00
Helpers
-------
2016-08-15 08:00:23 +00:00
`` attrs `` comes with a bunch of helper methods that make working with it easier:
2015-01-28 13:36:11 +00:00
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.cmp_using
.. function :: attr.cmp_using
Same as `attrs.cmp_using` .
2021-05-04 15:41:14 +00:00
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.fields
2015-01-28 13:36:11 +00:00
For example:
.. doctest ::
>>> @attr.s
2022-03-21 09:35:44 +00:00
... class C:
2015-01-28 13:36:11 +00:00
... x = attr.ib()
... y = attr.ib()
2021-12-25 14:15:10 +00:00
>>> attrs.fields(C)
2022-11-30 14:39:57 +00:00
(Attribute(name='x', default=NOTHING, validator=None, repr=True, eq=True, eq_key=None, order=True, order_key=None, hash=None, init=True, metadata=mappingproxy({}), type=None, converter=None, kw_only=False, inherited=False, on_setattr=None, alias='x'), Attribute(name='y', default=NOTHING, validator=None, repr=True, eq=True, eq_key=None, order=True, order_key=None, hash=None, init=True, metadata=mappingproxy({}), type=None, converter=None, kw_only=False, inherited=False, on_setattr=None, alias='y'))
2021-12-25 14:15:10 +00:00
>>> attrs.fields(C)[1]
2022-11-30 14:39:57 +00:00
Attribute(name='y', default=NOTHING, validator=None, repr=True, eq=True, eq_key=None, order=True, order_key=None, hash=None, init=True, metadata=mappingproxy({}), type=None, converter=None, kw_only=False, inherited=False, on_setattr=None, alias='y')
2021-12-25 14:15:10 +00:00
>>> attrs.fields(C).y is attrs.fields(C)[1]
2016-09-10 17:55:27 +00:00
True
2015-01-28 13:36:11 +00:00
2021-12-25 14:15:10 +00:00
.. function :: attr.fields
Same as `attrs.fields` .
.. autofunction :: attrs.fields_dict
2018-03-03 14:09:05 +00:00
For example:
.. doctest ::
>>> @attr.s
2022-03-21 09:35:44 +00:00
... class C:
2018-03-03 14:09:05 +00:00
... x = attr.ib()
... y = attr.ib()
2021-12-25 14:15:10 +00:00
>>> attrs.fields_dict(C)
2022-11-30 14:39:57 +00:00
{'x': Attribute(name='x', default=NOTHING, validator=None, repr=True, eq=True, eq_key=None, order=True, order_key=None, hash=None, init=True, metadata=mappingproxy({}), type=None, converter=None, kw_only=False, inherited=False, on_setattr=None, alias='x'), 'y': Attribute(name='y', default=NOTHING, validator=None, repr=True, eq=True, eq_key=None, order=True, order_key=None, hash=None, init=True, metadata=mappingproxy({}), type=None, converter=None, kw_only=False, inherited=False, on_setattr=None, alias='y')}
2018-03-03 14:09:05 +00:00
>>> attr.fields_dict(C)['y']
2022-11-30 14:39:57 +00:00
Attribute(name='y', default=NOTHING, validator=None, repr=True, eq=True, eq_key=None, order=True, order_key=None, hash=None, init=True, metadata=mappingproxy({}), type=None, converter=None, kw_only=False, inherited=False, on_setattr=None, alias='y')
2021-12-25 14:15:10 +00:00
>>> attrs.fields_dict(C)['y'] is attrs.fields(C).y
2018-03-03 14:09:05 +00:00
True
2021-12-25 14:15:10 +00:00
.. function :: attr.fields_dict
Same as `attrs.fields_dict` .
2015-01-28 13:36:11 +00:00
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.has
2015-01-28 13:36:11 +00:00
For example:
.. doctest ::
>>> @attr.s
2022-03-21 09:35:44 +00:00
... class C:
2015-01-28 13:36:11 +00:00
... pass
>>> attr.has(C)
True
>>> attr.has(object)
False
2021-12-25 14:15:10 +00:00
.. function :: attr.has
Same as `attrs.has` .
2015-01-29 09:17:08 +00:00
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.resolve_types
2020-07-22 09:43:07 +00:00
For example:
.. doctest ::
>>> import typing
2021-12-25 14:15:10 +00:00
>>> @attrs.define
2020-07-22 09:43:07 +00:00
... class A:
... a: typing.List['A']
... b: 'B'
...
2021-12-25 14:15:10 +00:00
>>> @attrs.define
2020-07-22 09:43:07 +00:00
... class B:
... a: A
...
2021-12-25 14:15:10 +00:00
>>> attrs.fields(A).a.type
2020-07-22 09:43:07 +00:00
typing.List[ForwardRef('A')]
2021-12-25 14:15:10 +00:00
>>> attrs.fields(A).b.type
2020-07-22 09:43:07 +00:00
'B'
2021-12-25 14:15:10 +00:00
>>> attrs.resolve_types(A, globals(), locals())
2020-07-22 09:43:07 +00:00
<class 'A'>
2021-12-25 14:15:10 +00:00
>>> attrs.fields(A).a.type
2020-07-22 09:43:07 +00:00
typing.List[A]
2021-12-25 14:15:10 +00:00
>>> attrs.fields(A).b.type
2020-07-22 09:43:07 +00:00
<class 'B'>
2021-12-25 14:15:10 +00:00
.. function :: attr.resolve_types
Same as `attrs.resolve_types` .
.. autofunction :: attrs.asdict
2020-07-22 10:19:58 +00:00
For example:
.. doctest ::
2021-12-25 14:15:10 +00:00
>>> @attrs.define
... class C:
... x: int
... y: int
>>> attrs.asdict(C(1, C(2, 3)))
2020-07-22 10:19:58 +00:00
{'x': 1, 'y': {'x': 2, 'y': 3}}
2021-12-25 14:15:10 +00:00
.. autofunction :: attr.asdict
2020-07-22 10:19:58 +00:00
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.astuple
2020-07-22 10:19:58 +00:00
For example:
.. doctest ::
2021-12-25 14:15:10 +00:00
>>> @attrs.define
... class C:
... x = attr.field()
... y = attr.field()
>>> attrs.astuple(C(1,2))
2020-07-22 10:19:58 +00:00
(1, 2)
2021-12-25 14:15:10 +00:00
.. autofunction :: attr.astuple
`` attrs `` includes some handy helpers for filtering the attributes in `attrs.asdict` and `attrs.astuple` :
.. autofunction :: attrs.filters.include
.. autofunction :: attrs.filters.exclude
.. function :: attr.filters.include
Same as `attrs.filters.include` .
.. function :: attr.filters.exclude
2015-02-20 15:34:21 +00:00
2021-12-25 14:15:10 +00:00
Same as `attrs.filters.exclude` .
2015-02-20 15:34:21 +00:00
2021-12-25 14:15:10 +00:00
See :func: `attrs.asdict` for examples.
2015-02-20 15:34:21 +00:00
2021-12-25 14:15:10 +00:00
All objects from `` attrs.filters `` are also available from `` attr.filters `` .
2015-02-20 15:34:21 +00:00
2021-12-25 14:15:10 +00:00
----
.. autofunction :: attrs.evolve
2017-01-21 16:11:45 +00:00
2017-05-22 23:23:18 +00:00
For example:
2017-01-21 16:11:45 +00:00
.. doctest ::
2021-12-25 14:15:10 +00:00
>>> @attrs.define
... class C:
... x: int
... y: int
2017-01-21 16:11:45 +00:00
>>> i1 = C(1, 2)
>>> i1
C(x=1, y=2)
2021-12-25 14:15:10 +00:00
>>> i2 = attrs.evolve(i1, y=3)
2017-01-21 16:11:45 +00:00
>>> i2
C(x=1, y=3)
>>> i1 == i2
False
2017-05-22 23:23:18 +00:00
`` evolve `` creates a new instance using `` __init__ `` .
This fact has several implications:
2017-05-04 11:20:39 +00:00
2017-05-22 23:23:18 +00:00
* private attributes should be specified without the leading underscore, just like in `` __init__ `` .
* attributes with `` init=False `` can't be set with `` evolve `` .
* the usual `` __init__ `` validators will validate the new values.
2017-05-04 11:20:39 +00:00
2021-12-25 14:15:10 +00:00
.. function :: attr.evolve
Same as `attrs.evolve` .
.. autofunction :: attrs.validate
2015-02-02 11:13:11 +00:00
For example:
.. doctest ::
2021-12-25 14:15:10 +00:00
>>> @attrs.define(on_setattr=attrs.setters.NO_OP)
... class C:
... x = attrs.field(validator=attrs.validators.instance_of(int))
2015-02-02 11:13:11 +00:00
>>> i = C(1)
>>> i.x = "1"
2021-12-25 14:15:10 +00:00
>>> attrs.validate(i)
2015-02-02 11:13:11 +00:00
Traceback (most recent call last):
...
2019-09-22 13:07:19 +00:00
TypeError: ("'x' must be <class 'int'> (got '1' that is a <class 'str'>).", ...)
2015-02-02 11:13:11 +00:00
2021-12-25 14:15:10 +00:00
.. function :: attr.validate
Same as `attrs.validate` .
2015-02-02 11:13:11 +00:00
2015-02-20 10:30:46 +00:00
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:
.. autofunction :: set_run_validators
.. autofunction :: get_run_validators
2015-01-29 11:20:17 +00:00
.. _api_validators:
Validators
----------
2021-12-25 14:15:10 +00:00
`` attrs `` comes with some common validators in the `` attrs.validators `` module.
2022-01-21 06:22:58 +00:00
All objects from `` attrs.validators `` are also available from `` attr.validators `` .
2015-01-29 11:20:17 +00:00
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.validators.lt
2021-09-24 10:47:19 +00:00
For example:
.. doctest ::
2021-12-25 14:15:10 +00:00
>>> @attrs.define
... class C:
... x = attrs.field(validator=attrs.validators.lt(42))
2021-09-24 10:47:19 +00:00
>>> C(41)
C(x=41)
>>> C(42)
Traceback (most recent call last):
...
ValueError: ("'x' must be < 42: 42")
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.validators.le
2021-09-24 10:47:19 +00:00
For example:
.. doctest ::
2021-12-25 14:15:10 +00:00
>>> @attrs.define
2022-03-21 09:35:44 +00:00
... class C:
2021-12-25 14:15:10 +00:00
... x = attrs.field(validator=attr.validators.le(42))
2021-09-24 10:47:19 +00:00
>>> C(42)
C(x=42)
>>> C(43)
Traceback (most recent call last):
...
ValueError: ("'x' must be <= 42: 43")
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.validators.ge
2021-09-24 10:47:19 +00:00
For example:
.. doctest ::
2021-12-25 14:15:10 +00:00
>>> @attrs.define
... class C:
... x = attrs.field(validator=attrs.validators.ge(42))
2021-09-24 10:47:19 +00:00
>>> C(42)
C(x=42)
>>> C(41)
Traceback (most recent call last):
...
ValueError: ("'x' must be => 42: 41")
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.validators.gt
2021-09-24 10:47:19 +00:00
For example:
.. doctest ::
2021-12-25 14:15:10 +00:00
>>> @attrs.define
... class C:
... x = attr.field(validator=attrs.validators.gt(42))
2021-09-24 10:47:19 +00:00
>>> C(43)
C(x=43)
>>> C(42)
Traceback (most recent call last):
...
ValueError: ("'x' must be > 42: 42")
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.validators.max_len
2021-09-24 10:47:19 +00:00
For example:
.. doctest ::
2021-12-25 14:15:10 +00:00
>>> @attrs.define
... class C:
... x = attrs.field(validator=attrs.validators.max_len(4))
2021-09-24 10:47:19 +00:00
>>> C("spam")
C(x='spam')
>>> C("bacon")
Traceback (most recent call last):
...
ValueError: ("Length of 'x' must be <= 4: 5")
2022-02-02 09:10:33 +00:00
.. autofunction :: attrs.validators.min_len
For example:
.. doctest ::
>>> @attrs.define
... class C:
... x = attrs.field(validator=attrs.validators.min_len(1))
>>> C("bacon")
C(x='bacon')
>>> C("")
Traceback (most recent call last):
...
ValueError: ("Length of 'x' must be => 1: 0")
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.validators.instance_of
2015-01-28 13:36:11 +00:00
2015-01-29 11:20:17 +00:00
For example:
.. doctest ::
2021-12-25 14:15:10 +00:00
>>> @attrs.define
... class C:
... x = attrs.field(validator=attrs.validators.instance_of(int))
2015-01-29 11:20:17 +00:00
>>> C(42)
C(x=42)
>>> C("42")
Traceback (most recent call last):
...
2018-08-11 04:40:01 +00:00
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=None, kw_only=False), <type 'int'>, '42')
2015-07-09 23:14:32 +00:00
>>> C(None)
Traceback (most recent call last):
...
2018-08-11 04:40:01 +00:00
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=None, init=True, type=None, kw_only=False), <type 'int'>, None)
2015-01-29 18:04:23 +00:00
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.validators.in_
2017-05-16 08:36:42 +00:00
For example:
.. doctest ::
2022-06-13 06:33:23 +00:00
>>> import enum
>>> class State(enum.Enum):
... ON = "on"
... OFF = "off"
>>> @attrs.define
... class C:
... state = attrs.field(validator=attrs.validators.in_(State))
... val = attrs.field(validator=attrs.validators.in_([1, 2, 3]))
>>> C(State.ON, 1)
C(state=<State.ON: 'on'>, val=1)
>>> C("on", 1)
Traceback (most recent call last):
...
ValueError: 'state' must be in <enum 'State'> (got 'on'), Attribute(name='state', default=NOTHING, validator=<in_ validator with options <enum 'State'>>, repr=True, eq=True, eq_key=None, order=True, order_key=None, hash=None, init=True, metadata=mappingproxy({}), type=None, converter=None, kw_only=False, inherited=False, on_setattr=None), <enum 'State'>, 'on')
>>> C(State.ON, 4)
Traceback (most recent call last):
...
ValueError: 'val' must be in [1, 2, 3] (got 4), Attribute(name='val', default=NOTHING, validator=<in_ validator with options [1, 2, 3]>, repr=True, eq=True, eq_key=None, order=True, order_key=None, hash=None, init=True, metadata=mappingproxy({}), type=None, converter=None, kw_only=False, inherited=False, on_setattr=None), [1, 2, 3], 4)
2017-05-16 08:36:42 +00:00
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.validators.provides
2017-05-16 08:36:42 +00:00
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.validators.and_
2017-05-12 21:02:07 +00:00
2021-12-25 14:15:10 +00:00
For convenience, it's also possible to pass a list to `attrs.field` 's validator argument.
2017-05-12 21:02:07 +00:00
Thus the following two statements are equivalent::
2021-12-25 14:15:10 +00:00
x = attrs.field(validator=attrs.validators.and_(v1, v2, v3))
x = attrs.field(validator=[v1, v2, v3])
2015-01-29 18:04:23 +00:00
2022-09-04 11:55:02 +00:00
.. autofunction :: attrs.validators.not_
For example:
.. doctest ::
>>> reserved_names = {"id", "time", "source"}
>>> @attrs.define
... class Measurement:
... tags = attrs.field(
... validator=attrs.validators.deep_mapping(
... key_validator=attrs.validators.not_(
... attrs.validators.in_(reserved_names),
... msg="reserved tag key",
... ),
... value_validator=attrs.validators.instance_of((str, int)),
... )
... )
>>> Measurement(tags={"source": "universe"})
Traceback (most recent call last):
...
ValueError: ("reserved tag key", Attribute(name='tags', default=NOTHING, validator=<not_ validator wrapping <in_ validator with options {'id', 'time', 'source'}>, capturing (<class 'ValueError'>, <class 'TypeError'>)>, type=None, kw_only=False), <in_ validator with options {'id', 'time', 'source'}>, {'source_': 'universe'}, (<class 'ValueError'>, <class 'TypeError'>))
>>> Measurement(tags={"source_": "universe"})
Measurement(tags={'source_': 'universe'})
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.validators.optional
2015-07-09 23:14:32 +00:00
For example:
.. doctest ::
2021-12-25 14:15:10 +00:00
>>> @attrs.define
... class C:
... x = attrs.field(validator=attrs.validators.optional(attr.validators.instance_of(int)))
2015-07-09 23:14:32 +00:00
>>> C(42)
C(x=42)
>>> C("42")
Traceback (most recent call last):
...
2018-08-11 04:40:01 +00:00
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=None, kw_only=False), <type 'int'>, '42')
2015-07-09 23:14:32 +00:00
>>> C(None)
C(x=None)
2016-08-16 10:18:03 +00:00
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.validators.is_callable
2018-11-08 03:33:52 +00:00
For example:
.. doctest ::
2021-12-25 14:15:10 +00:00
>>> @attrs.define
... class C:
... x = attrs.field(validator=attrs.validators.is_callable())
2018-11-08 03:33:52 +00:00
>>> C(isinstance)
C(x=<built-in function isinstance>)
>>> C("not a callable")
Traceback (most recent call last):
...
2019-07-20 09:55:26 +00:00
attr.exceptions.NotCallableError: 'x' must be callable (got 'not a callable' that is a <class 'str'>).
2018-11-08 03:33:52 +00:00
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.validators.matches_re
2019-09-09 08:48:52 +00:00
For example:
.. doctest ::
2021-12-25 14:15:10 +00:00
>>> @attrs.define
... class User:
... email = attrs.field(validator=attrs.validators.matches_re(
2019-09-09 08:48:52 +00:00
... "(^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$)"))
>>> User(email="user@example.com")
User(email='user@example.com')
>>> User(email="user@example.com@test.com")
Traceback (most recent call last):
...
ValueError: ("'email' must match regex '(^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\\\.[a-zA-Z0-9-.]+$)' ('user@example.com@test.com' doesn't)", Attribute(name='email', default=NOTHING, validator=<matches_re validator for pattern re.compile('(^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\.[a-zA-Z0-9-.]+$)')>, repr=True, cmp=True, hash=None, init=True, metadata=mappingproxy({}), type=None, converter=None, kw_only=False), re.compile('(^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\.[a-zA-Z0-9-.]+$)'), 'user@example.com@test.com')
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.validators.deep_iterable
2018-11-08 03:33:52 +00:00
For example:
.. doctest ::
2021-12-25 14:15:10 +00:00
>>> @attrs.define
... class C:
... x = attrs.field(validator=attrs.validators.deep_iterable(
... member_validator=attrs.validators.instance_of(int),
... iterable_validator=attrs.validators.instance_of(list)
2018-11-08 03:33:52 +00:00
... ))
>>> C(x=[1, 2, 3])
C(x=[1, 2, 3])
>>> C(x=set([1, 2, 3]))
Traceback (most recent call last):
...
TypeError: ("'x' must be <class 'list'> (got {1, 2, 3} that is a <class 'set'>).", Attribute(name='x', default=NOTHING, validator=<deep_iterable validator for <instance_of validator for type <class 'list'>> iterables of <instance_of validator for type <class 'int'>>>, repr=True, cmp=True, hash=None, init=True, metadata=mappingproxy({}), type=None, converter=None, kw_only=False), <class 'list'>, {1, 2, 3})
>>> C(x=[1, 2, "3"])
Traceback (most recent call last):
...
TypeError: ("'x' must be <class 'int'> (got '3' that is a <class 'str'>).", Attribute(name='x', default=NOTHING, validator=<deep_iterable validator for <instance_of validator for type <class 'list'>> iterables of <instance_of validator for type <class 'int'>>>, repr=True, cmp=True, hash=None, init=True, metadata=mappingproxy({}), type=None, converter=None, kw_only=False), <class 'int'>, '3')
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.validators.deep_mapping
2018-11-08 03:33:52 +00:00
For example:
.. doctest ::
2021-12-25 14:15:10 +00:00
>>> @attrs.define
... class C:
... x = attrs.field(validator=attrs.validators.deep_mapping(
... key_validator=attrs.validators.instance_of(str),
... value_validator=attrs.validators.instance_of(int),
... mapping_validator=attrs.validators.instance_of(dict)
2018-11-08 03:33:52 +00:00
... ))
>>> C(x={"a": 1, "b": 2})
C(x={'a': 1, 'b': 2})
>>> C(x=None)
Traceback (most recent call last):
...
TypeError: ("'x' must be <class 'dict'> (got None that is a <class 'NoneType'>).", Attribute(name='x', default=NOTHING, validator=<deep_mapping validator for objects mapping <instance_of validator for type <class 'str'>> to <instance_of validator for type <class 'int'>>>, repr=True, cmp=True, hash=None, init=True, metadata=mappingproxy({}), type=None, converter=None, kw_only=False), <class 'dict'>, None)
>>> C(x={"a": 1.0, "b": 2})
Traceback (most recent call last):
...
TypeError: ("'x' must be <class 'int'> (got 1.0 that is a <class 'float'>).", Attribute(name='x', default=NOTHING, validator=<deep_mapping validator for objects mapping <instance_of validator for type <class 'str'>> to <instance_of validator for type <class 'int'>>>, repr=True, cmp=True, hash=None, init=True, metadata=mappingproxy({}), type=None, converter=None, kw_only=False), <class 'int'>, 1.0)
>>> C(x={"a": 1, 7: 2})
Traceback (most recent call last):
...
TypeError: ("'x' must be <class 'str'> (got 7 that is a <class 'int'>).", Attribute(name='x', default=NOTHING, validator=<deep_mapping validator for objects mapping <instance_of validator for type <class 'str'>> to <instance_of validator for type <class 'int'>>>, repr=True, cmp=True, hash=None, init=True, metadata=mappingproxy({}), type=None, converter=None, kw_only=False), <class 'str'>, 7)
2021-11-17 06:05:01 +00:00
Validators can be both globally and locally disabled:
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.validators.set_disabled
2021-11-17 06:05:01 +00:00
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.validators.get_disabled
2021-11-17 06:05:01 +00:00
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.validators.disabled
2021-11-17 06:05:01 +00:00
2018-11-08 03:33:52 +00:00
2017-05-10 13:37:50 +00:00
Converters
----------
2021-12-25 14:15:10 +00:00
All objects from `` attrs.converters `` are also available from `` attr.converters `` .
.. autofunction :: attrs.converters.pipe
2020-03-05 10:54:44 +00:00
For convenience, it's also possible to pass a list to `attr.ib` 's converter argument.
Thus the following two statements are equivalent::
2020-07-21 12:43:09 +00:00
x = attr.ib(converter=attr.converter.pipe(c1, c2, c3))
2020-03-05 10:54:44 +00:00
x = attr.ib(converter=[c1, c2, c3])
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.converters.optional
2017-05-10 13:37:50 +00:00
For example:
.. doctest ::
>>> @attr.s
2022-03-21 09:35:44 +00:00
... class C:
2017-12-23 07:46:10 +00:00
... x = attr.ib(converter=attr.converters.optional(int))
2017-05-10 13:37:50 +00:00
>>> C(None)
C(x=None)
>>> C(42)
C(x=42)
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.converters.default_if_none
2018-07-28 15:03:41 +00:00
For example:
.. doctest ::
>>> @attr.s
2022-03-21 09:35:44 +00:00
... class C:
2018-07-28 15:03:41 +00:00
... x = attr.ib(
... converter=attr.converters.default_if_none("")
... )
>>> C(None)
C(x='')
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.converters.to_bool
2021-08-10 05:45:28 +00:00
For example:
.. doctest ::
>>> @attr.s
2022-03-21 09:35:44 +00:00
... class C:
2021-08-10 05:45:28 +00:00
... x = attr.ib(
... converter=attr.converters.to_bool
... )
>>> C("yes")
C(x=True)
>>> C(0)
C(x=False)
>>> C("foo")
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: Cannot convert value to bool: foo
2020-07-20 10:43:10 +00:00
.. _api_setters:
Setters
-------
2021-12-25 14:15:10 +00:00
These are helpers that you can use together with `attrs.define` 's and `attrs.fields` 's `` on_setattr `` arguments.
All setters in `` attrs.setters `` are also available from `` attr.setters `` .
2020-07-20 10:43:10 +00:00
2021-12-25 14:15:10 +00:00
.. autofunction :: attrs.setters.frozen
.. autofunction :: attrs.setters.validate
.. autofunction :: attrs.setters.convert
.. autofunction :: attrs.setters.pipe
2022-02-02 07:21:53 +00:00
.. data :: attrs.setters.NO_OP
Sentinel for disabling class-wide *on_setattr* hooks for certain attributes.
Does not work in `attrs.setters.pipe` or within lists.
.. versionadded :: 20.1.0
2020-07-20 10:43:10 +00:00
For example, only `` x `` is frozen here:
.. doctest ::
2021-12-25 14:15:10 +00:00
>>> @attrs.define(on_setattr=attr.setters.frozen)
... class C:
... x = attr.field()
... y = attr.field(on_setattr=attr.setters.NO_OP)
2020-07-20 10:43:10 +00:00
>>> c = C(1, 2)
>>> c.y = 3
>>> c.y
3
>>> c.x = 4
Traceback (most recent call last):
...
2021-12-25 14:15:10 +00:00
attrs.exceptions.FrozenAttributeError: ()
2020-08-20 17:01:34 +00:00
2021-12-25 14:15:10 +00:00
N.B. Please use `attrs.define` 's *frozen* argument (or `attrs.frozen` ) to freeze whole classes; it is more efficient.
2020-08-20 17:01:34 +00:00
2020-08-17 14:22:33 +00:00
2016-08-16 10:18:03 +00:00
Deprecated APIs
---------------
2019-10-01 14:06:36 +00:00
.. _version-info:
To help you write backward compatible code that doesn't throw warnings on modern releases, the `` attr `` module has an `` __version_info__ `` attribute as of version 19.2.0.
It behaves similarly to `sys.version_info` and is an instance of `VersionInfo` :
.. autoclass :: VersionInfo
With its help you can write code like this:
>>> if getattr(attr, "__version_info__", (0,)) >= (19, 2):
... cmp_off = {"eq": False}
... else:
... cmp_off = {"cmp": False}
>>> cmp_off == {"eq": False}
True
>>> @attr.s(**cmp_off)
2022-03-21 09:35:44 +00:00
... class C:
2019-10-01 14:06:36 +00:00
... pass
----
2022-07-28 07:23:44 +00:00
The serious-business aliases used to be called `` attr.attributes `` and `` attr.attr `` .
2016-08-16 10:18:03 +00:00
There are no plans to remove them but they shouldn't be used in new code.
2017-02-03 10:03:16 +00:00
.. autofunction :: assoc