# Attrs source notes

Repo: `python-attrs/attrs`
Local checkout: `/home/ubuntu/repos/rodin-sources/attrs`

## Why this repo is useful
- `attrs` is a strong source for explicit data-carrier design: generated methods, constructor-shape control, and deliberate conversion at boundaries.
- Its docs are especially valuable because they include caveats and failure cases, not just happy-path examples.

## Declarative fields are the default for data-heavy classes

### Repeated evidence
- `docs/examples.md:24-44` shows `@define` with typed fields immediately generating constructor, repr, and equality behavior.
- `docs/examples.md:31-44` makes the generated behavior visible at the REPL rather than implicit.
- `docs/examples.md:51-58` shows the same declarative shape without relying on type annotations, via `field()`.

### Why it matters
Repeated signal: when a class mostly carries data, `attrs` prefers declaring fields and letting the library generate the boilerplate. The code emphasizes structure and invariants over handwritten dunder noise.

### Caveat / counterexample
`docs/examples.md:60-62` warns that mixing `field()` declarations without annotations flips `attrs` into a no-typing mode and can ignore annotation-only attributes. That is a sharp edge worth preserving in synthesis: declarative does not mean "mix styles freely."

## Keyword-only fields are used to protect call-site clarity and inheritance

### Repeated evidence
- `docs/examples.md:147-157` shows `field(kw_only=True)` forcing explicit construction at the call site.
- `docs/examples.md:159-172` shows decorator-level `@define(kw_only=True)` applying the same rule to the whole class.
- `docs/examples.md:176-191` shows the practical inheritance payoff: subclasses can add required fields even when the base class already has defaults.
- `docs/examples.md:193-205` shows the counterexample when `kw_only=True` is omitted: invalid attribute ordering raises a `ValueError`.

### Why it matters
Repeated signal: keyword-only fields are not just cosmetic. They are a tool for making constructor calls self-describing and for avoiding inheritance-order traps.

## Serialization is explicit and filterable

### Repeated evidence
- `docs/examples.md:211-217` shows `asdict(...)` as a deliberate conversion step from object to plain data.
- `docs/examples.md:219-235` shows `asdict(..., filter=...)` excluding sensitive fields like passwords.
- `docs/examples.md:238-253` shows built-in include/exclude helpers for more reusable serialization control.

### Why it matters
Repeated signal: even value-like objects are not assumed to be wire-ready. `attrs` makes the serialization boundary explicit and gives callers hooks to shape what crosses it.

## Pattern candidates supported by this repo
- use declarative field definitions for data-carrier classes
- prefer keyword-only construction when call-site clarity or inheritance safety matters
- keep serialization as an explicit step
- preserve caveats about mixed declaration styles and constructor ordering