attrs

Warnings

• breaking @define enables slots=True by default. Slotted classes have no __dict__, so arbitrary attribute assignment (e.g. during monkeypatching or pickle with non-attrs base-class state) will raise AttributeError.
  Fix: Use @define(slots=False) when you need a __dict__, need to monkeypatch instances, or inherit from a non-slotted non-attrs base that stores state on self. When inheriting from a non-attrs base, the base class attributes are NOT captured by attrs-generated __getstate__/__setstate__, so round-tripping through pickle will silently drop them.
• breaking When using @define, converters run by default on setattr (on_setattr=[setters.convert, setters.validate]), not just at __init__ time. Code that relied on bypassing converter logic after construction will break silently or raise.
  Fix: Pass on_setattr=setters.validate (or on_setattr=None) to field() to restore the pre-21.3.0 behaviour, or restructure code so setattr is not used to set raw values.
• breaking kw_only=True on a class-level @define no longer forces kw_only on individual attributes that explicitly set kw_only=False (changed in 25.4.0). Subclasses with required positional args following a kw_only=False default field now raise a TypeError at class definition time.
  Fix: Audit any subclass hierarchy that mixes class-level kw_only=True with per-field kw_only=False and defaults. Add kw_only=True to the required subclass fields, or restructure argument ordering.
• gotcha Mutable defaults (list, dict, set) must not be passed as `default=<value>`. All instances will share the same object, causing cross-instance state mutation.
  Fix: Use field(factory=list) or Factory(list) instead of field(default=[]). attrs raises ValueError if you pass a plain list/dict/set as default to catch this, but custom mutable objects are not checked.
• gotcha Subclassing a @define class and adding a mandatory (no-default) attribute after a parent attribute that has a default raises ValueError at class definition time: 'No mandatory attributes allowed after an attribute with a default value or factory.'
  Fix: Mark mandatory subclass fields kw_only=True (field(kw_only=True)) so they don't conflict with positional argument ordering, or reorder parent class fields so defaulted fields come last.
• gotcha Slotted classes replace the original class object at decoration time. __init_subclass__ is therefore called twice for slotted subclasses (once for the original, once for the replacement), and metaclass features that depend on class identity can break silently.
  Fix: Use @define(slots=False) when combining attrs with metaclasses, __init_subclass__ hooks, or class registries that track the class object by identity.
• gotcha In frozen classes, you cannot assign to self in __attrs_post_init__ via normal attribute assignment — it raises FrozenInstanceError.
  Fix: Use object.__setattr__(self, 'attribute_name', value) inside __attrs_post_init__ when extra initialisation is needed on a frozen class.

Install

• pip install attrs pip

Imports

• define

  from attrs import define, field, Factory

  The modern `attrs` namespace (import attrs / from attrs import ...) was added in v21.3.0. The legacy `attr` namespace with @attr.s and attr.ib() still works but is the old API. `attrs.define` enables slots by default and runs converters on setattr; `attr.s` does not.
• frozen

  from attrs import frozen

  Use @frozen for immutable classes. Attempting to set attributes raises attrs.exceptions.FrozenInstanceError. To mutate a frozen instance, use attrs.evolve() to create a modified copy.
• asdict

  from attrs import asdict

  Both work, but attrs.asdict (from attrs import asdict, added v21.3.0) always retains collection types and uses dict as dict_factory, whereas attr.asdict has different defaults. Prefer the attrs namespace for new code.
• fields

  from attrs import fields

  Prefer attrs.fields(MyClass).attr_name over raw string names in filter callbacks. String names silently do nothing when mistyped; fields() raises AttributeError immediately.
• Factory

  from attrs import Factory
  some_field: list = field(factory=list)  # or Factory(list)

  Passing a mutable object as `default=` shares one instance across all class instances. Always use Factory(list) / field(factory=list) for mutable defaults.

Quickstart

Define a slotted, validated attrs class with a mutable-default field, a frozen variant, and serialisation.

from attrs import define, field, frozen, Factory, asdict, evolve, validators

# Modern API — slots=True by default, converters run on setattr
@define
class Point:
    x: float
    y: float
    tags: list[str] = field(factory=list)  # safe mutable default

    @x.validator
    def _positive_x(self, attribute, value):
        if value < 0:
            raise ValueError(f"x must be non-negative, got {value}")

p = Point(1.0, 2.0)
p.tags.append("origin-area")
print(p)           # Point(x=1.0, y=2.0, tags=['origin-area'])
print(asdict(p))   # {'x': 1.0, 'y': 2.0, 'tags': ['origin-area']}

# Frozen (immutable) class — use evolve() to get a modified copy
@frozen
class Config:
    host: str = "localhost"
    port: int = 8080

cfg = Config()
new_cfg = evolve(cfg, port=9090)
print(new_cfg)     # Config(host='localhost', port=9090)

# Nested serialisation
@define
class Server:
    config: Config
    name: str

srv = Server(config=cfg, name="primary")
print(asdict(srv))