demo: pure-soft hello-world example using the @attr decorator

[coretl]

Closes #398

The first rung of the demo ladder, and the only one with no device behind it. Every value lives in the controller object, so this module runs with no simulator, no socket and no external process — which is the point: it shows the declarative spelling on its own, with nothing else to read past.

class HelloWorldController(Controller):
    def __init__(self, subject: str = "world") -> None:
        super().__init__()
        self._greeting = "Hello"
        self._subject = subject
        self._started = time.monotonic()

    @AttrRW.declare
    async def greeting(self) -> str:
        """The word to greet with."""
        return self._greeting

    @greeting.setter
    async def set_greeting(self, value: str) -> None:
        self._greeting = value

    @AttrR.declare(Polled(period=0.2))
    async def message(self) -> str:
        """The greeting as it currently reads."""
        return f"{self._greeting}, {self._subject}!"

    @AttrR.declare(Polled(period=0.2), units="s", precision=1)
    async def uptime(self) -> float:
        """Seconds since the controller was constructed."""
        return time.monotonic() - self._started

Scope

• New src/fastcs/demo/hello_world.py, covering the four things the decorator is: a bare decorated getter as an AttrR, an AttrRW.declare plus @x.setter pair, the docstring becoming the description, and the decorator's positional schedule plus keyword metadata (Polled(period=0.2), units="s", precision=1).
• message recomputes from greeting, so setting one attribute visibly moves another. That is the one thing a soft example can otherwise not show — a value changing for a reason other than you writing it — and it earns the Polled schedule honestly rather than polling a constant.
• tests/demo/test_hello_world.py: access modes, inferred datatypes, docstring descriptions, the ONCE-vs-polled schedules, the metadata, the static types, and that the setter is still callable as an ordinary method.
• The demo README's ladder already had the hello_world.py row; its "baselines vs framework PRs" paragraph said this module was still waiting on the decorator (@attr decorator sugar over getter/setter constructors #397), which merged as attributes: @attr decorator sugar over the getter/setter constructors #423, so that sentence is updated.

Also in this PR: the decorator names the class it builds

