conson-xp 1.0.1__py3-none-any.whl → 1.2.0__py3-none-any.whl

xp/services/conbus/conbus_scan_service.py

@@ -1,7 +1,7 @@
 """Conbus Scan Service for TCP communication with Conbus servers.
 
-This service implements a TCP client that scan a Conbus servers and sends
-various types of telegrams including discover, version, and sensor data requests.
+This service implements a TCP client that scans Conbus servers and sends
+telegrams to scan modules for all datapoints by function code.
 """
 
 import logging
@@ -20,10 +20,10 @@ from xp.services.protocol import ConbusProtocol
 
 class ConbusScanService(ConbusProtocol):
     """
-    Service for querying datapoints from Conbus modules.
+    Service for scanning modules for all datapoints by function code.
 
-    Uses ConbusProtocol to provide datapoint query functionality
-    for reading sensor data and module information.
+    Uses ConbusProtocol to provide scan functionality for discovering
+    all available datapoints on a module.
     """
 
     def __init__(
@@ -31,7 +31,12 @@ class ConbusScanService(ConbusProtocol):
         cli_config: ConbusClientConfig,
         reactor: PosixReactorBase,
     ) -> None:
-        """Initialize the Conbus datapoint service"""
+        """Initialize the Conbus scan service.
+
+        Args:
+            cli_config: Conbus client configuration.
+            reactor: Twisted reactor instance.
+        """
         super().__init__(cli_config, reactor)
         self.serial_number: str = ""
         self.function_code: str = ""
@@ -49,10 +54,16 @@ class ConbusScanService(ConbusProtocol):
         self.logger = logging.getLogger(__name__)
 
     def connection_established(self) -> None:
+        """Handle connection established event."""
         self.logger.debug("Connection established, starting scan")
         self.scan_next_datacode()
 
     def scan_next_datacode(self) -> bool:
+        """Scan the next data code.
+
+        Returns:
+            True if scanning should continue, False if complete.
+        """
         self.datapoint_value += 1
         if self.datapoint_value >= 100:
             if self.finish_callback:
@@ -66,10 +77,20 @@ class ConbusScanService(ConbusProtocol):
         return True
 
     def telegram_sent(self, telegram_sent: str) -> None:
+        """Handle telegram sent event.
+
+        Args:
+            telegram_sent: The telegram that was sent.
+        """
         self.service_response.success = True
         self.service_response.sent_telegrams.append(telegram_sent)
 
     def telegram_received(self, telegram_received: TelegramReceivedEvent) -> None:
+        """Handle telegram received event.
+
+        Args:
+            telegram_received: The telegram received event.
+        """
         self.logger.debug(f"Telegram received: {telegram_received}")
         if not self.service_response.received_telegrams:
             self.service_response.received_telegrams = []
@@ -79,11 +100,21 @@ class ConbusScanService(ConbusProtocol):
             self.progress_callback(telegram_received.frame)
 
     def timeout(self) -> bool:
+        """Handle timeout event by scanning next data code.
+
+        Returns:
+            True to continue scanning, False to stop.
+        """
         self.logger.debug(f"Timeout: {self.timeout_seconds}s")
         continue_scan = self.scan_next_datacode()
         return continue_scan
 
     def failed(self, message: str) -> None:
+        """Handle failed connection event.
+
+        Args:
+            message: Failure message.
+        """
         self.logger.debug(f"Failed with message: {message}")
         self.service_response.success = False
         self.service_response.timestamp = datetime.now()
@@ -91,7 +122,7 @@ class ConbusScanService(ConbusProtocol):
         if self.finish_callback:
             self.finish_callback(self.service_response)
 
