conson-xp 1.1.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

xp/services/homekit/homekit_config_validator.py

@@ -1,3 +1,8 @@
+"""HomeKit Configuration Validator.
+
+This module validates HomeKit configuration files for correctness and consistency.
+"""
+
 from contextlib import suppress
 from typing import List, Set
 
@@ -9,10 +14,19 @@ class HomekitConfigValidator:
     """Validates homekit.yml configuration file for HomeKit integration."""
 
     def __init__(self, config: HomekitConfig):
+        """Initialize the HomeKit config validator.
+
+        Args:
+            config: HomeKit configuration to validate.
+        """
         self.config = config
 
     def validate_unique_accessory_names(self) -> List[str]:
-        """Validate that all accessory names are unique."""
+        """Validate that all accessory names are unique.
+
+        Returns:
+            List of validation error messages.
+        """
         names: Set[str] = set()
         errors = []
 
@@ -24,10 +38,19 @@ class HomekitConfigValidator:
         return errors
 
     def validate_service_types(self) -> List[str]:
-        """Validate that service types are valid."""
+        """Validate that service types are valid.
+
+        Returns:
+            List of validation error messages.
+        """
         valid_services = {"lightbulb", "outlet", "dimminglight"}
         errors = [
-            f"Invalid service type '{accessory.service}' for accessory '{accessory.name}'. Valid types: {', '.join(valid_services)}"
+            (
+                f"Invalid "
+                f"service type '{accessory.service}' "
+                f"for accessory '{accessory.name}'. "
+                f"Valid types: {', '.join(valid_services)}"
+            )
             for accessory in self.config.accessories
             if accessory.service not in valid_services
         ]
@@ -35,7 +58,11 @@ class HomekitConfigValidator:
         return errors
 
     def validate_output_numbers(self) -> List[str]:
-        """Validate that output numbers are positive integers."""
+        """Validate that output numbers are positive integers.
+
+        Returns:
+            List of validation error messages.
+        """
         errors = [
             f"Invalid output number {accessory.output_number} for accessory '{accessory.name}'. Must be positive."
             for accessory in self.config.accessories
@@ -45,7 +72,11 @@ class HomekitConfigValidator:
         return errors
 
     def validate_unique_room_names(self) -> List[str]:
-        """Validate that all room names are unique."""
+        """Validate that all room names are unique.
+
+        Returns:
+            List of validation error messages.
+        """
         names: Set[str] = set()
         errors = []
 
@@ -57,7 +88,11 @@ class HomekitConfigValidator:
         return errors
 
     def validate_room_accessory_references(self) -> List[str]:
-        """Validate that all room accessories exist in accessories section."""
+        """Validate that all room accessories exist in accessories section.
+
+        Returns:
+            List of validation error messages.
+        """
         accessory_names = {acc.name for acc in self.config.accessories}
         errors = []
 
@@ -71,7 +106,11 @@ class HomekitConfigValidator:
         return errors
 
     def validate_no_orphaned_accessories(self) -> List[str]:
-        """Validate that all accessories are assigned to at least one room."""
+        """Validate that all accessories are assigned to at least one room.
+
+        Returns:
+            List of validation error messages.
+        """
         assigned_accessories: Set[str] = set()
         for room in self.config.bridge.rooms:
             assigned_accessories.update(room.accessories)
@@ -85,7 +124,11 @@ class HomekitConfigValidator:
         return errors
 
     def validate_no_duplicate_accessory_assignments(self) -> List[str]:
-        """Validate that accessories are not assigned to multiple rooms."""
+        """Validate that accessories are not assigned to multiple rooms.
+
+        Returns:
+            List of validation error messages.
+        """
         assigned_accessories: Set[str] = set()
         errors = []
 
@@ -100,7 +143,11 @@ class HomekitConfigValidator:
         return errors
 
     def validate_all(self) -> List[str]:
-        """Run all validations and return combined errors."""
+        """Run all validations and return combined errors.
+
+        Returns:
+            List of all validation error messages.
+        """
         all_errors = []
         all_errors.extend(self.validate_unique_accessory_names())
         all_errors.extend(self.validate_service_types())
@@ -120,11 +167,21 @@ class CrossReferenceValidator:
         conson_validator: ConsonConfigValidator,
         homekit_validator: HomekitConfigValidator,
     ):
+        """Initialize the cross-reference validator.
+
+        Args:
+            conson_validator: Conson configuration validator.
+            homekit_validator: HomeKit configuration validator.
+        """
         self.conson_validator = conson_validator
         self.homekit_validator = homekit_validator
 
     def validate_serial_number_references(self) -> List[str]:
