lifx-emulator 1.0.0__py3-none-any.whl

lifx_emulator/state_restorer.py

@@ -0,0 +1,259 @@
+"""State restoration for devices with persistent storage.
+
+This module provides centralized state restoration logic, eliminating
+duplication between factories and device initialization.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from lifx_emulator.device import DeviceState
+
+logger = logging.getLogger(__name__)
+
+
+class StateRestorer:
+    """Handles restoration of device state from persistent storage.
+
+    Consolidates state restoration logic that was previously duplicated
+    between factories and device initialization.
+    """
+
+    def __init__(self, storage: Any):
+        """Initialize state restorer.
+
+        Args:
+            storage: Storage instance (DeviceStorage or AsyncDeviceStorage)
+        """
+        self.storage = storage
+
+    def restore_if_available(self, state: DeviceState) -> DeviceState:
+        """Restore saved state if available and compatible.
+
+        Args:
+            state: DeviceState to restore into
+
+        Returns:
+            The same DeviceState instance with restored values
+        """
+        if not self.storage:
+            return state
+
+        saved_state = self.storage.load_device_state(state.serial)
+        if not saved_state:
+            logger.debug("No saved state found for device %s", state.serial)
+            return state
+
+        # Only restore if product matches
+        if saved_state.get("product") != state.product:
+            logger.warning(
+                "Saved state for %s has different product (%s vs %s), skipping restore",
+                state.serial,
+                saved_state.get("product"),
+                state.product,
+            )
+            return state
+
+        logger.info("Restoring saved state for device %s", state.serial)
+
+        # Restore core state
+        self._restore_core_state(state, saved_state)
+
+        # Restore location and group
+        self._restore_location_and_group(state, saved_state)
+
+        # Restore capability-specific state
+        self._restore_capability_state(state, saved_state)
+
+        return state
+
+    def _restore_core_state(
+        self, state: DeviceState, saved_state: dict[str, Any]
+    ) -> None:
+        """Restore core device state fields.
+
+        Args:
+            state: DeviceState to restore into
+            saved_state: Dictionary with saved state values
+        """
+        if "label" in saved_state:
+            state.core.label = saved_state["label"]
+        if "power_level" in saved_state:
+            state.core.power_level = saved_state["power_level"]
+        if "color" in saved_state:
+            state.core.color = saved_state["color"]
+
+    def _restore_location_and_group(
+        self, state: DeviceState, saved_state: dict[str, Any]
+    ) -> None:
+        """Restore location and group metadata.
+
+        Args:
+            state: DeviceState to restore into
+            saved_state: Dictionary with saved state values
+        """
+        # Location
+        if "location_id" in saved_state:
+            state.location.location_id = saved_state["location_id"]
+        if "location_label" in saved_state:
+            state.location.location_label = saved_state["location_label"]
+        if "location_updated_at" in saved_state:
+            state.location.location_updated_at = saved_state["location_updated_at"]
+
+        # Group
+        if "group_id" in saved_state:
+            state.group.group_id = saved_state["group_id"]
+        if "group_label" in saved_state:
+            state.group.group_label = saved_state["group_label"]
+        if "group_updated_at" in saved_state:
+            state.group.group_updated_at = saved_state["group_updated_at"]
+
+    def _restore_capability_state(
+        self, state: DeviceState, saved_state: dict[str, Any]
+    ) -> None:
+        """Restore capability-specific state.
+
+        Args:
+            state: DeviceState to restore into
+            saved_state: Dictionary with saved state values
+        """
+        # Infrared
+        if (
+            state.has_infrared
+            and state.infrared
+            and "infrared_brightness" in saved_state
+        ):
+            state.infrared.infrared_brightness = saved_state["infrared_brightness"]
+
+        # HEV
+        if state.has_hev and state.hev:
+            if "hev_cycle_duration_s" in saved_state:
+                state.hev.hev_cycle_duration_s = saved_state["hev_cycle_duration_s"]
+            if "hev_cycle_remaining_s" in saved_state:
+                state.hev.hev_cycle_remaining_s = saved_state["hev_cycle_remaining_s"]
+            if "hev_cycle_last_power" in saved_state:
+                state.hev.hev_cycle_last_power = saved_state["hev_cycle_last_power"]
+            if "hev_indication" in saved_state:
+                state.hev.hev_indication = saved_state["hev_indication"]
+            if "hev_last_result" in saved_state:
+                state.hev.hev_last_result = saved_state["hev_last_result"]
+
+        # Multizone
+        if state.has_multizone and state.multizone:
+            self._restore_multizone_state(state, saved_state)
+
+        # Matrix (Tile)
+        if state.has_matrix and state.matrix:
+            self._restore_matrix_state(state, saved_state)
+
+    def _restore_multizone_state(
+        self, state: DeviceState, saved_state: dict[str, Any]
+    ) -> None:
+        """Restore multizone-specific state.
+
+        Args:
+            state: DeviceState to restore into
+            saved_state: Dictionary with saved state values
+        """
+        if state.multizone is None:
+            return
+
+        # First restore zone_count from saved state
+        # This ensures the device matches what was previously saved
+        if "zone_count" in saved_state:
+            state.multizone.zone_count = saved_state["zone_count"]
+            logger.debug("Restored zone_count: %s", state.multizone.zone_count)
+
+        # Now restore zone colors if available
+        if "zone_colors" in saved_state:
+            # Verify zone count matches (should match now that we restored it)
+            if len(saved_state["zone_colors"]) == state.multizone.zone_count:
+                state.multizone.zone_colors = saved_state["zone_colors"]
+                logger.debug("Restored %s zone colors", len(saved_state["zone_colors"]))
+            else:
+                logger.warning(
+                    "Zone count mismatch: saved has %s zones, current has %s zones",
+                    len(saved_state["zone_colors"]),
+                    state.multizone.zone_count,
+                )
+
+        if "multizone_effect_type" in saved_state:
+            state.multizone.effect_type = saved_state["multizone_effect_type"]
+        if "multizone_effect_speed" in saved_state:
+            state.multizone.effect_speed = saved_state["multizone_effect_speed"]
+
+    def _restore_matrix_state(
+        self, state: DeviceState, saved_state: dict[str, Any]
+    ) -> None:
+        """Restore matrix (tile) specific state.
+
+        Args:
+            state: DeviceState to restore into
+            saved_state: Dictionary with saved state values
+        """
+        if state.matrix is None:
+            return
+
+        # First restore tile configuration (count, width, height) from saved state
+        # This ensures the device matches what was previously saved
+        if "tile_count" in saved_state:
+            state.matrix.tile_count = saved_state["tile_count"]
+            logger.debug("Restored tile_count: %s", state.matrix.tile_count)
+        if "tile_width" in saved_state:
+            state.matrix.tile_width = saved_state["tile_width"]
+            logger.debug("Restored tile_width: %s", state.matrix.tile_width)
+        if "tile_height" in saved_state:
+            state.matrix.tile_height = saved_state["tile_height"]
+            logger.debug("Restored tile_height: %s", state.matrix.tile_height)
+
+        # Now restore tile devices if available
+        if "tile_devices" in saved_state:
+            saved_tiles = saved_state["tile_devices"]
+            # Verify tile count matches (should match now that we restored it)
+            if len(saved_tiles) == state.matrix.tile_count:
+                # Verify all tiles have matching dimensions
+                if all(
+                    t["width"] == state.matrix.tile_width
+                    and t["height"] == state.matrix.tile_height
+                    for t in saved_tiles
+                ):
+                    state.matrix.tile_devices = saved_tiles
+                    logger.debug("Restored %s tile devices", len(saved_tiles))
+                else:
+                    logger.warning(
+                        "Tile dimensions mismatch, skipping tile restoration"
+                    )
+            else:
+                logger.warning(
+                    f"Tile count mismatch: saved has {len(saved_tiles)} tiles, "
+                    f"current has {state.matrix.tile_count} tiles"
+                )
+
+        if "tile_effect_type" in saved_state:
+            state.matrix.effect_type = saved_state["tile_effect_type"]
+        if "tile_effect_speed" in saved_state:
+            state.matrix.effect_speed = saved_state["tile_effect_speed"]
+        if "tile_effect_palette_count" in saved_state:
+            state.matrix.effect_palette_count = saved_state["tile_effect_palette_count"]
+        if "tile_effect_palette" in saved_state:
+            state.matrix.effect_palette = saved_state["tile_effect_palette"]
+
+
+class NullStateRestorer:
+    """No-op state restorer for devices without persistence.
+
+    Allows code to unconditionally call restore without checking for None.
+    """
+
+    def restore_if_available(self, state: DeviceState) -> DeviceState:
+        """No-op restoration.
+
+        Args:
+            state: DeviceState (returned unchanged)
+
+        Returns:
+            The same DeviceState instance
+        """
+        return state

lifx_emulator/state_serializer.py

@@ -0,0 +1,130 @@
+"""Shared serialization logic for device state."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from lifx_emulator.protocol.protocol_types import LightHsbk
+
+
+def serialize_hsbk(hsbk: LightHsbk) -> dict[str, int]:
+    """Serialize LightHsbk to dict."""
+    return {
+        "hue": hsbk.hue,
+        "saturation": hsbk.saturation,
+        "brightness": hsbk.brightness,
+        "kelvin": hsbk.kelvin,
+    }
+
+
+def deserialize_hsbk(data: dict[str, int]) -> LightHsbk:
+    """Deserialize dict to LightHsbk."""
+    return LightHsbk(
+        hue=data["hue"],
+        saturation=data["saturation"],
+        brightness=data["brightness"],
+        kelvin=data["kelvin"],
+    )
+
+
+def serialize_device_state(device_state: Any) -> dict[str, Any]:
+    """Serialize DeviceState to dict.
+
+    Note: Accesses state via properties for backward compatibility with composed state.
+    """
+    state_dict = {
+        "serial": device_state.serial,
+        "label": device_state.label,
+        "product": device_state.product,
+        "power_level": device_state.power_level,
+        "color": serialize_hsbk(device_state.color),
+        "location_id": device_state.location_id.hex(),
+        "location_label": device_state.location_label,
+        "location_updated_at": device_state.location_updated_at,
+        "group_id": device_state.group_id.hex(),
+        "group_label": device_state.group_label,
+        "group_updated_at": device_state.group_updated_at,
+        "has_color": device_state.has_color,
+        "has_infrared": device_state.has_infrared,
+        "has_multizone": device_state.has_multizone,
+        "has_matrix": device_state.has_matrix,
+        "has_hev": device_state.has_hev,
+    }
+
+    if device_state.has_infrared:
+        state_dict["infrared_brightness"] = device_state.infrared_brightness
+
+    if device_state.has_hev:
+        state_dict["hev_cycle_duration_s"] = device_state.hev_cycle_duration_s
+        state_dict["hev_cycle_remaining_s"] = device_state.hev_cycle_remaining_s
+        state_dict["hev_cycle_last_power"] = device_state.hev_cycle_last_power
+        state_dict["hev_indication"] = device_state.hev_indication
+        state_dict["hev_last_result"] = device_state.hev_last_result
+
+    if device_state.has_multizone:
+        state_dict["zone_count"] = device_state.zone_count
+        state_dict["zone_colors"] = [
+            serialize_hsbk(c) for c in device_state.zone_colors
+        ]
+        state_dict["multizone_effect_type"] = device_state.multizone_effect_type
+        state_dict["multizone_effect_speed"] = device_state.multizone_effect_speed
+
+    if device_state.has_matrix:
+        state_dict["tile_count"] = device_state.tile_count
+        state_dict["tile_width"] = device_state.tile_width
+        state_dict["tile_height"] = device_state.tile_height
+        state_dict["tile_effect_type"] = device_state.tile_effect_type
+        state_dict["tile_effect_speed"] = device_state.tile_effect_speed
+        state_dict["tile_effect_palette_count"] = device_state.tile_effect_palette_count
+        state_dict["tile_effect_palette"] = [
+            serialize_hsbk(c) for c in device_state.tile_effect_palette
+        ]
+        state_dict["tile_devices"] = [
+            {
+                "accel_meas_x": t["accel_meas_x"],
+                "accel_meas_y": t["accel_meas_y"],
+                "accel_meas_z": t["accel_meas_z"],
+                "user_x": t["user_x"],
+                "user_y": t["user_y"],
+                "width": t["width"],
+                "height": t["height"],
+                "device_version_vendor": t["device_version_vendor"],
+                "device_version_product": t["device_version_product"],
+                "firmware_build": t["firmware_build"],
+                "firmware_version_minor": t["firmware_version_minor"],
+                "firmware_version_major": t["firmware_version_major"],
+                "colors": [serialize_hsbk(c) for c in t["colors"]],
+            }
+            for t in device_state.tile_devices
+        ]
+
+    return state_dict
+
+
+def deserialize_device_state(state_dict: dict[str, Any]) -> dict[str, Any]:
+    """Deserialize device state dict (convert hex strings and nested objects)."""
+    # Deserialize bytes fields
+    state_dict["location_id"] = bytes.fromhex(state_dict["location_id"])
+    state_dict["group_id"] = bytes.fromhex(state_dict["group_id"])
+
+    # Deserialize color
+    state_dict["color"] = deserialize_hsbk(state_dict["color"])
+
+    # Deserialize zone colors if present
+    if "zone_colors" in state_dict:
+        state_dict["zone_colors"] = [
+            deserialize_hsbk(c) for c in state_dict["zone_colors"]
+        ]
+
+    # Deserialize tile effect palette if present
+    if "tile_effect_palette" in state_dict:
+        state_dict["tile_effect_palette"] = [
+            deserialize_hsbk(c) for c in state_dict["tile_effect_palette"]
+        ]
+
+    # Deserialize tile devices if present
+    if "tile_devices" in state_dict:
+        for tile_dict in state_dict["tile_devices"]:
+            tile_dict["colors"] = [deserialize_hsbk(c) for c in tile_dict["colors"]]
+
+    return state_dict

