06 May 08:32

hynek

b22195e

21.1.0

I am extremely excited to announce the release of attrs 21.1.0.

attrs is the direct ancestor of – and the inspiration for – dataclasses in the standard library and remains the more powerful option for creating regular classes without getting bogged down with writing identical boilerplate again and again: https://www.attrs.org/

Heartfelt thanks go to my generous GitHub sponsors, companies subscribing to attrs on Tidelift, and people who bought me a coffee on Ko-fi! Support like that makes me work on FOSS on a Saturday afternoon – especially when a release drags itself like this one! <3

While this release took a bit longer than I wished for, it comes with many exciting changes. The highlights alone are longer than a usual changelog:

The next-generation APIs (@attr.define, @attr.mutable, @attr.frozen, @attr.field) are deemed stable now. The old ones aren't going anywhere, but I encourage you to check the new ones out – they're much nicer!
pyright and pylance support: Eric Traut of Microsoft was kind enough to involve me in their work on the dataclass_transforms spec.

As a result, Microsoft's type checker pyright will work with this attrs release, and so will their Python language server pylance which should be exciting to VS Code users.

Currently it only supports a subset of attrs's features, but it's the most important ones and more will most likely follow. Some of the limitations are documented in our documentation on type annotations.
Customization of field comparison. This is something especially NumPy users have been asking for for a long time: you can now fully customize how a field is compared. We also ship a helper to avoid boilerplate code. So if you'd like to have an object with a NumPy array that compares correctly, this is the way:
```
import attr
import numpy

@attr.define
class C:
    an_array = attr.field(eq=attr.cmp_using(eq=numpy.array_equal))
```
Check out the new documentation on comparison for details.
To make it more ergonomic, I've decided to un-deprecate the cmp argument again, so you can customize eq and order in one go. Sorry about the trouble! The cmp attribute remains deprecated.
New powerful __init__ helpers:
1. If attrs deduces you don't want it to write a __init__ for you, it will create an __attrs_init__ instead that you can call from your custom __init__.
2. If attrs finds a __attrs_pre_init__, it will call it without any arguments before doing any initializations. This is really only useful if you want to run super().__init__(), but that's a use-case people have asked for for years!
See Hooking Yourself Into Initialization for details.
In preparation for the (rescinded) plan to make from __future__ import annotations the default in Python 3.10, attr.resolve_types() can now also be used to resolve types inside of field_transformers.

A Look Ahead

For the next release we've got even bigger plans! By stabilizing the next-generation APIs we can finally go the last step, I've been talking for years (yeah, sorry): import attrs.

attrs's playful APIs (@attr.s, @attr.ib) lost a bit of their charm as the scope of the package grew – especially after the introduction of type annotations.

While the old APIs aren't going anywhere, in the next feature release there will be additionally an attrs package that you can use as an alternative to attr. No more attr.Factory!

The new package gives us the opportunity to rethink the defaults of some functions. So if you have any pet peeves, please air them on #487.

Full Changelog

Deprecations

The long-awaited, much-talked-about, little-delivered import attrs is finally upon us!

Since the NG APIs have now been proclaimed stable, the next release of attrs will allow you to actually import attrs. We're taking this opportunity to replace some defaults in our APIs that made sense in 2015, but don't in 2021.

So please, if you have any pet peeves about defaults in attrs's APIs, now is the time to air your grievances in #487! We're not gonna get such a chance for a second time, without breaking our backward-compatibility guarantees, or long deprecation cycles. Therefore, speak now or forever hold you peace! #487
The cmp argument to attr.s() and attr.ib() has been undeprecated It will continue to be supported as syntactic sugar to set eq and order in one go.

I'm terribly sorry for the hassle around this argument! The reason we're bringing it back is it's usefulness regarding customization of equality/ordering.

The cmp attribute and argument on attr.Attribute remains deprecated and will be removed later this year. #773

Changes

It's now possible to customize the behavior of eq and order by passing in a callable. #435, #627
The instant favorite next-generation APIs are not provisional anymore!

They are also officially supported by Mypy as of their 0.800 release.

