lifx-emulator 1.0.2__py3-none-any.whl → 2.1.0__py3-none-any.whl

lifx_emulator/protocol/protocol_types.py

@@ -505,16 +505,11 @@ class TileBufferRect:
 
 @dataclass
 class TileEffectParameter:
-    """Auto-generated field structure."""
+    """Auto-generated field structure for Sky effects."""
 
-    parameter0: int
-    parameter1: int
-    parameter2: int
-    parameter3: int
-    parameter4: int
-    parameter5: int
-    parameter6: int
-    parameter7: int
+    sky_type: TileEffectSkyType
+    cloud_saturation_min: int
+    cloud_saturation_max: int
 
     def pack(self) -> bytes:
         """Pack to bytes."""
@@ -522,22 +517,18 @@ class TileEffectParameter:
 
         result = b""
 
-        # parameter0: uint32
-        result += serializer.pack_value(self.parameter0, "uint32")
-        # parameter1: uint32
-        result += serializer.pack_value(self.parameter1, "uint32")
-        # parameter2: uint32
-        result += serializer.pack_value(self.parameter2, "uint32")
-        # parameter3: uint32
-        result += serializer.pack_value(self.parameter3, "uint32")
-        # parameter4: uint32
-        result += serializer.pack_value(self.parameter4, "uint32")
-        # parameter5: uint32
-        result += serializer.pack_value(self.parameter5, "uint32")
-        # parameter6: uint32
-        result += serializer.pack_value(self.parameter6, "uint32")
-        # parameter7: uint32
-        result += serializer.pack_value(self.parameter7, "uint32")
+        # sky_type: TileEffectSkyType (enum)
+        result += serializer.pack_value(int(self.sky_type), "uint8")
+        # Reserved 3 bytes
+        result += serializer.pack_reserved(3)
+        # cloud_saturation_min: uint8
+        result += serializer.pack_value(self.cloud_saturation_min, "uint8")
+        # Reserved 3 bytes
+        result += serializer.pack_reserved(3)
+        # cloud_saturation_max: uint8
+        result += serializer.pack_value(self.cloud_saturation_max, "uint8")
+        # Reserved 23 bytes
+        result += serializer.pack_reserved(23)
 
         return result
 
@@ -547,49 +538,31 @@ class TileEffectParameter:
         from lifx_emulator.protocol import serializer
 
         current_offset = offset
