api-attr.rst (5268B)
1 API Reference for the ``attr`` Namespace 2 ======================================== 3 4 .. module:: attr 5 6 7 Core 8 ---- 9 10 .. 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, unsafe_hash=None) 11 12 .. note:: 13 14 *attrs* also comes with a serious-business alias ``attr.attrs``. 15 16 For example: 17 18 .. doctest:: 19 20 >>> import attr 21 >>> @attr.s 22 ... class C: 23 ... _private = attr.ib() 24 >>> C(private=42) 25 C(_private=42) 26 >>> class D: 27 ... def __init__(self, x): 28 ... self.x = x 29 >>> D(1) 30 <D object at ...> 31 >>> D = attr.s(these={"x": attr.ib()}, init=False)(D) 32 >>> D(1) 33 D(x=1) 34 >>> @attr.s(auto_exc=True) 35 ... class Error(Exception): 36 ... x = attr.ib() 37 ... y = attr.ib(default=42, init=False) 38 >>> Error("foo") 39 Error(x='foo', y=42) 40 >>> raise Error("foo") 41 Traceback (most recent call last): 42 ... 43 Error: ('foo', 42) 44 >>> raise ValueError("foo", 42) # for comparison 45 Traceback (most recent call last): 46 ... 47 ValueError: ('foo', 42) 48 49 50 .. autofunction:: attr.ib 51 52 .. note:: 53 54 *attrs* also comes with a serious-business alias ``attr.attrib``. 55 56 The object returned by `attr.ib` also allows for setting the default and the validator using decorators: 57 58 .. doctest:: 59 60 >>> @attr.s 61 ... class C: 62 ... x = attr.ib() 63 ... y = attr.ib() 64 ... @x.validator 65 ... def _any_name_except_a_name_of_an_attribute(self, attribute, value): 66 ... if value < 0: 67 ... raise ValueError("x must be positive") 68 ... @y.default 69 ... def _any_name_except_a_name_of_an_attribute(self): 70 ... return self.x + 1 71 >>> C(1) 72 C(x=1, y=2) 73 >>> C(-1) 74 Traceback (most recent call last): 75 ... 76 ValueError: x must be positive 77 78 79 .. function:: define 80 81 Same as `attrs.define`. 82 83 .. function:: mutable 84 85 Same as `attrs.mutable`. 86 87 .. function:: frozen 88 89 Same as `attrs.frozen`. 90 91 .. function:: field 92 93 Same as `attrs.field`. 94 95 .. class:: Attribute 96 97 Same as `attrs.Attribute`. 98 99 .. function:: make_class 100 101 Same as `attrs.make_class`. 102 103 .. autoclass:: Factory 104 :noindex: 105 106 Same as `attrs.Factory`. 107 108 109 .. data:: NOTHING 110 111 Same as `attrs.NOTHING`. 112 113 114 Exceptions 115 ---------- 116 117 .. module:: attr.exceptions 118 119 All exceptions are available from both ``attr.exceptions`` and `attrs.exceptions` (it's the same module in a different namespace). 120 121 Please refer to `attrs.exceptions` for details. 122 123 124 Helpers 125 ------- 126 127 .. currentmodule:: attr 128 129 .. function:: cmp_using 130 131 Same as `attrs.cmp_using`. 132 133 .. function:: fields 134 135 Same as `attrs.fields`. 136 137 .. function:: fields_dict 138 139 Same as `attr.fields_dict`. 140 141 .. function:: has 142 143 Same as `attrs.has`. 144 145 .. function:: resolve_types 146 147 Same as `attrs.resolve_types`. 148 149 .. autofunction:: asdict 150 .. autofunction:: astuple 151 152 .. module:: attr.filters 153 154 .. function:: include 155 156 Same as `attrs.filters.include`. 157 158 .. function:: exclude 159 160 Same as `attrs.filters.exclude`. 161 162 See :func:`attrs.asdict` for examples. 163 164 All objects from `attrs.filters` are also available in ``attr.filters``. 165 166 ---- 167 168 .. currentmodule:: attr 169 170 .. function:: evolve 171 172 Same as `attrs.evolve`. 173 174 .. function:: validate 175 176 Same as `attrs.validate`. 177 178 179 Validators 180 ---------- 181 182 .. module:: attr.validators 183 184 All objects from `attrs.validators` are also available in ``attr.validators``. 185 Please refer to the former for details. 186 187 188 Converters 189 ---------- 190 191 .. module:: attr.converters 192 193 All objects from `attrs.converters` are also available from ``attr.converters``. 194 Please refer to the former for details. 195 196 197 Setters 198 ------- 199 200 .. module:: attr.setters 201 202 All objects from `attrs.setters` are also available in ``attr.setters``. 203 Please refer to the former for details. 204 205 206 Deprecated APIs 207 --------------- 208 209 .. currentmodule:: attr 210 211 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. 212 It behaves similarly to `sys.version_info` and is an instance of `attr.VersionInfo`: 213 214 .. autoclass:: VersionInfo 215 216 With its help you can write code like this: 217 218 >>> if getattr(attr, "__version_info__", (0,)) >= (19, 2): 219 ... cmp_off = {"eq": False} 220 ... else: 221 ... cmp_off = {"cmp": False} 222 >>> cmp_off == {"eq": False} 223 True 224 >>> @attr.s(**cmp_off) 225 ... class C: 226 ... pass 227 228 229 ---- 230 231 .. autofunction:: assoc 232 233 Before *attrs* got `attrs.validators.set_disabled` and `attrs.validators.set_disabled`, it had the following APIs to globally enable and disable validators. 234 They won't be removed, but are discouraged to use: 235 236 .. autofunction:: set_run_validators 237 .. autofunction:: get_run_validators 238 239 ---- 240 241 The serious-business aliases used to be called ``attr.attributes`` and ``attr.attr``. 242 There are no plans to remove them but they shouldn't be used in new code.