attributes: @attr decorator sugar over the getter/setter constructors

[coretl]

Closes #397

An attribute can now be declared by decorating the method that reads it, with @x.setter for the writer half - the PyTango hello-world, written over the getter=/setter= constructors from #392 rather than beside them.

class PowerSupply(Controller):
    @attr(Polled(period=0.5), units="V")
    async def voltage(self) -> float:  # pyright: ignore[reportRedeclaration]
        """Output voltage."""
        return float(await self._conn.query("V?"))

    @voltage.setter
    async def voltage(self, value: float) -> None:
        await self._conn.send(f"V={value}")

Scope

• @attr is a decorator only, in two forms: bare @attr and parameterised @attr(Polled(period=0.5), units="V"). Getter only builds an AttrR; getter + @x.setter builds an AttrRW. There is no @attr_r/@attr_rw, no free-function attr() factory, and no write-only decorator - AttrW(setter=…) stays longhand.
• The datatype is the getter's return annotation, unwrapping Update[T], and supports the Array1D/Table spellings. Not annotating it fails at decoration with a message naming the getter.
• The getter's docstring becomes the description - its first paragraph, as one line. An explicit description= wins.
• Decorator keyword arguments are the attribute's metadata, typed Unpack[Meta] (the superset, since the datatype is not known until the getter is read) and runtime-validated against the datatype by the constructor, so @attr(precision=3) on a -> str getter raises naming the field, datatype and attribute.
• The optional leading positional is a schedule - the same Polled/NotPolled objects the procedural form wraps its getter in, per ADR 0018's table. A bare @attr is read once at connect, exactly as a bare getter= is.
• Binding follows @command/@scan: the class body holds an UnboundAttr declaration, and BaseController._bind_attrs builds a fresh AttrR/AttrRW per instance with the getter and setter bound to it. Nothing is deepcopied from a class-scope prototype, so two controllers never share an attribute or write to each other's device.
• Name clashes already raise: a decorated attribute is added during __init__, so a later self.voltage = AttrR(...) hits the existing _check_for_name_clash. A matching voltage: AttrR[float] hint is validated against the decorated attribute by the existing hinted-attribute check.
• New docs/how-to/fastcs-for-pytango-users.md, pairing each spelling with its PyTango equivalent and saying when to reach for @attr rather than the constructor or (when it lands, ControllerFiller — declarative/procedural split #394) the filler.

Instructions to reviewer on how to test:

1. uv run pytest tests/test_attr_decorator.py -v
2. Write a two-attribute controller with @attr, serve it over EPICS CA, and confirm the PVs carry the docstring as DESC and the decorator's units/precision.

Checks for reviewer

• Would the PR title make sense to a user on a set of release notes
• A read-write @attr needs # pyright: ignore[reportRedeclaration] on the getter. This is the one wart, and it is inherent to the @x.setter spelling rather than to this implementation: type checkers special-case the builtin property and nothing else, so two def voltage in one class body is an error (pyright: obscured by a declaration of the same name; mypy: already defined). I measured the alternatives before choosing:
  • As implemented - UnboundAttr is a plain non-data descriptor whose __get__ is typed to return AttrR[T], and UnboundAttrRW's returns AttrRW[T]. self.voltage.set(...), .readback, .setpoint and the datatype all check correctly at every use site; the cost is one suppression comment per read-write declaration, which the docs page spells out.
  • Deriving UnboundAttr from property silences the diagnostic completely - but pyright then evaluates the whole pair through its property path, and c.voltage comes out as AttrR[Unknown]: .set() is unknown and even the datatype is lost. That trades one comment at the declaration for a cast at every use, which is why I did not take it.
    I have kept the ADR's spelling; say if you would rather have the property derivation, or a different spelling that avoids the collision (@voltage.writer on a differently-named method), and it is a small commit either way.
• @attr(Polled(period=0.5)), not Polled(0.5). ADR 0018 writes the shorthand Polled(0.5), but Polled's first positional is its getter and period is keyword-only (Polled(protocol.get_temperature, period=0.2) is the procedural form throughout the demo and docs), so Polled(0.5) would silently bind 0.5 as the getter. Rather than reorder Polled's fields and rewrite every procedural call site, @attr takes a bare Polled(period=0.5), and rejects a schedule that already carries a getter. Say if you would rather Polled grew a period-first spelling.
• The docstring contributes its first paragraph, not the whole thing. A description is the one-line label a transport puts next to the value (CA DESC is 40 characters), so a getter with a summary line and further explanation contributes only the summary. Say if you want the whole docstring.

Notes

• UnboundAttr refuses to be read before it is bound, so _bind_attrs reaches the declaration with inspect.getattr_static rather than getattr. The error a user gets from touching a decorated attribute before Controller.__init__ has run names the attribute and says why.
• .setter returns a new UnboundAttrRW rather than mutating in place, so class Child(Base) declaring a setter for a getter it inherited does not also give Base a setter. Covered by a test.
• The setter's value annotation is optional, but is checked against the getter's datatype when present.
• Unblocks Example 1 — hello-world: pure-soft @attr decorator device #398 (hello-world), which is the first user of this.
• Verified locally with uv run --locked tox -e pre-commit,type-checking, both green in full. For the tests env, this sandbox can't run docs (needs outbound network - conf.py fetches switcher.json) or the PVA/p4p-backed tests (RuntimeError: Address family not supported by protocol), the same known limitation noted on demo: use ControllerVector for temperature ramp sub-controllers #409/demo: cut-down Eiger REST sim + introspectable controller example #410/demo: convert temperature controller to getter/setter style #411/attributes: getter/setter IO rework, remove AttributeIORef/AttributeIO #412/attributes: replace the DataType family with python types and *Meta typed dicts #418/methods: typed commands — positional arguments and a return value #419/controllers: ControllerRunner, plus native timestamps and severity on attributes #420. Excluding those, pytest src tests --ignore=tests/benchmarking passes 437/447, with only the same 10 pre-existing p4p/socket-family failures, which I confirmed are identical on refactor itself by running them in a worktree off the base commit. I also ran the docs build offline with the switcher.json fetch stubbed out: it succeeds, and every warning it reports is a missing-intersphinx-inventory artifact of having no network, present on unrelated existing modules too - none come from the new module or the new page. Real CI covers docs and PVA.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SiGhLM9QRKpnQykdmMfLsh

---

Generated by Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: ea72352b-70d1-4ee6-8c89-fd88516fbd78

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 99.12281% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 92.63%. Comparing base (e73453b) to head (a5b7bf7).
⚠️ Report is 5 commits behind head on refactor.

Files with missing lines	Patch %	Lines
src/fastcs/attributes/attr_decorator.py	99.02%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor     #423      +/-   ##
============================================
+ Coverage     91.25%   92.63%   +1.38%     
============================================
  Files            72       70       -2     
  Lines          2892     3298     +406     
============================================
+ Hits           2639     3055     +416     
+ Misses          253      243      -10     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[shihab-dls]

Pushed a few changes. Now happy with the final shape, so approving on my end.

[coretl]

@shihab-dls I'm tempted to copy PyTango in this rather than @property so we don't need to ignore pyright.

If we say the name should be set_voltage, then the decorator sets the setter on the AttrRW, but returns the setter function.

That means controller.voltage is an AttrRW, but controller.set_voltage is a method that sets controller.voltage. What do you think?

[shihab-dls]

100%. I'm actually now re-reviewing this after looking at #425, and realized we need to make this change. I'll add this as a comment on that PR.