-        # parameter0: uint32
-        parameter0, current_offset = serializer.unpack_value(
-            data, "uint32", current_offset
-        )
-        # parameter1: uint32
-        parameter1, current_offset = serializer.unpack_value(
-            data, "uint32", current_offset
-        )
-        # parameter2: uint32
-        parameter2, current_offset = serializer.unpack_value(
-            data, "uint32", current_offset
-        )
-        # parameter3: uint32
-        parameter3, current_offset = serializer.unpack_value(
-            data, "uint32", current_offset
-        )
-        # parameter4: uint32
-        parameter4, current_offset = serializer.unpack_value(
-            data, "uint32", current_offset
-        )
-        # parameter5: uint32
-        parameter5, current_offset = serializer.unpack_value(
-            data, "uint32", current_offset
+        # sky_type: TileEffectSkyType (enum)
+        sky_type_raw, current_offset = serializer.unpack_value(
+            data, "uint8", current_offset
         )
-        # parameter6: uint32
-        parameter6, current_offset = serializer.unpack_value(
-            data, "uint32", current_offset
+        sky_type = TileEffectSkyType(sky_type_raw)
+        # Skip reserved 3 bytes
+        current_offset += 3
+        # cloud_saturation_min: uint8
+        cloud_saturation_min, current_offset = serializer.unpack_value(
+            data, "uint8", current_offset
         )
-        # parameter7: uint32
-        parameter7, current_offset = serializer.unpack_value(
-            data, "uint32", current_offset
+        # Skip reserved 3 bytes
+        current_offset += 3
+        # cloud_saturation_max: uint8
+        cloud_saturation_max, current_offset = serializer.unpack_value(
+            data, "uint8", current_offset
         )
+        # Skip reserved 23 bytes
+        current_offset += 23
 
         return (
             cls(
-                parameter0=parameter0,
-                parameter1=parameter1,
-                parameter2=parameter2,
-                parameter3=parameter3,
-                parameter4=parameter4,
-                parameter5=parameter5,
-                parameter6=parameter6,
-                parameter7=parameter7,
+                sky_type=sky_type,
+                cloud_saturation_min=cloud_saturation_min,
+                cloud_saturation_max=cloud_saturation_max,
             ),
             current_offset,
         )

lifx_emulator/repositories/__init__.py

@@ -0,0 +1,22 @@
+"""Repository interfaces and implementations for LIFX emulator.
+
+This module defines repository abstractions following the Repository Pattern
+and Dependency Inversion Principle. Repositories encapsulate data access logic
+and provide a clean separation between domain logic and data persistence.
+"""
+
+from lifx_emulator.repositories.device_repository import (
+    DeviceRepository,
+    IDeviceRepository,
+)
+from lifx_emulator.repositories.storage_backend import (
+    IDeviceStorageBackend,
+    IScenarioStorageBackend,
+)
+
+__all__ = [
+    "IDeviceRepository",
+    "DeviceRepository",
+    "IDeviceStorageBackend",
+    "IScenarioStorageBackend",
+]

lifx_emulator/repositories/device_repository.py

@@ -0,0 +1,155 @@
+"""Device repository interface and implementation.
+
+Provides abstraction for device storage and retrieval operations,
+following the Repository Pattern and Dependency Inversion Principle.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from lifx_emulator.devices import EmulatedLifxDevice
+
+
+@runtime_checkable
+class IDeviceRepository(Protocol):
+    """Interface for device repository operations.
+
+    This protocol defines the contract for managing device storage and retrieval.
+    Concrete implementations can use in-memory storage, databases, or other backends.
+    """
+
+    def add(self, device: EmulatedLifxDevice) -> bool:
+        """Add a device to the repository.
+
+        Args:
+            device: Device to add
+
+        Returns:
+            True if device was added, False if device with same serial already exists
+        """
+        ...
+
+    def remove(self, serial: str) -> bool:
+        """Remove a device from the repository.
+
+        Args:
+            serial: Serial number of device to remove
+
+        Returns:
+            True if device was removed, False if not found
+        """
+        ...
+
+    def get(self, serial: str) -> EmulatedLifxDevice | None:
+        """Get a device by serial number.
+
+        Args:
+            serial: Serial number to look up
+
+        Returns:
+            Device if found, None otherwise
+        """
+        ...
+
+    def get_all(self) -> list[EmulatedLifxDevice]:
+        """Get all devices.
+
+        Returns:
+            List of all devices in the repository
+        """
+        ...
+
+    def clear(self) -> int:
+        """Remove all devices from the repository.
+
+        Returns:
+            Number of devices removed
+        """
+        ...
+
+    def count(self) -> int:
+        """Get the number of devices in the repository.
+
+        Returns:
+            Number of devices
+        """
+        ...
+
+
+class DeviceRepository:
+    """In-memory device repository implementation.
+
+    Stores devices in a dictionary keyed by serial number.
+    This is the default implementation used by EmulatedLifxServer.
+    """
+
+    def __init__(self) -> None:
+        """Initialize empty device repository."""
+        self._devices: dict[str, EmulatedLifxDevice] = {}
+
+    def add(self, device: EmulatedLifxDevice) -> bool:
+        """Add a device to the repository.
+
+        Args:
+            device: Device to add
+
+        Returns:
+            True if device was added, False if device with same serial already exists
+        """
+        serial = device.state.serial
+        if serial in self._devices:
+            return False
+        self._devices[serial] = device
+        return True
+
+    def remove(self, serial: str) -> bool:
+        """Remove a device from the repository.
+
+        Args:
+            serial: Serial number of device to remove
+
+        Returns:
+            True if device was removed, False if not found
+        """
+        if serial in self._devices:
+            del self._devices[serial]
+            return True
+        return False
+
+    def get(self, serial: str) -> EmulatedLifxDevice | None:
+        """Get a device by serial number.
+
+        Args:
+            serial: Serial number to look up
+
+        Returns:
+            Device if found, None otherwise
+        """
+        return self._devices.get(serial)
+
+    def get_all(self) -> list[EmulatedLifxDevice]:
+        """Get all devices.
+
+        Returns:
+            List of all devices in the repository
+        """
+        return list(self._devices.values())
+
+    def clear(self) -> int:
+        """Remove all devices from the repository.
+
+        Returns:
+            Number of devices removed
+        """
+        count = len(self._devices)
+        self._devices.clear()
+        return count
+
+    def count(self) -> int:
+        """Get the number of devices in the repository.
+
+        Returns:
+            Number of devices
+        """
+        return len(self._devices)

lifx_emulator/repositories/storage_backend.py

@@ -0,0 +1,107 @@
+"""Storage backend interfaces for device and scenario persistence.
+
+Provides abstraction for persistent storage operations,
+following the Repository Pattern and Dependency Inversion Principle.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from lifx_emulator.scenarios import HierarchicalScenarioManager
+
+
+@runtime_checkable
+class IDeviceStorageBackend(Protocol):
+    """Interface for device state persistence operations.
+
+    This protocol defines the contract for loading and saving device state.
+    Concrete implementations can use async file I/O, databases,
+    or other storage backends.
+    """
+
+    async def save_device_state(self, device_state: Any) -> None:
+        """Save device state to persistent storage (async).
+
+        Args:
+            device_state: DeviceState instance to persist
+        """
+        raise NotImplementedError
+
+    def load_device_state(self, serial: str) -> dict | None:
+        """Load device state from persistent storage (sync).
+
+        Args:
+            serial: Device serial number (12-character hex string)
+
+        Returns:
+            Dictionary with device state data, or None if not found
+        """
+        raise NotImplementedError
+
+    def delete_device_state(self, serial: str) -> bool:
+        """Delete device state from persistent storage.
+
+        Args:
+            serial: Device serial number
+
+        Returns:
+            True if state was deleted, False if not found
+        """
+        raise NotImplementedError
+
+    def list_devices(self) -> list[str]:
+        """List all device serials with saved state.
+
+        Returns:
+            List of serial numbers
+        """
+        raise NotImplementedError
+
+    def delete_all_device_states(self) -> int:
+        """Delete all device states from persistent storage.
+
+        Returns:
+            Number of device states deleted
+        """
+        raise NotImplementedError
+
+    async def shutdown(self) -> None:
+        """Gracefully shutdown storage backend, flushing pending writes."""
+        raise NotImplementedError
+
+
+@runtime_checkable
+class IScenarioStorageBackend(Protocol):
+    """Interface for scenario configuration persistence operations.
+
+    This protocol defines the contract for loading and saving scenario configurations.
+    Concrete implementations can use async file I/O, databases,
+    or other storage backends.
+    """
+
+    async def load(self) -> HierarchicalScenarioManager:
+        """Load scenario configuration from persistent storage (async).
+
+        Returns:
+            Scenario manager with loaded configuration, or default manager
+            if no saved data
+        """
+        raise NotImplementedError
+
+    async def save(self, manager: HierarchicalScenarioManager) -> None:
+        """Save scenario configuration to persistent storage (async).
+
+        Args:
+            manager: Scenario manager whose configuration should be saved
+        """
+        raise NotImplementedError
+
+    async def delete(self) -> bool:
+        """Delete scenario configuration from persistent storage (async).
+
+        Returns:
+            True if configuration was deleted, False if it didn't exist
+        """
+        raise NotImplementedError

lifx_emulator/scenarios/__init__.py

@@ -0,0 +1,22 @@
+"""Scenario management module for LIFX emulator.
+
+This module contains all scenario-related functionality including:
+- Scenario manager (HierarchicalScenarioManager)
+- Scenario models (ScenarioConfig)
+- Scenario persistence (async file storage)
+- Device type classification (get_device_type)
+"""
+
+from lifx_emulator.scenarios.manager import (
+    HierarchicalScenarioManager,
+    get_device_type,
+)
+from lifx_emulator.scenarios.models import ScenarioConfig
+from lifx_emulator.scenarios.persistence import ScenarioPersistenceAsyncFile
+
+__all__ = [
+    "HierarchicalScenarioManager",
+    "ScenarioConfig",
+    "ScenarioPersistenceAsyncFile",
+    "get_device_type",
+]

lifx_emulator/{scenario_manager.py → scenarios/manager.py}

@@ -5,96 +5,12 @@ test scenarios at multiple scopes with precedence-based resolution.
 """
 
 import random
-from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
-if TYPE_CHECKING:
-    from lifx_emulator.device import EmulatedLifxDevice
-
-
-@dataclass
-class ScenarioConfig:
-    """Individual scenario configuration.
-
-    Scenarios define testing behaviors for the emulator, such as:
-    - Dropping specific packet types (no response)
-    - Adding response delays
-    - Sending malformed/corrupted responses
-    - Overriding firmware version
-    """
-
-    drop_packets: dict[int, float] = field(default_factory=dict)
-    """Packet types to drop with drop rates (0.1-1.0).
-
-    Maps packet type to drop rate where:
-    - 1.0 = always drop (100%)
-    - 0.5 = drop 50% of packets
-    - 0.1 = drop 10% of packets
-    Examples: {101: 1.0} (always drop), {102: 0.6} (drop 60% of packets)
-    """
+from lifx_emulator.scenarios.models import ScenarioConfig
 
-    response_delays: dict[int, float] = field(default_factory=dict)
-    """Response delays in seconds by packet type"""
-
-    malformed_packets: list[int] = field(default_factory=list)
-    """Packet types to send truncated/corrupted"""
-
-    invalid_field_values: list[int] = field(default_factory=list)
-    """Packet types to send with all 0xFF bytes"""
-
-    firmware_version: tuple[int, int] | None = None
-    """Override firmware version (major, minor)"""
-
-    partial_responses: list[int] = field(default_factory=list)
-    """Packet types to send incomplete multizone/tile data"""
-
-    send_unhandled: bool = False
-    """Send StateUnhandled for unknown packet types"""
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for API serialization."""
-        return {
-            "drop_packets": {str(k): v for k, v in self.drop_packets.items()},
-            "response_delays": {str(k): v for k, v in self.response_delays.items()},
-            "malformed_packets": self.malformed_packets,
-            "invalid_field_values": self.invalid_field_values,
-            "firmware_version": self.firmware_version,
-            "partial_responses": self.partial_responses,
-            "send_unhandled": self.send_unhandled,
-        }
-
-    @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> "ScenarioConfig":
-        """Create from dictionary (API input)."""
-        firmware = data.get("firmware_version")
-        if firmware and not isinstance(firmware, tuple):
-            firmware = tuple(firmware)
-
-        # Convert drop_packets keys from string to int
-        drop_packets_input = data.get("drop_packets", {})
-        drop_packets = (
-            {int(k): v for k, v in drop_packets_input.items()}
-            if isinstance(drop_packets_input, dict)
-            else {}
-        )
-
-        # Convert response_delays keys from string to int
-        response_delays_input = data.get("response_delays", {})
-        response_delays = (
-            {int(k): v for k, v in response_delays_input.items()}
-            if isinstance(response_delays_input, dict)
-            else {}
-        )
-
-        return cls(
-            drop_packets=drop_packets,
-            response_delays=response_delays,
-            malformed_packets=data.get("malformed_packets", []),
-            invalid_field_values=data.get("invalid_field_values", []),
-            firmware_version=firmware,
-            partial_responses=data.get("partial_responses", []),
-            send_unhandled=data.get("send_unhandled", False),
-        )
+if TYPE_CHECKING:
+    from lifx_emulator.devices import EmulatedLifxDevice
 
 
 def get_device_type(device: "EmulatedLifxDevice") -> str:
@@ -144,7 +60,9 @@ class HierarchicalScenarioManager:
         self.type_scenarios: dict[str, ScenarioConfig] = {}  # type → config
         self.location_scenarios: dict[str, ScenarioConfig] = {}  # location → config
         self.group_scenarios: dict[str, ScenarioConfig] = {}  # group → config
-        self.global_scenario: ScenarioConfig = ScenarioConfig()
+        self.global_scenario: ScenarioConfig = ScenarioConfig(
+            firmware_version=None, send_unhandled=False
+        )
 
     def set_device_scenario(self, serial: str, config: ScenarioConfig):
         """Set scenario for specific device by serial."""
@@ -184,7 +102,9 @@ class HierarchicalScenarioManager:
 
     def clear_global_scenario(self):
         """Clear global scenario (reset to empty)."""
-        self.global_scenario = ScenarioConfig()
+        self.global_scenario = ScenarioConfig(
+            firmware_version=None, send_unhandled=False
+        )
 
     def get_global_scenario(self) -> ScenarioConfig:
         """Get global scenario configuration."""
@@ -265,7 +185,7 @@ class HierarchicalScenarioManager:
             Merged ScenarioConfig
         """
         # Start with empty config
-        merged = ScenarioConfig()
+        merged = ScenarioConfig(firmware_version=None, send_unhandled=False)
 
         # Layer in each scope (general to specific)
         # Later scopes override or merge with earlier ones

lifx_emulator/scenarios/models.py

@@ -0,0 +1,112 @@
+"""Shared domain models for LIFX emulator.
+
+This module contains Pydantic models that are used across multiple layers
+of the application (domain, API, persistence, etc.).
+"""
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class ScenarioConfig(BaseModel):
+    """Scenario configuration for testing LIFX protocol behavior.
+
+    Scenarios define testing behaviors for the emulator:
+    - Dropping specific packet types (no response)
+    - Adding response delays
+    - Sending malformed/corrupted responses
+    - Overriding firmware version
+    - Sending incomplete data
+
+    This is used by:
+    - HierarchicalScenarioManager (domain layer)
+    - API endpoints (API layer)
+    - ScenarioPersistence (persistence layer)
+    """
+
+    drop_packets: dict[int, float] = Field(
+        default_factory=dict,
+        description="Map of packet types to drop rates (0.0-1.0). "
+        "1.0 = always drop, 0.5 = drop 50%, 0.1 = drop 10%. "
+        "Example: {101: 1.0, 102: 0.6}",
+    )
+    response_delays: dict[int, float] = Field(
+        default_factory=dict,
+        description="Map of packet types to delay in seconds before responding",
+    )
+    malformed_packets: list[int] = Field(
+        default_factory=list,
+        description="List of packet types to send with truncated/corrupted payloads",
+    )
+    invalid_field_values: list[int] = Field(
+        default_factory=list,
+        description="List of packet types to send with all 0xFF bytes in fields",
+    )
+    firmware_version: tuple[int, int] | None = Field(
+        None, description="Override firmware version (major, minor). Example: [3, 70]"
+    )
+    partial_responses: list[int] = Field(
+        default_factory=list,
+        description="List of packet types to send with incomplete data",
+    )
+    send_unhandled: bool = Field(
+        False, description="Send unhandled message responses for unknown packet types"
+    )
+
+    @field_validator("drop_packets", mode="before")
+    @classmethod
+    def convert_drop_packets_keys(cls, v):
+        """Convert string keys to integers for drop_packets.
+
+        This allows JSON serialization where keys must be strings,
+        but internally we use integer packet types.
+        """
+        if isinstance(v, dict):
+            return {int(k): float(val) for k, val in v.items()}
+        return v
+
+    @field_validator("response_delays", mode="before")
+    @classmethod
+    def convert_response_delays_keys(cls, v):
+        """Convert string keys to integers for response_delays.
+
+        This allows JSON serialization where keys must be strings,
+        but internally we use integer packet types.
+        """
+        if isinstance(v, dict):
+            return {int(k): float(val) for k, val in v.items()}
+        return v
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ScenarioConfig":
+        """Create from dictionary (backward compatibility wrapper).
+
+        Note: This wraps Pydantic's .model_validate() for backward compatibility.
+        The field_validators automatically handle string-to-int key conversion.
+
+        Args:
+            data: Dictionary with scenario configuration
+
+        Returns:
+            ScenarioConfig instance
+        """
+        return cls.model_validate(data)
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization.
+
+        Note: Pydantic models have .model_dump() which does this,
+        but we keep this method for backward compatibility with
+        existing code that expects string keys for packet types.
+
+        Returns:
+            Dictionary with string keys for drop_packets and response_delays
+        """
+        return {
+            "drop_packets": {str(k): v for k, v in self.drop_packets.items()},
+            "response_delays": {str(k): v for k, v in self.response_delays.items()},
+            "malformed_packets": self.malformed_packets,
+            "invalid_field_values": self.invalid_field_values,
+            "firmware_version": self.firmware_version,
+            "partial_responses": self.partial_responses,
+            "send_unhandled": self.send_unhandled,
+        }