-        """Validate that all accessory serial numbers exist in conson configuration."""
+        """Validate that all accessory serial numbers exist in conson configuration.
+
+        Returns:
+            List of validation error messages.
+        """
         conson_serials = self.conson_validator.get_all_serial_numbers()
         errors = [
             f"Accessory '{accessory.name}' references unknown serial number {accessory.serial_number}"
@@ -135,7 +192,11 @@ class CrossReferenceValidator:
         return errors
 
     def validate_output_capabilities(self) -> List[str]:
-        """Validate that output numbers are within module capabilities."""
+        """Validate that output numbers are within module capabilities.
+
+        Returns:
+            List of validation error messages.
+        """
         errors = []
 
         for accessory in self.homekit_validator.config.accessories:
@@ -162,13 +223,20 @@ class CrossReferenceValidator:
 
                 if accessory.output_number > max_outputs:
                     errors.append(
-                        f"Accessory '{accessory.name}' output {accessory.output_number} exceeds module '{module.name}' ({module.module_type}) limit of {max_outputs}"
+                        f"Accessory '{accessory.name}' "
+                        f"output {accessory.output_number} "
+                        f"exceeds module '{module.name}' ({module.module_type}) "
+                        f"limit of {max_outputs}"
                     )
 
         return errors
 
     def validate_all(self) -> List[str]:
-        """Run all cross-reference validations and return combined errors."""
+        """Run all cross-reference validations and return combined errors.
+
+        Returns:
+            List of all cross-reference validation error messages.
+        """
         all_errors = []
         all_errors.extend(self.validate_serial_number_references())
         all_errors.extend(self.validate_output_capabilities())
@@ -179,6 +247,12 @@ class ConfigValidationService:
     """Main service for validating HomeKit configuration coherence."""
 
     def __init__(self, conson_config_path: str, homekit_config_path: str):
+        """Initialize the config validation service.
+
+        Args:
+            conson_config_path: Path to conson.yml configuration file.
+            homekit_config_path: Path to homekit.yml configuration file.
+        """
         from xp.models.homekit.homekit_config import HomekitConfig
         from xp.models.homekit.homekit_conson_config import ConsonModuleListConfig
 
@@ -192,7 +266,11 @@ class ConfigValidationService:
         )
 
     def validate_all(self) -> dict:
-        """Run all validations and return organized results."""
+        """Run all validations and return organized results.
+
+        Returns:
+            Dictionary containing validation results and error counts.
+        """
         conson_errors = self.conson_validator.validate_all()
         homekit_errors = self.homekit_validator.validate_all()
         cross_errors = self.cross_validator.validate_all()
@@ -209,7 +287,11 @@ class ConfigValidationService:
         }
 
     def print_config_summary(self) -> str:
