Improve Attribute validation

Add HintedAttribute dataclass
Allow for validation of Attribute type hints without a dtype

Author: GDYendell

src/fastcs/attributes/__init__.py

@@ -6,3 +6,4 @@
 from .attribute_io import AttributeIO as AttributeIO
 from .attribute_io_ref import AttributeIORef as AttributeIORef
 from .attribute_io_ref import AttributeIORefT as AttributeIORefT
+from .hinted_attribute import HintedAttribute as HintedAttribute

src/fastcs/attributes/hinted_attribute.py

@@ -0,0 +1,18 @@
+from dataclasses import dataclass
+
+from fastcs.attributes.attribute import Attribute
+from fastcs.datatypes import DType
+
+
+@dataclass(kw_only=True)
+class HintedAttribute:
+    """An `Attribute` type hint found on a `Controller` class
+
+    e.g. ``attr: AttrR[int]``
+
+    """
+
+    attr_type: type[Attribute]
+    """The type of the `Attribute` in the type hint - e.g. `AttrR`"""
+    dtype: type[DType] | None
+    """The dtype of the `Attribute` in the type hint, if any - e.g. `int`"""

src/fastcs/controllers/base_controller.py

@@ -5,10 +5,20 @@
 from copy import deepcopy
 from typing import _GenericAlias, get_args, get_origin, get_type_hints  # type: ignore
 
-from fastcs.attributes import Attribute, AttributeIO, AttributeIORefT, AttrR, AttrW
-from fastcs.datatypes import DataType, DType_T
+from fastcs.attributes import (
+    Attribute,
+    AttributeIO,
+    AttributeIORefT,
+    AttrR,
+    AttrW,
+    HintedAttribute,
+)
+from fastcs.datatypes import DType_T
+from fastcs.logging import bind_logger
 from fastcs.tracer import Tracer
 
+logger = bind_logger(logger_name=__name__)
+
 
 class BaseController(Tracer):
     """Base class for controllers
@@ -44,27 +54,41 @@ def __init__(
         # Internal state that should not be accessed directly by base classes
         self.__attributes: dict[str, Attribute] = {}
         self.__sub_controllers: dict[str, BaseController] = {}
-        self.__hinted_attributes = self._parse_attribute_type_hints()
+        self.__hinted_attributes = self._validate_attribute_type_hints()
 
         self._bind_attrs()
 
         ios = ios or []
         self._attribute_ref_io_map = {io.ref_type: io for io in ios}
         self._validate_io(ios)
 
-    def _parse_attribute_type_hints(
-        self,
-    ) -> dict[str, tuple[type[Attribute], type[DataType]]]:
-        hinted_attributes = {}
-        for name, hint in get_type_hints(type(self)).items():
-            if not isinstance(hint, _GenericAlias):  # e.g. AttrR[int]
-                continue
+    def _validate_attribute_type_hints(self) -> dict[str, HintedAttribute]:
+        """Validate `Attribute` type hints for introspection
 
-            origin = get_origin(hint)
-            if not isinstance(origin, type) or not issubclass(origin, Attribute):
-                continue
+        Returns:
+            A dictionary of `HintedAttribute` from type hints on this controller class
 
-            hinted_attributes[name] = (origin, get_args(hint)[0])
+        """
+        hinted_attributes = {}
+        for name, hint in get_type_hints(type(self)).items():
+            if isinstance(hint, _GenericAlias):  # e.g. AttrR[int]
+                args = get_args(hint)
+                hint = get_origin(hint)
+            else:
+                args = None
+
+            if isinstance(hint, type) and issubclass(hint, Attribute):
+                if args is None:
+                    dtype = None
+                else:
+                    if len(args) == 2:
+                        dtype = args[0]
+                    else:
+                        raise TypeError(
+                            f"Invalid type hint for attribute {name}: {hint}"
+                        )
+
+                hinted_attributes[name] = HintedAttribute(attr_type=hint, dtype=dtype)
 
         return hinted_attributes
 
@@ -136,18 +160,29 @@ def post_initialise(self):
         self._connect_attribute_ios()
 
     def _validate_hinted_attributes(self):
-        """Validate ``Attribute`` type-hints were introspected during initialisation"""
+        """Validate all `Attribute` type-hints were introspected"""
         for name in self.__hinted_attributes:
-            attr = getattr(self, name, None)
-            if attr is None or not isinstance(attr, Attribute):
-                raise RuntimeError(
-                    f"Controller `{self.__class__.__name__}` failed to introspect "
-                    f"hinted attribute `{name}` during initialisation"
-                )
+            self._validate_hinted_attribute(name)
 
         for subcontroller in self.sub_controllers.values():
             subcontroller._validate_hinted_attributes()  # noqa: SLF001
 
+    def _validate_hinted_attribute(self, name: str):
+        """Check that an `Attribute` with the given name exists on the controller"""
+        attr = getattr(self, name, None)
+        if attr is None or not isinstance(attr, Attribute):
+            raise RuntimeError(
+                f"Controller `{self.__class__.__name__}` failed to introspect "
+                f"hinted attribute `{name}` during initialisation"
+            )
+        else:
+            logger.debug(
+                "Validated hinted attribute",
+                name=name,
+                controller=self,
+                attribute=attr,
+            )
+
     def _connect_attribute_ios(self) -> None:
         """Connect ``Attribute`` callbacks to ``AttributeIO``s"""
         for attr in self.__attributes.values():
@@ -191,18 +226,18 @@ def add_attribute(self, name, attr: Attribute):
                 f"{self.__attributes[name]}"
             )
         elif name in self.__hinted_attributes:
-            attr_class, attr_dtype = self.__hinted_attributes[name]
-            if not isinstance(attr, attr_class):
+            hint = self.__hinted_attributes[name]
+            if not isinstance(attr, hint.attr_type):
                 raise RuntimeError(
                     f"Controller '{self.__class__.__name__}' introspection of "
                     f"hinted attribute '{name}' does not match defined access mode. "
-                    f"Expected '{attr_class.__name__}', got '{type(attr).__name__}'."
+                    f"Expected '{hint.attr_type.__name__}' got '{type(attr).__name__}'."
                 )
-            if attr_dtype is not None and attr_dtype != attr.datatype.dtype:
+            if hint.dtype is not None and hint.dtype != attr.datatype.dtype:
                 raise RuntimeError(
                     f"Controller '{self.__class__.__name__}' introspection of "
                     f"hinted attribute '{name}' does not match defined datatype. "
-                    f"Expected '{attr_dtype.__name__}', "
+                    f"Expected '{hint.dtype.__name__}', "
                     f"got '{attr.datatype.dtype.__name__}'."
                 )
         elif name in self.__sub_controllers.keys():