docs: resolve the UnboundGetter references the declare overloads emit

The docs job failed with four nitpicky warnings, all of them the
`UnboundGetter` in an `AttrR.declare`/`AttrRW.declare` overload.

Two of them were a real problem: the alias was defined in
`attr_decorator.py` and imported into `attr_r.py`/`attr_rw.py` only under
`TYPE_CHECKING`, so sphinx could not evaluate the annotation and fell
back to a bare, unresolvable name. `UnboundGetter` now lives in
`attr_r.py` next to `Getter`, and `UnboundSetter` in `attr_w.py` next to
`Setter`, which is where they belong and removes an import cycle rather
than working around one; `attr_decorator.py` imports them.

The other two are nested inside the `Callable[...]` the parameterised
overload returns, where a type alias cannot answer the `py:class`
reference sphinx emits, so they get a `nitpick_ignore` entry saying so.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JAWLNMnpQSJKbsZXa3NDZx

Author: claude

docs/conf.py

@@ -107,6 +107,11 @@
     # A ParamSpec gets no target of its own, so `Command[P, T]` renders a
     # reference to a bare `P` that resolves to nothing
     ("py:class", "P"),
+    # `UnboundGetter` resolves where it is a parameter's own annotation, but
+    # not where it is nested inside the `Callable[...]` an `AttrR.declare` /
+    # `AttrRW.declare` overload returns: a type alias is a `py:data` target,
+    # and a nested argument is rendered as a `py:class` reference
+    ("py:class", "UnboundGetter"),
 ]
 nitpick_ignore_regex = [
     ("py:class", r"fastcs.*.DType_T"),

src/fastcs/attributes/__init__.py

@@ -1,16 +1,16 @@
 from .attr_decorator import AttrSetter as AttrSetter
 from .attr_decorator import UnboundAttr as UnboundAttr
 from .attr_decorator import UnboundAttrRW as UnboundAttrRW
-from .attr_decorator import UnboundGetter as UnboundGetter
-from .attr_decorator import UnboundSetter as UnboundSetter
 from .attr_r import AttrR as AttrR
 from .attr_r import Getter as Getter
 from .attr_r import NotPolled as NotPolled
 from .attr_r import Polled as Polled
 from .attr_r import Schedule as Schedule
+from .attr_r import UnboundGetter as UnboundGetter
 from .attr_rw import AttrRW as AttrRW
 from .attr_w import AttrW as AttrW
 from .attr_w import Setter as Setter
+from .attr_w import UnboundSetter as UnboundSetter
 from .attribute import Attribute as Attribute
 from .attribute import AttributeAccessMode as AttributeAccessMode
 from .hinted_attribute import HintedAttribute as HintedAttribute

src/fastcs/attributes/attr_decorator.py

@@ -44,19 +44,19 @@ async def set_voltage(self, value: float) -> None:
     _datatype_for_annotation,
     _unwrap_update_annotation,
 )
-from fastcs.attributes.attr_r import AttrR, NotPolled, Polled, Schedule
+from fastcs.attributes.attr_r import (
+    AttrR,
+    NotPolled,
+    Polled,
+    Schedule,
+    UnboundGetter,
+)
 from fastcs.attributes.attr_rw import AttrRW
+from fastcs.attributes.attr_w import UnboundSetter
 from fastcs.attributes.update import Update
 from fastcs.datatypes import DType_T, Meta
 from fastcs.util import Controller_T
 
-UnboundGetter = Callable[[Controller_T], Awaitable[DType_T | Update[DType_T]]]
-"""A declared getter, taking the `Controller` it will be bound to as ``self``"""
-UnboundSetter = Callable[
-    [Controller_T, DType_T], Awaitable[None | DType_T | Update[DType_T]]
-]
-"""An ``@x.setter`` setter, taking the `Controller` it will be bound to as ``self``"""
-
 
 def _type_name(datatype: Any) -> str:
     """A datatype as it was most likely written, to name it in an error."""

src/fastcs/attributes/attr_r.py

@@ -31,10 +31,12 @@
 from fastcs.util import ONCE, Controller_T
 
 if TYPE_CHECKING:
-    from fastcs.attributes.attr_decorator import UnboundAttr, UnboundGetter
+    from fastcs.attributes.attr_decorator import UnboundAttr
 
 Getter = Callable[[], Awaitable[DType_T | Update[DType_T]]]
 """A callable that fetches a fresh value for an attribute from its source"""
+UnboundGetter = Callable[[Controller_T], Awaitable[DType_T | Update[DType_T]]]
+"""A declared getter, taking the `Controller` it will be bound to as ``self``"""
 AttrReadbackCallback = Callable[[DType_T], Coroutine[None, None, None]]
 """A callback to be called when the readback of the attribute updates"""
 

src/fastcs/attributes/attr_rw.py

@@ -3,7 +3,7 @@
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Any, Unpack, overload
 
-from fastcs.attributes.attr_r import AttrR, Getter, Schedule
+from fastcs.attributes.attr_r import AttrR, Getter, Schedule, UnboundGetter
 from fastcs.attributes.attr_w import AttrW, Setter
 from fastcs.attributes.attribute import AttributeAccessMode
 from fastcs.attributes.update import Update
@@ -27,7 +27,7 @@
 from fastcs.util import Controller_T
 
 if TYPE_CHECKING:
-    from fastcs.attributes.attr_decorator import UnboundAttrRW, UnboundGetter
+    from fastcs.attributes.attr_decorator import UnboundAttrRW
 
 
 class AttrRW(AttrR[DType_T], AttrW[DType_T]):

src/fastcs/attributes/attr_w.py

@@ -23,9 +23,14 @@
     TableMeta,
 )
 from fastcs.logging import logger
+from fastcs.util import Controller_T
 
 Setter = Callable[[DType_T], Awaitable[None | DType_T | Update[DType_T]]]
 """A callable that applies a new setpoint to an attribute's source"""
+UnboundSetter = Callable[
+    [Controller_T, DType_T], Awaitable[None | DType_T | Update[DType_T]]
+]
+"""An ``@x.setter`` setter, taking the `Controller` it will be bound to as ``self``"""
 AttrSetpointCallback = Callable[[DType_T], Coroutine[None, None, None]]
 """A callback to be called when the setpoint of the attribute updates"""