-        """Generate a summary of the configuration."""
+        """Generate a summary of the configuration.
+
+        Returns:
+            String containing configuration summary.
+        """
         summary = [
             f"Conson Modules: {len(self.conson_config.root)}",
             f"HomeKit Accessories: {len(self.homekit_config.accessories)}",

xp/services/homekit/homekit_conson_validator.py

@@ -1,3 +1,8 @@
+"""Conson Configuration Validator for HomeKit.
+
+This module validates conson.yml configuration files for HomeKit integration.
+"""
+
 from typing import List, Set
 
 from xp.models.homekit.homekit_conson_config import (
@@ -10,10 +15,19 @@ class ConsonConfigValidator:
     """Validates conson.yml configuration file for HomeKit integration."""
 
     def __init__(self, config: ConsonModuleListConfig):
+        """Initialize the Conson config validator.
+
+        Args:
+            config: Conson module list configuration to validate.
+        """
         self.config = config
 
     def validate_unique_names(self) -> List[str]:
-        """Validate that all module names are unique."""
+        """Validate that all module names are unique.
+
+        Returns:
+            List of validation error messages.
+        """
         names: Set[str] = set()
         errors = []
 
@@ -25,7 +39,11 @@ class ConsonConfigValidator:
         return errors
 
     def validate_unique_serial_numbers(self) -> List[str]:
-        """Validate that all serial numbers are unique."""
+        """Validate that all serial numbers are unique.
+
+        Returns:
+            List of validation error messages.
+        """
         serials: Set[str] = set()
         errors = []
 
@@ -37,7 +55,11 @@ class ConsonConfigValidator:
         return errors
 
     def validate_module_type_codes(self) -> List[str]:
-        """Validate module type code ranges."""
+        """Validate module type code ranges.
+
+        Returns:
+            List of validation error messages.
+        """
         errors = [
             f"Invalid module_type_code {module.module_type_code} for module {module.name}. Must be between 1 and 255."
             for module in self.config.root
@@ -47,7 +69,11 @@ class ConsonConfigValidator:
         return errors
 
     def validate_network_config(self) -> List[str]:
-        """Validate IP/port configuration."""
+        """Validate IP/port configuration.
+
+        Returns:
+            List of validation error messages.
+        """
         errors = [
             f"Invalid conbus_port {module.conbus_port} for module {module.name}. Must be between 1 and 65535."
             for module in self.config.root
@@ -57,7 +83,11 @@ class ConsonConfigValidator:
         return errors
 
     def validate_all(self) -> List[str]:
-        """Run all validations and return combined errors."""
+        """Run all validations and return combined errors.
+
+        Returns:
+            List of all validation error messages.
+        """
         all_errors = []
         all_errors.extend(self.validate_unique_names())
         all_errors.extend(self.validate_unique_serial_numbers())
@@ -66,12 +96,26 @@ class ConsonConfigValidator:
         return all_errors
 
     def get_module_by_serial(self, serial_number: str) -> ConsonModuleConfig:
-        """Get module configuration by serial number."""
+        """Get module configuration by serial number.
+
+        Args:
+            serial_number: Serial number of the module to find.
+
+        Returns:
+            Module configuration for the specified serial number.
+
+        Raises:
+            ValueError: If module with serial number is not found.
+        """
         for module in self.config.root:
             if module.serial_number == serial_number:
                 return module
         raise ValueError(f"Module with serial number {serial_number} not found")
 
     def get_all_serial_numbers(self) -> Set[str]:
-        """Get all serial numbers from the configuration."""
+        """Get all serial numbers from the configuration.
+
+        Returns:
+            Set of all serial numbers in the configuration.
+        """
         return {module.serial_number for module in self.config.root}

xp/services/homekit/homekit_dimminglight.py

@@ -1,3 +1,8 @@
+"""HomeKit Dimming Light Accessory.
+
+This module provides a dimming light accessory for HomeKit integration.
+"""
+
 import logging
 
 from bubus import EventBus
@@ -16,7 +21,20 @@ from xp.models.protocol.conbus_protocol import (
 
 
 class DimmingLight(Accessory):
-    """Fake lightbulb, logs what the client sets."""
+    """HomeKit dimming light accessory.
+
+    Attributes:
+        category: HomeKit category (CATEGORY_LIGHTBULB).
+        event_bus: Event bus for inter-service communication.
+        logger: Logger instance.
+        identifier: Unique identifier for the accessory.
+        accessory: Accessory configuration.
+        module: Module configuration.
+        is_on: Current on/off state.
+        brightness: Current brightness level (0-100).
+        char_on: On characteristic.
+        char_brightness: Brightness characteristic.
+    """
 
     category = CATEGORY_LIGHTBULB
     event_bus: EventBus
@@ -28,6 +46,14 @@ class DimmingLight(Accessory):
         accessory: HomekitAccessoryConfig,
         event_bus: EventBus,
     ):
+        """Initialize the dimming light accessory.
+
+        Args:
+            driver: HAP accessory driver.
+            module: Module configuration.
+            accessory: Accessory configuration.
+            event_bus: Event bus for inter-service communication.
+        """
         super().__init__(driver, accessory.description)
 
         self.logger = logging.getLogger(__name__)
@@ -76,6 +102,11 @@ class DimmingLight(Accessory):
         )
 
     def set_on(self, value: bool) -> None:
+        """Set the on/off state of the dimming light.
+
+        Args:
+            value: True to turn on, False to turn off.
+        """
         # Emit set event
         self.logger.debug(f"set_on {value}")
 
@@ -93,6 +124,11 @@ class DimmingLight(Accessory):
             )
 
     def get_on(self) -> bool:
+        """Get the on/off state of the dimming light.
+
+        Returns:
+            True if on, False if off.
+        """
         # Emit event and get response
         self.logger.debug("get_on")
 
@@ -108,6 +144,11 @@ class DimmingLight(Accessory):
         return self.is_on
 
     def set_brightness(self, value: int) -> None:
+        """Set the brightness level of the dimming light.
+
+        Args:
+            value: Brightness level (0-100).
+        """
         self.logger.debug(f"set_brightness {value}")
         self.brightness = value
 
@@ -122,6 +163,11 @@ class DimmingLight(Accessory):
         )
 
     def get_brightness(self) -> int:
+        """Get the brightness level of the dimming light.
+
+        Returns:
+            Current brightness level (0-100).
+        """
         self.logger.debug("get_brightness")
 
         # Dispatch event from HAP thread (thread-safe)

xp/services/homekit/homekit_dimminglight_service.py

@@ -1,3 +1,8 @@
+"""HomeKit Dimming Light Service.
+
+This module provides service implementation for dimming light accessories.
+"""
+
 import logging
 
 from bubus import EventBus
@@ -14,12 +19,21 @@ from xp.models.telegram.datapoint_type import DataPointType
 
 
 class HomeKitDimmingLightService:
-    """Dimming light service for HomeKit"""
+    """Dimming light service for HomeKit.
+
+    Attributes:
+        event_bus: Event bus for inter-service communication.
+        logger: Logger instance.
+    """
 
     event_bus: EventBus
 
     def __init__(self, event_bus: EventBus) -> None:
+        """Initialize the dimming light service.
 
+        Args:
+            event_bus: Event bus instance.
+        """
         self.logger = logging.getLogger(__name__)
         self.event_bus = event_bus
 
@@ -34,6 +48,11 @@ class HomeKitDimmingLightService:
         )
 
     def handle_dimminglight_get_on(self, event: DimmingLightGetOnEvent) -> None:
+        """Handle dimming light get on event.
+
+        Args:
+            event: Dimming light get on event.
+        """
         self.logger.info(
             f"Getting dimming light state for serial {event.serial_number}, output {event.output_number}"
         )
@@ -48,6 +67,11 @@ class HomeKitDimmingLightService:
         self.logger.debug(f"Dispatched ReadDatapointEvent for {event.serial_number}")
 
     def handle_dimminglight_set_on(self, event: DimmingLightSetOnEvent) -> None:
+        """Handle dimming light set on event.
+
+        Args:
+            event: Dimming light set on event.
+        """
         brightness = event.brightness if event.value else 0
         self.logger.debug(
             f"Setting on light for "
@@ -74,6 +98,11 @@ class HomeKitDimmingLightService:
     def handle_dimminglight_set_brightness(
         self, event: DimmingLightSetBrightnessEvent
     ) -> None:
+        """Handle dimming light set brightness event.
+
+        Args:
+            event: Dimming light set brightness event.
+        """
         self.logger.info(
             f"Setting dimming light brightness"
             f"serial {event.serial_number}, "
@@ -97,6 +126,11 @@ class HomeKitDimmingLightService:
     def handle_dimminglight_get_brightness(
         self, event: DimmingLightGetBrightnessEvent
     ) -> None:
+        """Handle dimming light get brightness event.
+
+        Args:
+            event: Dimming light get brightness event.
+        """
         self.logger.info(
             f"Getting dimming light brightness "
             f"for serial {event.serial_number}, "

xp/services/homekit/homekit_hap_service.py

@@ -1,3 +1,8 @@
+"""HomeKit HAP Service for Apple HomeKit integration.
+
+This module provides the main HAP (HomeKit Accessory Protocol) service.
+"""
+
 import logging
 import signal
 import threading
@@ -30,11 +35,20 @@ from xp.services.homekit.homekit_outlet import Outlet
 
 
 class HomekitHapService:
-    """
-    HomeKit services.
-
-    Manages TCP socket connections, handles telegram generation and transmission,
-    and processes server responses.
+    """HomeKit HAP service.
+
+    Manages HAP accessory protocol, handles bridge and accessory setup,
+    and processes HomeKit events for device state synchronization.
+
+    Attributes:
+        event_bus: Event bus for inter-service communication.
+        last_activity: Timestamp of last service activity.
+        logger: Logger instance.
+        config: HomeKit configuration.
+        accessory_registry: Registry of accessories by identifier.
+        module_registry: Registry of accessories by module key.
+        modules: Module service for module lookup.
+        driver: HAP accessory driver.
     """
 
     event_bus: EventBus
@@ -45,12 +59,12 @@ class HomekitHapService:
         module_service: HomekitModuleService,
         event_bus: EventBus,
     ):
-        """Initialize the Conbus client send service
+        """Initialize the HomeKit HAP service.
 
         Args:
-            homekit_config: Conson configuration file
-            module_service: HomekitModuleService for dependency injection
-            event_bus: EventBus for dependency injection
+            homekit_config: HomeKit configuration.
+            module_service: Module service for dependency injection.
+            event_bus: Event bus for dependency injection.
         """
         self.last_activity: Optional[datetime] = None
 
@@ -82,13 +96,13 @@ class HomekitHapService:
         self.driver: AccessoryDriver = driver
 
     async def async_start(self) -> None:
-        """Get current client configuration"""
-        self.logger.info("Loading accessories...")
+        """Start the HAP service asynchronously."""
+        self.logger.info("Loading accessories.")
         self.build_bridge()
         self.logger.info("Accessories loaded successfully")
 
         # Start HAP-python in a separate thread to avoid event loop conflicts
-        self.logger.info("Starting HAP-python driver in separate thread...")
+        self.logger.info("Starting HAP-python driver in separate thread.")
         hap_thread = threading.Thread(
             target=self._run_driver_in_thread, daemon=True, name="HAP-Python"
         )
@@ -96,19 +110,26 @@ class HomekitHapService:
         self.logger.info("HAP-python driver thread started")
 
     def _run_driver_in_thread(self) -> None:
-        """Run the HAP-python driver in a separate thread with its own event loop"""
+        """Run the HAP-python driver in a separate thread with its own event loop."""
         try:
-            self.logger.info("HAP-python thread starting, creating new event loop...")
+            self.logger.info("HAP-python thread starting, creating new event loop.")
             # Create a new event loop for this thread
 
-            self.logger.info("Starting HAP-python driver...")
+            self.logger.info("Starting HAP-python driver.")
             self.driver.start()
             self.logger.info("HAP-python driver started successfully")
         except Exception as e:
             self.logger.error(f"HAP-python driver error: {e}", exc_info=True)
 
     def handle_output_state_received(self, event: OutputStateReceivedEvent) -> str:
+        """Handle output state received event.
+
+        Args:
+            event: Output state received event.
 
+        Returns:
+            Data value from the event.
+        """
         self.logger.debug(f"Received OutputStateReceivedEvent {event}")
         output_number = 0
         for output in event.data_value[::-1]:
@@ -131,7 +152,14 @@ class HomekitHapService:
         return event.data_value
 
     def handle_light_level_received(self, event: LightLevelReceivedEvent) -> str:
+        """Handle light level received event.
+
+        Args:
+            event: Light level received event.
 
+        Returns:
+            Data value from the event.
+        """
         # Parse response format like "00:050,01:025,02:100"
         self.logger.debug("Received LightLevelReceivedEvent", extra={"event": event})
         output_number = 0
@@ -165,6 +193,7 @@ class HomekitHapService:
         return event.data_value
 
     def build_bridge(self) -> None:
+        """Build the HomeKit bridge with all configured accessories."""
         bridge_config = self.config.bridge
         bridge = Bridge(self.driver, bridge_config.name)
         bridge.set_info_service(
@@ -177,7 +206,12 @@ class HomekitHapService:
         self.driver.add_accessory(accessory=bridge)
 
     def add_room(self, bridge: Bridge, room: RoomConfig) -> None:
-        """Call this method to get a Bridge instead of a standalone accessory."""
+        """Add a room with its accessories to the bridge.
+
+        Args:
+            bridge: HAP bridge instance.
+            room: Room configuration.
+        """
         temperature = TemperatureSensor(self.driver, room.name)
         bridge.add_accessory(temperature)
 
@@ -205,7 +239,14 @@ class HomekitHapService:
     def get_accessory(
         self, homekit_accessory: HomekitAccessoryConfig
     ) -> Union[LightBulb, Outlet, DimmingLight, None]:
-        """Call this method to get a standalone Accessory."""
+        """Get an accessory instance from configuration.
+
+        Args:
+            homekit_accessory: HomeKit accessory configuration.
+
+        Returns:
+            Accessory instance or None if not found or invalid service type.
+        """
         module_config = self.modules.get_module_by_serial(
             homekit_accessory.serial_number
         )
@@ -241,12 +282,24 @@ class HomekitHapService:
         return None
 
     def get_accessory_by_name(self, name: str) -> Optional[HomekitAccessoryConfig]:
+        """Get an accessory configuration by name.
+
+        Args:
+            name: Name of the accessory to find.
+
+        Returns:
+            Accessory configuration if found, None otherwise.
+        """
         return next(
             (module for module in self.config.accessories if module.name == name), None
         )
 
     def handle_module_state_changed(self, event: ModuleStateChangedEvent) -> None:
-        """Handle module state change by refreshing affected accessories"""
+        """Handle module state change by refreshing affected accessories.
+
+        Args:
+            event: Module state changed event.
+        """
         self.logger.debug(
             f"Module state changed: module_type={event.module_type_code}, "
             f"link={event.link_number}, input={event.input_number}"