-    def scan_module_background(
+    def scan_module(
         self,
         serial_number: str,
         function_code: str,
@@ -99,21 +130,16 @@ class ConbusScanService(ConbusProtocol):
         finish_callback: Callable[[ConbusResponse], None],
         timeout_seconds: Optional[float] = None,
     ) -> None:
-        """
-        Query a specific datapoint from a module.
+        """Scan a module for all datapoints by function code.
 
         Args:
-            serial_number: 10-digit module serial number
-            function_code: the function code to scan
-            progress_callback: callback to handle progress
-            finish_callback: callback function to call when the datapoint is received
-            timeout_seconds: timeout in seconds
-
-        Returns:
-            ConbusDatapointResponse with operation result and datapoint value
+            serial_number: 10-digit module serial number.
+            function_code: The function code to scan.
+            progress_callback: Callback to handle progress.
+            finish_callback: Callback function to call when the scan is complete.
+            timeout_seconds: Timeout in seconds.
         """
-
-        self.logger.info("Starting query_datapoint")
+        self.logger.info("Starting scan_module")
         if timeout_seconds:
             self.timeout_seconds = timeout_seconds
 

xp/services/homekit/__init__.py

@@ -0,0 +1 @@
+"""HomeKit integration services."""

xp/services/homekit/homekit_cache_service.py

@@ -22,7 +22,12 @@ CACHE_FILE = CACHE_DIR / "homekit_cache.json"
 
 
 class CacheEntry(TypedDict):
-    """Cache entry type definition."""
+    """Cache entry type definition.
+
+    Attributes:
+        event: The cached event (OutputStateReceivedEvent or LightLevelReceivedEvent).
+        timestamp: When the event was cached.
+    """
 
     event: Union[OutputStateReceivedEvent, LightLevelReceivedEvent]
     timestamp: datetime
@@ -39,6 +44,12 @@ class HomeKitCacheService:
     """
 
     def __init__(self, event_bus: EventBus, enable_persistence: bool = True):
+        """Initialize the HomeKit cache service.
+
+        Args:
+            event_bus: Event bus for inter-service communication.
+            enable_persistence: Whether to persist cache to disk.
+        """
         self.logger = logging.getLogger(__name__)
         self.event_bus = event_bus
         self.cache: dict[tuple[str, DataPointType], CacheEntry] = {}
@@ -192,12 +203,14 @@ class HomeKitCacheService:
         return None
 
     def handle_read_datapoint_event(self, event: ReadDatapointEvent) -> None:
-        """
-        Handle ReadDatapointEvent by checking cache or refresh flag.
+        """Handle ReadDatapointEvent by checking cache or refresh flag.
 
         On refresh_cache=True: invalidate cache and force protocol query
         On cache hit: dispatch cached response event
         On cache miss: forward to protocol via ReadDatapointFromProtocolEvent
+
+        Args:
+            event: Read datapoint event with serial number, datapoint type, and refresh flag.
         """
         self.logger.debug(
             f"Handling ReadDatapointEvent: "
@@ -250,7 +263,11 @@ class HomeKitCacheService:
     def handle_output_state_received_event(
         self, event: OutputStateReceivedEvent
     ) -> None:
-        """Cache OutputStateReceivedEvent for future queries."""
+        """Cache OutputStateReceivedEvent for future queries.
+
+        Args:
+            event: Output state received event to cache.
+        """
         self.logger.debug(
             f"Caching OutputStateReceivedEvent: "
             f"serial={event.serial_number}, "
@@ -260,7 +277,11 @@ class HomeKitCacheService:
         self._cache_event(event)
 
     def handle_light_level_received_event(self, event: LightLevelReceivedEvent) -> None:
-        """Cache LightLevelReceivedEvent for future queries."""
+        """Cache LightLevelReceivedEvent for future queries.
+
+        Args:
+            event: Light level received event to cache.
+        """
         self.logger.debug(
             f"Caching LightLevelReceivedEvent: "
             f"serial={event.serial_number}, "
@@ -276,7 +297,11 @@ class HomeKitCacheService:
         self._save_cache()
 
     def get_cache_stats(self) -> dict[str, int]:
-        """Get cache statistics."""
+        """Get cache statistics.
+
+        Returns:
+            Dictionary with cache statistics including total_entries.
+        """
         return {
             "total_entries": len(self.cache),
         }

xp/services/homekit/homekit_conbus_service.py

@@ -1,3 +1,8 @@
+"""HomeKit Conbus Service for protocol communication.
+
+This module bridges HomeKit events with the Conbus protocol for device control.
+"""
+
 import logging
 
 from bubus import EventBus
@@ -14,11 +19,23 @@ from xp.services.protocol.telegram_protocol import TelegramProtocol
 
 
 class HomeKitConbusService:
-    """homeKitConbusService"""
+    """Service for bridging HomeKit events with Conbus protocol.
+
+    Attributes:
+        event_bus: Event bus for inter-service communication.
+        telegram_protocol: Protocol for sending telegrams.
+        logger: Logger instance.
+    """
 
     event_bus: EventBus
 
     def __init__(self, event_bus: EventBus, telegram_protocol: TelegramProtocol):
+        """Initialize the HomeKit Conbus service.
+
+        Args:
+            event_bus: Event bus instance.
+            telegram_protocol: Telegram protocol instance.
+        """
         self.logger = logging.getLogger(__name__)
         self.event_bus = event_bus
         self.telegram_protocol = telegram_protocol
@@ -33,7 +50,11 @@ class HomeKitConbusService:
     def handle_read_datapoint_request(
         self, event: ReadDatapointFromProtocolEvent
     ) -> None:
-        """Handle request to read datapoint from protocol."""
+        """Handle request to read datapoint from protocol.
+
+        Args:
+            event: Read datapoint event with serial number and datapoint type.
+        """
         self.logger.debug(f"read_datapoint_request {event}")
 
         system_function = SystemFunction.READ_DATAPOINT.value
@@ -42,6 +63,11 @@ class HomeKitConbusService:
         self.telegram_protocol.sendFrame(telegram.encode())
 
     def handle_send_write_config_event(self, event: SendWriteConfigEvent) -> None:
+        """Handle send write config event.
+
+        Args:
+            event: Write config event with configuration data.
+        """
         self.logger.debug(f"send_write_config_event {event}")
 
         # Format data as output_number:level (e.g., "02:050")
@@ -54,6 +80,11 @@ class HomeKitConbusService:
         self.telegram_protocol.sendFrame(telegram.encode())
 
     def handle_send_action_event(self, event: SendActionEvent) -> None:
+        """Handle send action event.
+
+        Args:
+            event: Send action event with action data.
+        """
         self.logger.debug(f"send_action_event {event}")
 
         action_value = (

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}