attrs 21.3.0

Classes Without Boilerplate

attrs is the Python package that will bring back the joy of writing classes by relieving you from the drudgery of implementing object protocols (aka dunder methods). Trusted by NASA for Mars missions since 2020!

Its main goal is to help you to write concise and correct software without slowing down your code.

For that, it gives you a class decorator and a way to declaratively define the attributes on that class:

>>> from attrs import asdict, define, make_class, Factory

>>> @define
... class SomeClass:
...     a_number: int = 42
...     list_of_numbers: list[int] = Factory(list)
...
...     def hard_math(self, another_number):
...         return self.a_number + sum(self.list_of_numbers) * another_number


>>> sc = SomeClass(1, [1, 2, 3])
>>> sc
SomeClass(a_number=1, list_of_numbers=[1, 2, 3])

>>> sc.hard_math(3)
19
>>> sc == SomeClass(1, [1, 2, 3])
True
>>> sc != SomeClass(2, [3, 2, 1])
True

>>> asdict(sc)
{'a_number': 1, 'list_of_numbers': [1, 2, 3]}

>>> SomeClass()
SomeClass(a_number=42, list_of_numbers=[])

>>> C = make_class("C", ["a", "b"])
>>> C("foo", "bar")
C(a='foo', b='bar')

After declaring your attributes attrs gives you:

• a concise and explicit overview of the class’s attributes,

• a nice human-readable __repr__,

• a equality-checking methods,

• an initializer,

• and much more,

without writing dull boilerplate code again and again and without runtime performance penalties.

Hate type annotations!? No problem! Types are entirely optional with attrs. Simply assign attrs.field() to the attributes instead of annotating them with types.

---

This example uses attrs’s modern APIs that have been introduced in version 20.1.0, and the attrs package import name that has been added in version 21.3.0. The classic APIs (@attr.s, attr.ib, plus their serious business aliases) and the attr package import name will remain indefinitely.

Please check out On The Core API Names for a more in-depth explanation.

Data Classes

On the tin, attrs might remind you of dataclasses (and indeed, dataclasses are a descendant of attrs). In practice it does a lot more more and is more flexible. For instance it allows you to define special handling of NumPy arrays for equality checks, or allows more ways to plug into the initialization process.

For more details, please refer to our comparison page.

Getting Help

Please use the python-attrs tag on Stack Overflow to get help.

Answering questions of your fellow developers is also a great way to help the project!

Project Information

attrs is released under the MIT license, its documentation lives at Read the Docs, the code on GitHub, and the latest release on PyPI. It’s rigorously tested on Python 2.7, 3.5+, and PyPy.

We collect information on third-party extensions in our wiki. Feel free to browse and add your own!

If you’d like to contribute to attrs you’re most welcome and we’ve written a little guide to get you started!

attrs for Enterprise

Available as part of the Tidelift Subscription.

The maintainers of attrs and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use. Learn more.

Release Information

21.3.0 (2021-12-28)

Backward-incompatible Changes

• When using @define, converters are now run by default when setting an attribute on an instance – additionally to validators. I.e. the new default is on_setattr=[attrs.setters.convert, attrs.setters.validate].

  This is unfortunately a breaking change, but it was an oversight, impossible to raise a DeprecationWarning about, and it’s better to fix it now while the APIs are very fresh with few users. #835, #886

• import attrs has finally landed! As of this release, you can finally import attrs using its proper name.

  Not all names from the attr namespace have been transferred; most notably attr.s and attr.ib are missing. See attrs.define and attrs.field if you haven’t seen our next-generation APIs yet. A more elaborate explanation can be found On The Core API Names

  This feature is at least for one release provisional. We don’t plan on changing anything, but such a big change is unlikely to go perfectly on the first strike.

  The API docs have been mostly updated, but it will be an ongoing effort to change everything to the new APIs. Please note that we have not moved – or even removed – anything from attr!

  Please do report any bugs or documentation inconsistencies! #887

Changes

• attr.asdict(retain_collection_types=False) (default) dumps collection-esque keys as tuples. #646, #888

• __match_args__ are now generated to support Python 3.10’s Structural Pattern Matching. This can be controlled by the match_args argument to the class decorators on Python 3.10 and later. On older versions, it is never added and the argument is ignored. #815

• If the class-level on_setattr is set to attrs.setters.validate (default in @define and @mutable) but no field defines a validator, pretend that it’s not set. #817

• The generated __repr__ is significantly faster on Pythons with f-strings. #819

• Attributes transformed via field_transformer are wrapped with AttrsClass again. #824

• Generated source code is now cached more efficiently for identical classes. #828

• Added attrs.converters.to_bool(). #830

• attrs.resolve_types() now resolves types of subclasses after the parents are resolved. #842 #843

• Added new validators: lt(val) (< val), le(va) (≤ val), ge(val) (≥ val), gt(val) (> val), and maxlen(n). #845

• attrs classes are now fully compatible with cloudpickle (no need to disable repr anymore). #857

• Added new context manager attrs.validators.disabled() and functions attrs.validators.(set|get)_disabled(). They deprecate attrs.(set|get)_run_validators(). All functions are interoperable and modify the same internal state. They are not – and never were – thread-safe, though. #859

• attrs.validators.matches_re() now accepts pre-compiled regular expressions in addition to pattern strings. #877

Full changelog.

Credits

attrs is written and maintained by Hynek Schlawack.

The development is kindly supported by Variomedia AG.

A full list of contributors can be found in GitHub’s overview.

It’s the spiritual successor of characteristic and aspires to fix some of it clunkiness and unfortunate decisions. Both were inspired by Twisted’s FancyEqMixin but both are implemented using class decorators because subclassing is bad for you, m’kay?