Added on review (thread r3944915082 and its follow-up), so that this example is the one we actually want. It is a change to the decorator itself (#397's code, merged as #423) rather than to the demo, and it is what makes the module above read as it does. It landed in two steps, and the second supersedes the first:

1. The setter got a name of its own, as PyTango's write_voltage does for a voltage attribute, rather than redeclaring the getter's name the way @property does. That removed the # pyright: ignore[reportRedeclaration] attributes: @attr decorator sugar over the getter/setter constructors #423 documented as its one wart, but left a second cost: a type checker binds the name at the decorator line and nothing later in the class body can change it, so self.greeting read as AttrR[str] even though it was an AttrRW[str] at runtime, and .set() needed assert isinstance(...) narrowing.

2. @attr is replaced by AttrR.declare/AttrRW.declare — an alternate constructor on the class the decorator builds, which is where @coretl and @shihab-dls landed on the thread. The type is now in the declaration rather than inferred from what follows it, so both costs are gone:

   • AttrR.declare is read-only and carries no setter at all — @serial.setter on one is an AttributeError, not a quiet promotion to read-write.
   • AttrRW.declare expects a setter, and a declaration that never gets one raises when the controller is constructed, naming the attribute.
   • self.greeting is an AttrRW[str] to pyright as well as at runtime. tests/demo/test_hello_world.py pins that with assert_type, so the type-checking job fails if it drifts.
   • set_greeting stays an ordinary bound method, so await controller.set_greeting("Goodbye") writes to the device directly while await controller.greeting.set("Goodbye") writes through the attribute and updates what clients see.
   • There is no # pyright: ignore left in the repo for either half of a read-write attribute.

   @x.setter still replaces the getter's declaration in the declaring class's own namespace, so @Base.voltage.setter in a subclass leaves Base without one (unchanged behaviour, same test).

   ADR 0018 gains an amendment recording the spelling and why it changed, since its resolved question 1 writes @attr + @x.setter and a reader would otherwise be given a spelling that no longer exists. ADRs 0013 and 0014 mention @attr in passing and are left alone as records of their own moment.

docs/how-to/fastcs-for-pytango-users.md is updated throughout: the PyTango pairing reads as voltage/write_voltage, and the note about narrowing is gone rather than reworded, because there is nothing left to narrow.

Instructions to reviewer on how to test:

1. uv run pytest tests/demo/test_hello_world.py tests/test_attr_decorator.py -v — nothing external needed.
2. uv run --locked tox -e type-checking — the assert_type calls in the demo tests are what prove the static type.
3. uv run python -c "import asyncio; from fastcs.demo.hello_world import HelloWorldController as C; c = C(); print(asyncio.run(c.message.poll()))"

Checks for reviewer

• Would the PR title make sense to a user on a set of release notes
• attr is removed rather than kept as an alias. Two spellings for one thing is what the review exchange was trying to avoid, and it is pre-1.0 with the decorator only days old (attributes: @attr decorator sugar over the getter/setter constructors #423), so everything in the repo is migrated instead. Say if you would rather attr stayed as a deprecated alias for a release.
• A read-only declaration can no longer be promoted by a subclass. AttrR.declare has no setter, which is what "@AttrR does not expect a setter" asks for — but it means a base that is read-only and instantiable, with a subclass adding writing, is no longer expressible. The subclass-namespace test now declares AttrRW.declare on the base and supplies the setter in the child, which still proves the thing it is for. Say if you want the promotion back.
• AttrRW.declare with no setter raises rather than binding a soft attribute. The procedural AttrRW(str) with no setter is legitimate — set() pushes straight to the readback — so this could have been allowed. A decorated getter is device IO by construction, though, so a silent soft round-trip is almost certainly a forgotten setter. Say if you would rather it were permitted.
• Three attributes, where the issue says "one or two". greeting alone would not show the @AttrR.declare(Polled(...), units=...) form, which is half the decorator's surface and the half a reader will reach for first. message and uptime are two lines each.
• The class is HelloWorldController, not HelloWorld. It matches TemperatureController/EigerDetector in reading as a controller, but the issue text says "hello world"; trivial to rename.
• uptime is a soft value that moves on its own (time.monotonic()). It is the only thing here with no user-visible cause, which is what makes it a fair demonstration of polling — but it is also the one attribute whose value is not reproducible, so its test only asserts it does not go backwards.

Notes

• The two per-instance tests (test_each_instance_gets_its_own_attributes, test_setting_one_instance_leaves_the_other_alone) are removed on review, as controllers: ControllerFiller, and one declarative mechanism for attributes #426 covers that generally.
• Overlaps controllers: ControllerFiller, and one declarative mechanism for attributes #426, which uses attr in tests/test_controller_filler.py and reads UnboundAttr in base_controller._bind_attrs. Both are independent branches off refactor; whichever merges second needs those decorators renamed, which is mechanical.
• Not added to src/fastcs/demo/fastcs.yaml. That file launches the temperature controllers over GraphQL and EPICS CA on fixed ports, and a soft example does not need a transport to be the thing it demonstrates; adding it would also churn the checked-in schema.json. Say if you would like it launchable.
• No literalinclude region markers yet — per the demo README those are added with each module's tutorial in the docs pass (DOCS: Rewrite tutorials around the examples/ controllers (one per example, single-sourced) #408).
• declare is a staticmethod with its own Declared_T TypeVar, which sits in datatypes/types.py next to Inferred_T: a class-scoped TypeVar leaves pyright resolving the decorator to AttrR[Unknown].
• Verified locally with uv run --locked tox -e pre-commit,type-checking, both green in full. As 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/attributes: @attr decorator sugar over the getter/setter constructors #423, this sandbox cannot run docs (needs outbound network) or the PVA/p4p-backed tests (RuntimeError: Address family not supported by protocol). Excluding those, pytest src tests --ignore=tests/benchmarking passes 451, with only the same 10 pre-existing p4p/socket-family failures. Real CI covers docs and PVA. mypy is not in this repo's dev dependencies or tox envs, so only pyright has been run.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JAWLNMnpQSJKbsZXa3NDZx

[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: c34c3d22-2ae1-4106-8f44-956594540d94

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 96.20253% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.63%. Comparing base (e73453b) to head (9c890be).
⚠️ Report is 6 commits behind head on refactor.

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

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor     #425      +/-   ##
============================================
+ Coverage     91.25%   92.63%   +1.38%     
============================================
  Files            72       70       -2     
  Lines          2892     3341     +449     
============================================
+ Hits           2639     3095     +456     
+ Misses          253      246       -7     

☔ 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]

The example has brought up a design choice we must change regarding @attr setters, so this must be changed in this PR, such that the example is correct.

[shihab-dls]

must: we should not have to # pyright: ignore[reportRedeclaration] to make a setter for our @attr. We should instead copy the PyTango approach rather than @property, where HelloWorldController.greeting is an AttrRW and set_greeting (or any method with @greeting.setter) is the method that sets HelloWorldController.greeting. such as:

Suggested change

	async def greeting(self) -> str: # pyright: ignore[reportRedeclaration]
	"""The word to greet with."""
	# A bare `@attr` is read once, when the controller connects, which is
	# what a value only changes because you changed it needs.
	return self._greeting
	@greeting.setter
	async def greeting(self, value: str) -> None:
	self._greeting = value
	async def greeting(self) -> str: # pyright: ignore[reportRedeclaration]
	"""The word to greet with."""
	# A bare `@attr` is read once, when the controller connects, which is
	# what a value only changes because you changed it needs.
	return self._greeting
	@greeting.setter
	async def set_greeting(self, value: str) -> None:
	self._greeting = value

Although this is beyond the original scope of this PR, support this change in this PR, and amend the PR description to mention that this PR will add this as a fix such that we have our intended example controller. We should ensure that an @attr without a setter (named whatever), ends up as an AttrR though.

[coretl]

Done in 6d2becd, and the PR description now covers it.

@x.setter returns an AttrSetter declaration instead of a new UnboundAttrRW. Its __set_name__ replaces the getter's declaration — in the declaring class's own namespace, so @Base.voltage.setter in a subclass still leaves Base read-only — with the read-write one. So HelloWorldController.greeting is an AttrRW, set_greeting stays an ordinary callable method (await controller.set_greeting("Goodbye") works and is tested), and an @attr with no setter is still an AttrR. No # pyright: ignore[reportRedeclaration] anywhere in the repo now. The old same-name spelling still works, so nothing else needed changing, but every call site and doc uses the named form.

One consequence to flag, because it is inherent to the spelling rather than to how I implemented it: a type checker binds greeting at the @attr line, and nothing later in the class body can change the type of a name already bound. So self.greeting is AttrR[str] statically even though it is an AttrRW[str] at runtime, and self.greeting.set(...) needs an assert isinstance(..., AttrRW) to narrow (which is what the tests do). Writing through your own set_greeting needs nothing. That is the trade for dropping the ignore — it moves the one suppression at the declaration to narrowing at the use sites that reach for .set(), which I think is the better side of it, but say if you would rather have it the other way.

Two follow-ups I have not done, as they look like your calls rather than mine:

• ADR 0018 still writes the spelling as @property-mirroring (§ "What is the decorator spelling?"). Happy to add an amendment section recording this, the way controllers: connections own health, reconnect and the retry budget #424 amends ADR 0016 — say the word.
• docs/how-to/fastcs-for-pytango-users.md is updated here (the PyTango pairing now reads as voltage/write_voltage, and the note about the ignore is replaced by one about the static type).

— overnight agent

---

Generated by Claude Code

[coretl]

Hmm, I'd prefer to put the type in the name rather than use @attr then have to type narrow. Considered attr.rw but that's another namespace to learn. I'd prefer the decorator to be attached to the type it creates. How about an alternate constructor on the class?

@AttrR.declare
async def uptime(self) -> float: ...

@AttrRW.declare(Polled(period=0.2), units="s")
async def greeting(self) -> str: ...

@greeting.setter
async def set_greeting(self, value: str) -> None: ...

Claude checked this is clean under both pyright and mypy with no suppressions anywhere. (It needs to be a staticmethod with its own TypeVar; a classmethod using the class's TypeVar leaves pyright at AttrR[Unknown] while mypy resolves it fine.)

@shihab-dls which spelling do you prefer?

• AttrRW.declare(...)
• AttrRW.of(...)
• AttrRW.wrap(...)
• AttrRW.from_getter(...) and AttrW.from_setter
• something else

[shihab-dls]

I agree with having a narrower decorator like @AttrR and AttrRW, where @AttrR does not expect a setter, but AttrRW does. I prefer .declare(...)

[coretl]

Agreed. Let's build that.

[coretl]

Built in 45f0db2, as .declare.

@AttrR.declare
async def uptime(self) -> float:
    """Seconds since the controller was constructed."""
    return time.monotonic() - self._started

@AttrRW.declare
async def greeting(self) -> str:
    """The word to greet with."""
    return self._greeting

@greeting.setter
async def set_greeting(self, value: str) -> None:
    self._greeting = value

self.greeting is now an AttrRW[str] to pyright, not just at runtime. That was the point, and it holds — tests/demo/test_hello_world.py asserts it with assert_type(controller.greeting, AttrRW[str]), so the type-checking job fails if it ever drifts. Every assert isinstance(..., AttrRW) narrowing that existed only to reach .set() is gone, and there is no # pyright: ignore left in the repo for either half of a read-write attribute.

AttrR.declare genuinely does not expect a setter, as you asked: setter lives on UnboundAttrRW alone, so @serial.setter on an AttrR.declare getter is an AttributeError, not a quiet promotion to read-write. AttrRW.declare expects one, and a declaration that never gets one raises when the controller is constructed, naming the attribute and offering both ways out.

It is a staticmethod with its own Declared_T TypeVar, as you found — a class-scoped TypeVar leaves pyright at AttrR[Unknown]. Declared_T sits in datatypes/types.py next to Inferred_T, which exists for the same reason on the constructor overloads.

Three things worth your eye:

• attr is gone, rather than kept as an alias. Two spellings for one thing is what the exchange above was trying to avoid, and it is pre-1.0 with the decorator only three days old (attributes: @attr decorator sugar over the getter/setter constructors #423). Everything in the repo is migrated: the demo, tests/test_attr_decorator.py, and docs/how-to/fastcs-for-pytango-users.md. Say if you would rather attr stayed as a deprecated alias for a release.
• A read-only declaration can no longer be promoted by a subclass. test_setter_does_not_leak_onto_the_class_it_was_inherited_from used to declare @attr on Base and @Base.voltage.setter in Child; the base now declares AttrRW.declare and the child supplies the setter, which still proves the thing the test is for — the setter lands in Child's namespace and Base.voltage does not have one. What is no longer expressible is a base that is read-only and instantiable while a subclass adds writing. That follows from "AttrR does not expect a setter"; say if you want it back and the fix is AttrR.declare keeping a setter that returns an UnboundAttrRW.
• ADR 0018 has an amendment, since the ADR's resolved question 1 records @attr + @x.setter and a reader would otherwise be given a spelling that does not exist. It records the redeclaration problem, the narrowing that replaced it, and this decision; the rest of the ADR stands, and ADRs 0013/0014 are left alone as the records of their own moment.

Verified with uv run --locked tox -e pre-commit,type-checking (both green in full) and the test suite — 451 passing, with only the 10 pre-existing p4p/socket-family failures this sandbox always has. I have not run mypy: it is not in this repo's dev dependencies or its tox envs, so I can only report pyright.

— overnight agent

---

Generated by Claude Code