lifx_emulator/storage_protocol.py

@@ -0,0 +1,100 @@
+"""Storage protocol definition for device state persistence.
+
+This module defines the common interface that all storage implementations
+must follow, enabling polymorphic use and easier testing.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class StorageProtocol(Protocol):
+    """Protocol defining the interface for device state storage.
+
+    Both synchronous (DeviceStorage) and asynchronous (AsyncDeviceStorage)
+    implementations must provide these methods.
+
+    The protocol allows for polymorphic usage and dependency injection,
+    improving testability and adherence to SOLID principles.
+    """
+
+    def load_device_state(self, serial: str) -> dict[str, Any] | None:
+        """Load device state from persistent storage.
+
+        This method is synchronous in both implementations because loading
+        primarily happens at device initialization where blocking is acceptable.
+
+        Args:
+            serial: Device serial number
+
+        Returns:
+            Dictionary with device state, or None if not found
+        """
+        ...
+
+    def delete_device_state(self, serial: str) -> None:
+        """Delete device state from persistent storage.
+
+        This method is synchronous because deletion is rare and blocking
+        is acceptable for this operation.
+
+        Args:
+            serial: Device serial number
+        """
+        ...
+
+    def delete_all_device_states(self) -> int:
+        """Delete all device states from persistent storage.
+
+        This method is synchronous because it's typically used for cleanup
+        operations where blocking is acceptable.
+
+        Returns:
+            Number of devices deleted
+        """
+        ...
+
+    def list_devices(self) -> list[str]:
+        """List all devices with saved state.
+
+        This method is synchronous because listing is typically used for
+        administrative/query operations where blocking is acceptable.
+
+        Returns:
+            List of device serial numbers
+        """
+        ...
+
+
+@runtime_checkable
+class AsyncStorageProtocol(StorageProtocol, Protocol):
+    """Extended protocol for asynchronous storage implementations.
+
+    Adds async save method for high-performance non-blocking writes.
+    """
+
+    async def save_device_state(self, device_state: Any) -> None:
+        """Queue device state for saving (non-blocking).
+
+        Args:
+            device_state: DeviceState instance to persist
+        """
+        ...
+
+
+@runtime_checkable
+class SyncStorageProtocol(StorageProtocol, Protocol):
+    """Extended protocol for synchronous storage implementations.
+
+    Adds synchronous save method for simple blocking writes.
+    """
+
+    def save_device_state(self, device_state: Any) -> None:
+        """Save device state to persistent storage (blocking).
+
+        Args:
+            device_state: DeviceState instance to persist
+        """
+        ...