Rodin
49 lines
3.0 KiB
Markdown
49 lines
3.0 KiB
Markdown
# 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
|