lifx-emulator 2.3.1__py3-none-any.whl → 3.0.1__py3-none-any.whl

lifx_emulator/scenarios/manager.py

@@ -1,322 +0,0 @@
-"""Hierarchical scenario management for testing LIFX protocol behavior.
-
-This module provides a flexible scenario system that allows configuring
-test scenarios at multiple scopes with precedence-based resolution.
-"""
-
-import random
-from typing import TYPE_CHECKING
-
-from lifx_emulator.scenarios.models import ScenarioConfig
-
-if TYPE_CHECKING:
-    from lifx_emulator.devices import EmulatedLifxDevice
-
-
-def get_device_type(device: "EmulatedLifxDevice") -> str:
-    """Get device type identifier for scenario scoping.
-
-    Args:
-        device: EmulatedLifxDevice instance
-
-    Returns:
-        Device type string (matrix, extended_multizone, multizone,
-        hev, infrared, color, or basic)
-    """
-    if device.state.has_matrix:
-        return "matrix"
-    elif device.state.has_extended_multizone:
-        return "extended_multizone"
-    elif device.state.has_multizone:
-        return "multizone"
-    elif device.state.has_hev:
-        return "hev"
-    elif device.state.has_infrared:
-        return "infrared"
-    elif device.state.has_color:
-        return "color"
-    else:
-        return "basic"
-
-
-class HierarchicalScenarioManager:
-    """Manages scenarios across multiple scopes with precedence resolution.
-
-    Supports 5 scope levels with precedence (specific to general):
-    1. Device-specific (by serial) - Highest priority
-    2. Device-type specific (by capability: color, multizone, matrix, etc.)
-    3. Location-specific (all devices in location)
-    4. Group-specific (all devices in group)
-    5. Global (all emulated devices) - Lowest priority
-
-    When resolving scenarios for a device, configurations from all applicable
-    scopes are merged using union semantics for lists and override semantics
-    for scalars.
-    """
-
-    def __init__(self):
-        # Scenario storage by scope
-        self.device_scenarios: dict[str, ScenarioConfig] = {}  # serial → config
-        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(
-            firmware_version=None, send_unhandled=False
-        )
-
-    def set_device_scenario(self, serial: str, config: ScenarioConfig):
-        """Set scenario for specific device by serial."""
-        self.device_scenarios[serial] = config
-
-    def set_type_scenario(self, device_type: str, config: ScenarioConfig):
-        """Set scenario for device type (color, multizone, matrix, etc.)."""
-        self.type_scenarios[device_type] = config
-
-    def set_location_scenario(self, location: str, config: ScenarioConfig):
-        """Set scenario for all devices in a location."""
-        self.location_scenarios[location] = config
-
-    def set_group_scenario(self, group: str, config: ScenarioConfig):
-        """Set scenario for all devices in a group."""
-        self.group_scenarios[group] = config
-
-    def set_global_scenario(self, config: ScenarioConfig):
-        """Set global scenario for all devices."""
-        self.global_scenario = config
-
-    def delete_device_scenario(self, serial: str) -> bool:
-        """Delete device-specific scenario. Returns True if existed."""
-        return self.device_scenarios.pop(serial, None) is not None
-
-    def delete_type_scenario(self, device_type: str) -> bool:
-        """Delete type-specific scenario. Returns True if existed."""
-        return self.type_scenarios.pop(device_type, None) is not None
-
-    def delete_location_scenario(self, location: str) -> bool:
-        """Delete location-specific scenario. Returns True if existed."""
-        return self.location_scenarios.pop(location, None) is not None
-
-    def delete_group_scenario(self, group: str) -> bool:
-        """Delete group-specific scenario. Returns True if existed."""
-        return self.group_scenarios.pop(group, None) is not None
-
-    def clear_global_scenario(self):
-        """Clear global scenario (reset to empty)."""
-        self.global_scenario = ScenarioConfig(
-            firmware_version=None, send_unhandled=False
-        )
-
-    def get_global_scenario(self) -> ScenarioConfig:
-        """Get global scenario configuration."""
-        return self.global_scenario
-
-    def get_device_scenario(self, serial: str) -> ScenarioConfig | None:
-        """Get device-specific scenario by serial.
-
-        Args:
-            serial: Device serial number
-
-        Returns:
-            ScenarioConfig if scenario exists, None otherwise
-        """
-        return self.device_scenarios.get(serial)
-
-    def get_type_scenario(self, device_type: str) -> ScenarioConfig | None:
-        """Get type-specific scenario.
-
-        Args:
-            device_type: Device type (color, multizone, matrix, etc.)
-
-        Returns:
-            ScenarioConfig if scenario exists, None otherwise
-        """
-        return self.type_scenarios.get(device_type)
-
-    def get_location_scenario(self, location: str) -> ScenarioConfig | None:
-        """Get location-specific scenario.
-
-        Args:
-            location: Device location label
-
-        Returns:
-            ScenarioConfig if scenario exists, None otherwise
-        """
-        return self.location_scenarios.get(location)
-
-    def get_group_scenario(self, group: str) -> ScenarioConfig | None:
-        """Get group-specific scenario.
-
-        Args:
-            group: Device group label
-
-        Returns:
-            ScenarioConfig if scenario exists, None otherwise
-        """
-        return self.group_scenarios.get(group)
-
-    def get_scenario_for_device(
-        self,
-        serial: str,
-        device_type: str,
-        location: str,
-        group: str,
-    ) -> ScenarioConfig:
-        """Resolve scenario for device with precedence.
-
-        Precedence (highest to lowest):
-        1. Device-specific
-        2. Device-type
-        3. Location
-        4. Group
-        5. Global
-
-        Returns merged configuration with most specific values taking priority.
-        Lists are merged using union (all values combined).
-        Dicts are merged with later values overriding earlier.
-        Scalars use the most specific non-None value.
-
-        Args:
-            serial: Device serial number
-            device_type: Device type (color, multizone, matrix, etc.)
-            location: Device location label
-            group: Device group label
-
-        Returns:
-            Merged ScenarioConfig
-        """
-        # Start with empty config
-        merged = ScenarioConfig(firmware_version=None, send_unhandled=False)
-
-        # Layer in each scope (general to specific)
-        # Later scopes override or merge with earlier ones
-        for config in [
-            self.global_scenario,
-            self.group_scenarios.get(group),
-            self.location_scenarios.get(location),
-            self.type_scenarios.get(device_type),
-            self.device_scenarios.get(serial),
-        ]:
-            if config is None:
-                continue
-
-            # Merge drop_packets dict (later overwrites earlier)
-            merged.drop_packets.update(config.drop_packets)
-
-            # Merge lists using union (combine all values)
-            merged.malformed_packets = list(
-                set(merged.malformed_packets + config.malformed_packets)
-            )
-            merged.invalid_field_values = list(
-                set(merged.invalid_field_values + config.invalid_field_values)
-            )
-            merged.partial_responses = list(
-                set(merged.partial_responses + config.partial_responses)
-            )
-
-            # Merge delays dict (later overwrites earlier)
-            merged.response_delays.update(config.response_delays)
-
-            # Scalars: use most specific non-default value
-            if config.firmware_version is not None:
-                merged.firmware_version = config.firmware_version
-            if config.send_unhandled:
-                merged.send_unhandled = True
-
-        return merged
-
-    def should_respond(self, packet_type: int, scenario: ScenarioConfig) -> bool:
-        """Check if device should respond to packet type.
-
-        Uses probabilistic dropping based on drop_packets configuration.
-
-        Args:
-            packet_type: LIFX packet type number
-            scenario: Resolved scenario configuration
-
-        Returns:
-            False if packet should be dropped, True otherwise
-        """
-        if packet_type not in scenario.drop_packets:
-            return True
-
-        # Get drop rate for this packet type (0.1-1.0)
-        drop_rate = scenario.drop_packets[packet_type]
-
-        # Probabilistic drop: random value [0, 1) < drop_rate means drop
-        return random.random() >= drop_rate  # nosec
-
-    def get_response_delay(self, packet_type: int, scenario: ScenarioConfig) -> float:
-        """Get response delay for packet type.
-
-        Args:
-            packet_type: LIFX packet type number
-            scenario: Resolved scenario configuration
-
-        Returns:
-            Delay in seconds (0.0 if no delay configured)
-        """
-        return scenario.response_delays.get(packet_type, 0.0)
-
-    def should_send_malformed(self, packet_type: int, scenario: ScenarioConfig) -> bool:
-        """Check if response should be malformed/truncated.
-
-        Args:
-            packet_type: LIFX packet type number
-            scenario: Resolved scenario configuration
-
-        Returns:
-            True if response should be corrupted
-        """
-        return packet_type in scenario.malformed_packets
-
-    def should_send_invalid_fields(
-        self, packet_type: int, scenario: ScenarioConfig
-    ) -> bool:
-        """Check if response should have invalid field values (all 0xFF).
-
-        Args:
-            packet_type: LIFX packet type number
-            scenario: Resolved scenario configuration
-
-        Returns:
-            True if response should have invalid fields
-        """
-        return packet_type in scenario.invalid_field_values
-
-    def get_firmware_version_override(
-        self, scenario: ScenarioConfig
-    ) -> tuple[int, int] | None:
-        """Get firmware version override if configured.
-
-        Args:
-            scenario: Resolved scenario configuration
-
-        Returns:
-            (major, minor) tuple or None
-        """
-        return scenario.firmware_version
-
-    def should_send_partial_response(
-        self, packet_type: int, scenario: ScenarioConfig
-    ) -> bool:
-        """Check if response should be partial (incomplete multizone/tile data).
-
-        Args:
-            packet_type: LIFX packet type number
-            scenario: Resolved scenario configuration
-
-        Returns:
-            True if response should be incomplete
-        """
-        return packet_type in scenario.partial_responses
-
-    def should_send_unhandled(self, scenario: ScenarioConfig) -> bool:
-        """Check if StateUnhandled should be sent for unknown packet types.
-
-        Args:
-            scenario: Resolved scenario configuration
-
-        Returns:
-            True if StateUnhandled should be sent
-        """
-        return scenario.send_unhandled

