refactor: replace @auto_refresh with simpler @dirties_state decorator

- Remove complex automatic refresh system in favor of explicit state tracking.
- Add dirty flags to OmniLogic and update refresh() with flexible
  if_dirty/if_older_than/force parameters for better user control.

Author: cryptk

pyomnilogic_local/_base.py

@@ -97,25 +97,3 @@ def update_telemetry(self, telemetry: Telemetry) -> None:
             self.telemetry = cast(TelemetryT, specific_telemetry)
         else:
             self.telemetry = cast(TelemetryT, None)
-        # else:
-        #     raise NotImplementedError("This equipment does not have telemetry data.")
-
-    # def _update_equipment(self, telemetry: Telemetry) -> None:
-    #     pass
-
-    # def _update_equipment(self, telemetry: Telemetry) -> None:
-    #     """Update any child equipment based on the latest MSPConfig and Telemetry data."""
-    #     for _, equipment_mspconfig in self.mspconfig:
-    #         system_id = equipment_mspconfig.system_id
-    #         if system_id is None:
-    #             _LOGGER.debug("Skipping equipment update: system_id is None: %s", equipment_mspconfig)
-    #             continue
-    #         if system_id in self.child_equipment:
-    #             # Update existing child equipment
-    #             child_equipment = self.child_equipment[system_id]
-    #             if child_equipment is not None:
-    #                 child_equipment.update_config(equipment_mspconfig)
-    #                 if hasattr(self, "telemetry"):
-    #                     child_equipment.update_telemetry(telemetry)
-    #         else:
-    #             equipment = create_equipment(self, equipment_mspconfig, telemetry)

pyomnilogic_local/colorlogiclight.py

@@ -2,7 +2,7 @@
 from typing import TYPE_CHECKING
 
 from pyomnilogic_local._base import OmniEquipment