We hope the next release will already contain an (additional) importable package called attrs. #668, #786
If an attribute defines a converter, the type of its parameter is used as type annotation for its corresponding __init__ parameter.

If an attr.converters.pipe is used, the first one's is used. #710
Fixed the creation of an extra slot for an attr.ib when the parent class already has a slot with the same name. #718
__attrs__init__() will now be injected if init=False, or if auto_detect=True and a user-defined __init__() exists.

This enables users to do "pre-init" work in their __init__() (such as super().__init__()).

__init__() can then delegate constructor argument processing to self.__attrs_init__(*args, **kwargs). #731
bool(attr.NOTHING) is now False. #732
It's now possible to use super() inside of properties of slotted classes. #747
Allow for a __attrs_pre_init__() method that -- if defined -- will get called at the beginning of the attrs-generated __init__() method. #750
Added forgotten attr.Attribute.evolve() to type stubs. #752
attrs.evolve() now works recursively with nested attrs classes. #759
Python 3.10 is now officially supported. #763
attr.resolve_types() now takes an optional attrib argument to work inside a field_transformer. #774
ClassVars are now also detected if they come from typing-extensions. #782
To make it easier to customize attribute comparison (#435), we have added the attr.cmp_with() helper.

See the new docs on comparison for more details. #787
Added provisional support for static typing in pyright via the dataclass_transforms specification. Both the pyright specification and attrs implementation may change in future versions of both projects.

Your constructive feedback is welcome in both attrs#795 and pyright#1782. #796

Assets 2

05 Nov 10:11

hynek

20.3.0

f3762ba

20.3.0

Backward-incompatible Changes

attr.define(), attr.frozen(), attr.mutable(), and attr.field() remain provisional.

This release does not change change anything about them and they are already used widely in production though.

If you wish to use them together with mypy, you can simply drop this plugin into your project.

Feel free to provide feedback to them in the linked issue #668.

We will release the attrs namespace once we have the feeling that the APIs have properly settled. #668

Changes

attr.s() now has a field_transformer hook that is called for all Attributes and returns a (modified or updated) list of Attribute instances. attr.asdict() has a value_serializer hook that can change the way values are converted. Both hooks are meant to help with data (de-)serialization workflows. #653
kw_only=True now works on Python 2. #700
raise from now works on frozen classes on PyPy. #703, #712
attr.asdict() and attr.astuple() now treat frozensets like sets with regards to the retain_collection_types argument. #704
The type stubs for attr.s() and attr.make_class() are not missing the collect_by_mro argument anymore. #711

Assets 2

05 Sep 10:37

hynek

20.2.0

4f74fba

20.2.0

Backward-incompatible Changes

attr.define(), attr.frozen(), attr.mutable(), and attr.field() remain provisional.

This release fixes a bunch of bugs and ergonomics but they remain mostly unchanged.

If you wish to use them together with mypy, you can simply drop this plugin into your project.

Feel free to provide feedback to them in the linked issue #668.

We will release the attrs namespace once we have the feeling that the APIs have properly settled. #668

Changes

attr.define() et al now correct detect __eq__ and __ne__. #671
attr.define() et al's hybrid behavior now also works correctly when arguments are passed. #675
It's possible to define custom __setattr__ methods on slotted classes again. #681
In 20.1.0 we introduced the inherited attribute on the attr.Attribute class to differentiate attributes that have been inherited and those that have been defined directly on the class.

It has shown to be problematic to involve that attribute when comparing instances of attr.Attribute though, because when sub-classing, attributes from base classes are suddenly not equal to themselves in a super class.

Therefore the inherited attribute will now be ignored when hashing and comparing instances of attr.Attribute. #684
zope.interface is now a "soft dependency" when running the test suite; if zope.interface is not installed when running the test suite, the interface-related tests will be automatically skipped. #685
The ergonomics of creating frozen classes using @define(frozen=True) and sub-classing frozen classes has been improved: you don't have to set on_setattr=None anymore. #687

Assets 2

20 Aug 17:40

hynek

20.1.0

90386b6

20.1.0

Backward-incompatible Changes

Python 3.4 is not supported anymore. It has been unsupported by the Python core team for a while now, its PyPI downloads are negligible, and our CI provider removed it as a supported option.

It's very unlikely that attrs will break under 3.4 anytime soon, which is why we do not block its installation on Python 3.4. But we don't test it anymore and will block it once someone reports breakage. #608

Deprecations

Less of a deprecation and more of a heads up: the next release of attrs will introduce an attrs namespace. That means that you'll finally be able to run import attrs with new functions that aren't cute abbreviations and that will carry better defaults.

This should not break any of your code, because project-local packages have priority before installed ones. If this is a problem for you for some reason, please report it to our bug tracker and we'll figure something out.

The old attr namespace isn't going anywhere and its defaults are not changing -- this is a purely additive measure. Please check out the linked issue for more details.

These new APIs have been added provisionally as part of #666 so you can try them out today and provide feedback. Learn more in the API docs. #408

Changes

Added attr.resolve_types(). It ensures that all forward-references and types in string form are resolved into concrete types.

You need this only if you need concrete types at runtime. That means that if you only use types for static type checking, you do not need this function. #288, #302
Added @attr.s(collect_by_mro=False) argument that if set to True fixes the collection of attributes from base classes.

It's only necessary for certain cases of multiple-inheritance but is kept off for now for backward-compatibility reasons. It will be turned on by default in the future.

As a side-effect, attr.Attribute now always has an inherited attribute indicating whether an attribute on a class was directly defined or inherited. #428, #635
On Python 3, all generated methods now have a docstring explaining that they have been created by attrs. #506
It is now possible to prevent attrs from auto-generating the __setstate__ and __getstate__ methods that are required for pickling of slotted classes.

Either pass @attr.s(getstate_setstate=False) or pass @attr.s(auto_detect=True) and implement them yourself: if attrs finds either of the two methods directly on the decorated class, it assumes implicitly getstate_setstate=False (and implements neither).

This option works with dict classes but should never be necessary. #512, #513, #642
Fixed a ValueError: Cell is empty bug that could happen in some rare edge cases. #590
attrs can now automatically detect your own implementations and infer init=False, repr=False, eq=False, order=False, and hash=False if you set @attr.s(auto_detect=True). attrs will ignore inherited methods. If the argument implies more than one method (e.g. eq=True creates both __eq__ and __ne__), it's enough for one of them to exist and attrs will create neither.

This feature requires Python 3. #607
Added attr.converters.pipe(). The feature allows combining multiple conversion callbacks into one by piping the value through all of them, and retuning the last result.

As part of this feature, we had to relax the type information for converter callables. #618
Fixed serialization behavior of non-slots classes with cache_hash=True. The hash cache will be cleared on operations which make "deep copies" of instances of classes with hash caching, though the cache will not be cleared with shallow copies like those made by copy.copy().

Previously, copy.deepcopy() or serialization and deserialization with pickle would result in an un-initialized object.

This change also allows the creation of cache_hash=True classes with a custom __setstate__, which was previously forbidden (#494). #620
It is now possible to specify hooks that are called whenever an attribute is set after a class has been instantiated.

You can pass on_setattr both to @attr.s() to set the default for all attributes on a class, and to @attr.ib() to overwrite it for individual attributes.

attrs also comes with a new module attr.setters that brings helpers that run validators, converters, or allow to freeze a subset of attributes. #645, #660
Provisional APIs called attr.define(), attr.mutable(), and attr.frozen() have been added.

They are only available on Python 3.6 and later, and call attr.s() with different default values.

If nothing comes up, they will become the official way for creating classes in 20.2.0 (see above).

Please note that it may take some time until mypy -- and other tools that have dedicated support for attrs -- recognize these new APIs. Please do not open issues on our bug tracker, there is nothing we can do about it. #666
We have also provisionally added attr.field() that supplants attr.ib(). It also requires at least Python 3.6 and is keyword-only. Other than that, it only dropped a few arguments, but changed no defaults.

As with attr.s(): attr.ib() is not going anywhere. #669