lifx_emulator/scenarios/models.py

@@ -1,112 +0,0 @@
-"""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,
-        }

lifx_emulator/scenarios/persistence.py

@@ -1,241 +0,0 @@
-"""Async persistent storage for scenario configurations.
-
-This module provides async JSON serialization and deserialization for scenarios,
-allowing them to persist across emulator restarts without blocking the event loop.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import json
-import logging
-from concurrent.futures import ThreadPoolExecutor
-from pathlib import Path
-from typing import Any
-
-from lifx_emulator.scenarios.manager import HierarchicalScenarioManager, ScenarioConfig
-
-logger = logging.getLogger(__name__)
-
-DEFAULT_STORAGE_DIR = Path.home() / ".lifx-emulator"
-
-
-class ScenarioPersistenceAsyncFile:
-    """Async persistent storage for scenario configurations.
-
-    Non-blocking asynchronous I/O for scenario persistence.
-    Scenarios are stored in JSON format at ~/.lifx-emulator/scenarios.json
-    with separate sections for each scope level.
-
-    Features:
-    - Async I/O operations (no event loop blocking)
-    - Executor-based I/O for file operations
-    - Atomic writes (write to temp file, then rename)
-    - Graceful error handling and recovery
-    """
-
-    def __init__(self, storage_path: Path | str | None = None):
-        """Initialize async scenario persistence.
-
-        Args:
-            storage_path: Directory to store scenarios.json
-                         Defaults to ~/.lifx-emulator
-        """
-        if storage_path is None:
-            storage_path = DEFAULT_STORAGE_DIR
-
-        self.storage_path = Path(storage_path)
-        self.scenario_file = self.storage_path / "scenarios.json"
-
-        # Single-thread executor for serialized I/O operations
-        self.executor = ThreadPoolExecutor(
-            max_workers=1, thread_name_prefix="scenario-io"
-        )
-
-        logger.debug("Async scenario storage initialized at %s", self.storage_path)
-
-    async def load(self) -> HierarchicalScenarioManager:
-        """Load scenarios from disk (async).
-
-        Returns:
-            HierarchicalScenarioManager with loaded scenarios.
-            If file doesn't exist, returns empty manager.
-        """
-        loop = asyncio.get_running_loop()
-        return await loop.run_in_executor(self.executor, self._sync_load)
-
-    def _sync_load(self) -> HierarchicalScenarioManager:
-        """Synchronous load operation (runs in executor).
-
-        Returns:
-            HierarchicalScenarioManager with loaded scenarios
-        """
-        manager = HierarchicalScenarioManager()
-
-        if not self.scenario_file.exists():
-            logger.debug("No scenario file found at %s", self.scenario_file)
-            return manager
-
-        try:
-            with open(self.scenario_file) as f:
-                data = json.load(f)
-
-            # Load global scenario
-            if "global" in data and data["global"]:
-                manager.global_scenario = ScenarioConfig.model_validate(data["global"])
-                logger.debug("Loaded global scenario")
-
-            # Load device-specific scenarios
-            for serial, config_data in data.get("devices", {}).items():
-                manager.device_scenarios[serial] = ScenarioConfig.model_validate(
-                    config_data
-                )
-            if manager.device_scenarios:
-                logger.debug(
-                    "Loaded %s device scenario(s)", len(manager.device_scenarios)
-                )
-
-            # Load type-specific scenarios
-            for device_type, config_data in data.get("types", {}).items():
-                manager.type_scenarios[device_type] = ScenarioConfig.model_validate(
-                    config_data
-                )
-            if manager.type_scenarios:
-                logger.debug("Loaded %s type scenario(s)", len(manager.type_scenarios))
-
-            # Load location-specific scenarios
-            for location, config_data in data.get("locations", {}).items():
-                manager.location_scenarios[location] = ScenarioConfig.model_validate(
-                    config_data
-                )
-            if manager.location_scenarios:
-                logger.debug(
-                    "Loaded %s location scenario(s)", len(manager.location_scenarios)
-                )
-
-            # Load group-specific scenarios
-            for group, config_data in data.get("groups", {}).items():
-                manager.group_scenarios[group] = ScenarioConfig.model_validate(
-                    config_data
-                )
-            if manager.group_scenarios:
-                logger.debug(
-                    "Loaded %s group scenario(s)", len(manager.group_scenarios)
-                )
-
-            logger.info("Loaded scenarios from %s", self.scenario_file)
-            return manager
-
-        except json.JSONDecodeError as e:
-            logger.error("Failed to parse scenario file %s: %s", self.scenario_file, e)
-            return manager
-        except Exception as e:
-            logger.error("Failed to load scenarios from %s: %s", self.scenario_file, e)
-            return manager
-
-    async def save(self, manager: HierarchicalScenarioManager) -> None:
-        """Save scenarios to disk (async).
-
-        Args:
-            manager: HierarchicalScenarioManager to save
-        """
-        loop = asyncio.get_running_loop()
-        await loop.run_in_executor(self.executor, self._sync_save, manager)
-
-    def _sync_save(self, manager: HierarchicalScenarioManager) -> None:
-        """Synchronous save operation (runs in executor).
-
-        Args:
-            manager: HierarchicalScenarioManager to save
-        """
-
-        # Convert response_delays keys to strings for JSON serialization
-        def _serialize_config(config: ScenarioConfig) -> dict[str, Any]:
-            """Convert ScenarioConfig to JSON-serializable dict."""
-            data = config.to_dict()
-            # Convert int keys in response_delays to strings
-            if data.get("response_delays"):
-                data["response_delays"] = {
-                    str(k): v for k, v in data["response_delays"].items()
-                }
-            return data
-
-        data: dict[str, Any] = {
-            "global": _serialize_config(manager.global_scenario),
-            "devices": {
-                serial: _serialize_config(config)
-                for serial, config in manager.device_scenarios.items()
-            },
-            "types": {
-                device_type: _serialize_config(config)
-                for device_type, config in manager.type_scenarios.items()
-            },
-            "locations": {
-                location: _serialize_config(config)
-                for location, config in manager.location_scenarios.items()
-            },
-            "groups": {
-                group: _serialize_config(config)
-                for group, config in manager.group_scenarios.items()
-            },
-        }
-
-        try:
-            # Create directory if it doesn't exist
-            self.storage_path.mkdir(parents=True, exist_ok=True)
-
-            # Write to temporary file first, then rename (atomic operation)
-            temp_file = self.scenario_file.with_suffix(".json.tmp")
-            with open(temp_file, "w") as f:
-                json.dump(data, f, indent=2)
-
-            # Atomic rename
-            temp_file.replace(self.scenario_file)
-
-            logger.info("Saved scenarios to %s", self.scenario_file)
-
-        except Exception as e:
-            logger.error("Failed to save scenarios to %s: %s", self.scenario_file, e)
-            raise
-
-    async def delete(self) -> bool:
-        """Delete the scenario file (async).
-
-        Returns:
-            True if file was deleted, False if it didn't exist
-        """
-        loop = asyncio.get_running_loop()
-        return await loop.run_in_executor(self.executor, self._sync_delete)
-
-    def _sync_delete(self) -> bool:
-        """Synchronous delete operation (runs in executor).
-
-        Returns:
-            True if file was deleted, False if it didn't exist
-        """
-        if self.scenario_file.exists():
-            try:
-                self.scenario_file.unlink()
-                logger.info("Deleted scenario file %s", self.scenario_file)
-                return True
-            except Exception as e:
-                logger.error("Failed to delete scenario file: %s", e)
-                raise
-        return False
-
-    async def shutdown(self) -> None:
-        """Gracefully shutdown executor.
-
-        This should be called before the application exits.
-        """
-        logger.info("Shutting down async scenario storage...")
-
-        # Shutdown executor (non-blocking to avoid hanging on Windows)
-        loop = asyncio.get_running_loop()
-        await loop.run_in_executor(None, self.executor.shutdown, True)
-
-        logger.info("Async scenario storage shutdown complete")
-
-
-# Note: Pydantic's field_validators in ScenarioConfig handle string-to-int
-# key conversion automatically, so no additional deserialization logic is needed.