-from pyomnilogic_local.decorators import auto_refresh
+from pyomnilogic_local.decorators import dirties_state
 from pyomnilogic_local.models.mspconfig import MSPColorLogicLight
 from pyomnilogic_local.models.telemetry import Telemetry, TelemetryColorLogicLight
 from pyomnilogic_local.omnitypes import (
@@ -72,21 +72,21 @@ def special_effect(self) -> int:
         """Returns the current special effect."""
         return self.telemetry.special_effect
 
-    @auto_refresh()
+    @dirties_state()
     async def turn_on(self) -> None:
         """Turns the light on."""
         if self.bow_id is None or self.system_id is None:
             raise OmniEquipmentNotInitializedError("Cannot turn on light: bow_id or system_id is None")
         await self._api.async_set_equipment(self.bow_id, self.system_id, True)
 
-    @auto_refresh()
+    @dirties_state()
     async def turn_off(self) -> None:
         """Turns the light off."""
         if self.bow_id is None or self.system_id is None:
             raise OmniEquipmentNotInitializedError("Cannot turn off light: bow_id or system_id is None")
         await self._api.async_set_equipment(self.bow_id, self.system_id, False)
 
-    @auto_refresh()
+    @dirties_state()
     async def set_show(
         self, show: LightShows | None = None, speed: ColorLogicSpeed | None = None, brightness: ColorLogicBrightness | None = None
     ) -> None:

pyomnilogic_local/decorators.py

@@ -1,9 +1,7 @@
-"""Decorators for automatic state management in pyomnilogic_local."""
+"""Decorators for equipment control methods."""
 
-import asyncio
 import functools
 import logging
-import time
 from collections.abc import Callable
 from typing import Any, TypeVar, cast
 
@@ -12,82 +10,37 @@
 F = TypeVar("F", bound=Callable[..., Any])
 
 
-def auto_refresh(
-    update_mspconfig: bool = False,
-    update_telemetry: bool = True,
-    delay: float = 1.25,
-) -> Callable[[F], F]:
-    """Decorator to automatically refresh OmniLogic state after method execution.
+def dirties_state(mspconfig: bool = False, telemetry: bool = True) -> Callable[[F], F]:
+    """Mark state as dirty after equipment control methods.
 
-    This decorator will:
-    1. Execute the decorated method
-    2. Wait for the specified delay (to allow controller to update)
-    3. Refresh telemetry/mspconfig if they're older than the post-delay time
-
-    The decorator is lock-safe: if multiple decorated methods are called concurrently,
-    only one refresh will occur thanks to the update_if_older_than mechanism.
+    This decorator marks the OmniLogic state (telemetry and/or mspconfig) as dirty
+    after a control method executes, indicating that the cached state is likely
+    out of sync with reality. Users can then call refresh() to update the state.
 
     Args:
-        update_mspconfig: Whether to refresh MSPConfig after method execution
-        update_telemetry: Whether to refresh Telemetry after method execution
-        delay: Time in seconds to wait after method completes before refreshing
-
-    Usage:
-        @auto_refresh()  # Default: telemetry only, 0.25s delay
-        async def turn_on(self, auto_refresh: bool | None = None):
-            ...
-
-        @auto_refresh(update_mspconfig=True, delay=0.5)
-        async def configure(self, auto_refresh: bool | None = None):
-            ...
+        mspconfig: Whether to mark mspconfig as dirty (default: False)
+        telemetry: Whether to mark telemetry as dirty (default: True)
 
-    The decorated method can accept an optional `auto_refresh` parameter:
-    - If None (default): Uses the OmniLogic instance's auto_refresh_enabled setting
-    - If True: Forces auto-refresh regardless of instance setting
-    - If False: Disables auto-refresh for this call
+    Example:
+        @dirties_state(telemetry=True)
+        async def turn_on(self) -> None:
+            await self._api.async_set_equipment(...)
     """
 
     def decorator(func: F) -> F:
         @functools.wraps(func)
-        async def wrapper(*args: Any, **kwargs: Any) -> Any:
-            # Extract the 'auto_refresh' parameter if provided
-            auto_refresh_param = kwargs.pop("auto_refresh", None)
-
-            # First arg should be 'self' (equipment instance)
-            if not args:
-                raise RuntimeError("@auto_refresh decorator requires a method with 'self' parameter")
-
-            self_obj = args[0]
-
-            # Get the OmniLogic instance
-            # Equipment classes should have _omni attribute pointing to parent OmniLogic
-            if hasattr(self_obj, "_omni") and self_obj._omni is not None:  # pylint: disable=protected-access
-                omni = self_obj._omni  # pylint: disable=protected-access
-            elif hasattr(self_obj, "auto_refresh_enabled"):
-                # This IS the OmniLogic instance
-                omni = self_obj
+        async def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+            # Execute the original function
+            result = await func(self, *args, **kwargs)
+
+            # Mark state as dirty
+            if hasattr(self, "_omni"):
+                if telemetry:
+                    self._omni._telemetry_dirty = True  # pylint: disable=protected-access
+                if mspconfig:
+                    self._omni._mspconfig_dirty = True  # pylint: disable=protected-access
             else:
-                raise RuntimeError("@auto_refresh decorator requires equipment to have '_omni' attribute or be used on OmniLogic methods")
-
-            # Determine if we should auto-refresh
-            should_refresh = auto_refresh_param if auto_refresh_param is not None else omni.auto_refresh_enabled
-
-            # Execute the original method
-            result = await func(*args, **kwargs)
-
-            # Perform auto-refresh if enabled
-            if should_refresh:
-                # Wait for the controller to process the change
-                await asyncio.sleep(delay)
-
-                # Calculate the target time (after delay)
-                target_time = time.time()
-
-                # Update only if data is older than target time
-                await omni.update_if_older_than(
-                    telemetry_min_time=target_time if update_telemetry else None,
-                    mspconfig_min_time=target_time if update_mspconfig else None,
-                )
+                _LOGGER.warning("%s does not have _omni reference, cannot mark state as dirty", self.__class__.__name__)
 
             return result
 

pyomnilogic_local/omnilogic.py

@@ -11,8 +11,6 @@
 
 
 class OmniLogic:
-    auto_refresh_enabled: bool = True
-
     mspconfig: MSPConfig
     telemetry: Telemetry
 
@@ -21,6 +19,8 @@ class OmniLogic:
 
     _mspconfig_last_updated: float = 0.0
     _telemetry_last_updated: float = 0.0
+    _mspconfig_dirty: bool = True
+    _telemetry_dirty: bool = True
     _refresh_lock: asyncio.Lock
 
     def __init__(self, host: str, port: int = 10444) -> None:
@@ -30,58 +30,60 @@ def __init__(self, host: str, port: int = 10444) -> None:
         self._api = OmniLogicAPI(host, port)
         self._refresh_lock = asyncio.Lock()
 
-    async def refresh(self, update_mspconfig: bool = True, update_telemetry: bool = True) -> None:
-        """Refresh the data from the OmniLogic controller.
-
-        Args:
-            update_mspconfig: Whether to fetch and update MSPConfig data
-            update_telemetry: Whether to fetch and update Telemetry data
-        """
-        if update_mspconfig:
-            self.mspconfig = await self._api.async_get_mspconfig()
-            self._mspconfig_last_updated = time.time()
-        if update_telemetry:
-            self.telemetry = await self._api.async_get_telemetry()
-            self._telemetry_last_updated = time.time()
-
-        self._update_equipment()
-
-    # async def refresh_mspconfig(self) -> None:
-    #     """Refresh only the MSPConfig data from the OmniLogic controller."""
-    #     self.mspconfig = await self._api.async_get_mspconfig()
-    #     self._mspconfig_last_updated = time.time()
-    #     self._update_equipment()
-
-    # async def refresh_telemetry(self) -> None:
-    #     """Refresh only the Telemetry data from the OmniLogic controller."""
-    #     self.telemetry = await self._api.async_get_telemetry()
-    #     self._telemetry_last_updated = time.time()
-    #     self._update_equipment()
-
-    async def update_if_older_than(
+    async def refresh(
         self,
-        telemetry_min_time: float | None = None,
-        mspconfig_min_time: float | None = None,
+        *,
+        mspconfig: bool = True,
+        telemetry: bool = True,
+        if_dirty: bool = True,
+        if_older_than: float = 10.0,
+        force: bool = False,
     ) -> None:
-        """Update telemetry/mspconfig only if older than specified timestamp.
-
-        This method uses a lock to ensure only one refresh happens at a time.
-        If another thread/task already updated the data to be newer than required,
-        this method will skip the update.
+        """Refresh the data from the OmniLogic controller.
 
         Args:
-            telemetry_min_time: Update telemetry if last updated before this timestamp
-            mspconfig_min_time: Update mspconfig if last updated before this timestamp
+            mspconfig: Whether to refresh MSPConfig data (if conditions are met)
+            telemetry: Whether to refresh Telemetry data (if conditions are met)
+            if_dirty: Only refresh if the data has been marked dirty
+            if_older_than: Only refresh if data is older than this many seconds
+            force: Force refresh regardless of dirty flag or age
         """
         async with self._refresh_lock:
-            needs_telemetry = telemetry_min_time and self._telemetry_last_updated < telemetry_min_time
-            needs_mspconfig = mspconfig_min_time and self._mspconfig_last_updated < mspconfig_min_time
-
-            if needs_telemetry or needs_mspconfig:
-                await self.refresh(
-                    update_mspconfig=bool(needs_mspconfig),
-                    update_telemetry=bool(needs_telemetry),
-                )
+            current_time = time.time()
+
+            # Determine if mspconfig needs updating
+            update_mspconfig = False
+            if mspconfig:
+                if force:
+                    update_mspconfig = True
+                elif if_dirty and self._mspconfig_dirty:
+                    update_mspconfig = True
+                elif (current_time - self._mspconfig_last_updated) > if_older_than:
+                    update_mspconfig = True
+
+            # Determine if telemetry needs updating
+            update_telemetry = False
+            if telemetry:
+                if force:
+                    update_telemetry = True
+                elif if_dirty and self._telemetry_dirty:
+                    update_telemetry = True
+                elif (current_time - self._telemetry_last_updated) > if_older_than:
+                    update_telemetry = True
+
+            # Perform the updates
+            if update_mspconfig:
+                self.mspconfig = await self._api.async_get_mspconfig()
+                self._mspconfig_last_updated = time.time()
+                self._mspconfig_dirty = False
+
+            if update_telemetry:
+                self.telemetry = await self._api.async_get_telemetry()
+                self._telemetry_last_updated = time.time()
+                self._telemetry_dirty = False
+
+            if update_mspconfig or update_telemetry:
+                self._update_equipment()
 
     def _update_equipment(self) -> None:
         """Update equipment objects based on the latest MSPConfig and Telemetry data."""