| single |
======================================
attrs: 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.
.. teaser-end
For that, it gives you a class decorator and a way to declaratively define
the attributes on that class:
.. -code-begin-
.. code-block:: pycon
>>> import attr
>>> @attr.s
... class SomeClass(object):
... a_number = attr.ib(default=42)
... list_of_numbers = attr.ib(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
>>> attr.asdict(sc)
{'a_number': 1, 'list_of_numbers': [1, 2, 3]}
>>> SomeClass()
SomeClass(a_number=42, list_of_numbers=[])
>>> C = attr.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 complete set of comparison methods (equality and ordering),
- an initializer,
- and much more,
*without* writing dull boilerplate code again and again and *without*
runtime performance penalties.
On Python 3.6 and later, you can often even drop the calls to ``attr.ib()``
by using [type annotations].
This gives you the power to use actual classes with actual types in your
code instead of confusing tuple\ s or [confusingly behaving] namedtuple\ s.
Which in turn encourages you to write *small classes* that do [one thing
well].
Never again violate the [single responsibility principle] just because
implementing __init__ et al is a painful drag.
.. -getting-help-
Getting Help
============
Please use the ``python-attrs`` tag on [StackOverflow] to get help.
Answering questions of your fellow developers is also a great way to help
the project!
.. -project-information-
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!
|