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

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}"

xp/services/homekit/homekit_lightbulb.py

@@ -1,3 +1,8 @@
+"""HomeKit Light Bulb Accessory.
+
+This module provides a light bulb accessory for HomeKit integration.
+"""
+
 import logging
 
 from bubus import EventBus
@@ -14,7 +19,18 @@ from xp.models.protocol.conbus_protocol import (
 
 
 class LightBulb(Accessory):
-    """Fake lightbulb, logs what the client sets."""
+    """HomeKit light bulb 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.
+        char_on: On characteristic.
+    """
 
     category = CATEGORY_LIGHTBULB
     event_bus: EventBus
@@ -26,6 +42,14 @@ class LightBulb(Accessory):
         accessory: HomekitAccessoryConfig,
         event_bus: EventBus,
     ):
+        """Initialize the light bulb 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__)
@@ -56,6 +80,11 @@ class LightBulb(Accessory):
         )
 
     def set_on(self, value: bool) -> None:
+        """Set the on/off state of the light bulb.
+
+        Args:
+            value: True to turn on, False to turn off.
+        """
         # Emit set event
         self.logger.debug(f"set_on {value}")
         if self.is_on != value:
@@ -71,6 +100,11 @@ class LightBulb(Accessory):
             )
 
     def get_on(self) -> bool:
+        """Get the on/off state of the light bulb.
+
+        Returns:
+            True if on, False if off.
+        """
         # Emit event and get response
         self.logger.debug("get_on")
         self.event_bus.dispatch(

xp/services/homekit/homekit_lightbulb_service.py

@@ -1,3 +1,8 @@
+"""HomeKit Light Bulb Service.
+
+This module provides service implementation for light bulb accessories.
+"""
+
 import logging
 
 from bubus import EventBus
@@ -12,11 +17,21 @@ from xp.models.telegram.datapoint_type import DataPointType
 
 
 class HomeKitLightbulbService:
-    """Lightbulb service for HomeKit"""
+    """Lightbulb service for HomeKit.
+
+    Attributes:
+        event_bus: Event bus for inter-service communication.
+        logger: Logger instance.
+    """
 
     event_bus: EventBus
 
     def __init__(self, event_bus: EventBus):
+        """Initialize the lightbulb service.
+
+        Args:
+            event_bus: Event bus instance.
+        """
         self.event_bus = event_bus
         self.logger = logging.getLogger(__name__)
 
@@ -25,6 +40,11 @@ class HomeKitLightbulbService:
         self.event_bus.on(LightBulbSetOnEvent, self.handle_lightbulb_set_on)
 
     def handle_lightbulb_get_on(self, event: LightBulbGetOnEvent) -> None:
+        """Handle lightbulb get on event.
+
+        Args:
+            event: Lightbulb get on event.
+        """
         self.logger.info(
             f"Getting lightbulb state for serial {event.serial_number}, output {event.output_number}"
         )
@@ -40,8 +60,16 @@ class HomeKitLightbulbService:
         self.logger.debug(f"Dispatched ReadDatapointEvent for {event.serial_number}")
 
     def handle_lightbulb_set_on(self, event: LightBulbSetOnEvent) -> None:
+        """Handle lightbulb set on event.
+
+        Args:
+            event: Lightbulb set on event.
+        """
         self.logger.info(
-            f"Setting lightbulb for serial {event.serial_number}, output {event.output_number} to {'ON' if event.value else 'OFF'}"
+            f"Setting lightbulb "
+            f"for serial {event.serial_number}, "
+            f"output {event.output_number} "
+            f"to {'ON' if event.value else 'OFF'}"
         )
         self.logger.debug(f"lightbulb_set_on {event}")
 

xp/services/homekit/homekit_module_service.py

@@ -1,3 +1,8 @@
+"""HomeKit Module Service.
+
+This module provides service implementation for HomeKit module management.
+"""
+
 import logging
 from typing import Optional
 
@@ -8,18 +13,35 @@ from xp.models.homekit.homekit_conson_config import (
 
 
 class HomekitModuleService:
+    """Service for managing HomeKit module configurations.
+
+    Attributes:
+        logger: Logger instance.
+        conson_modules_config: Conson module list configuration.
+    """
 
     def __init__(
         self,
         conson_modules_config: ConsonModuleListConfig,
     ):
+        """Initialize the HomeKit module service.
 
+        Args:
+            conson_modules_config: Conson module list configuration.
+        """
         # Set up logging
         self.logger = logging.getLogger(__name__)
         self.conson_modules_config = conson_modules_config
 
     def get_module_by_serial(self, serial_number: str) -> Optional[ConsonModuleConfig]:
-        """Get a module by its serial number"""
+        """Get a module by its serial number.
+
+        Args:
+            serial_number: Serial number of the module to find.
+
+        Returns:
+            Module configuration if found, None otherwise.
+        """
         module = next(
             (
                 module

xp/services/homekit/homekit_outlet.py

@@ -1,3 +1,8 @@
+"""HomeKit Outlet Accessory.
+
+This module provides an outlet accessory for HomeKit integration.
+"""
+
 import logging
 
 from bubus import EventBus
@@ -16,7 +21,20 @@ from xp.models.protocol.conbus_protocol import (
 
 
 class Outlet(Accessory):
-    """Fake lightbulb, logs what the client sets."""
+    """HomeKit outlet accessory.
+
+    Attributes:
+        category: HomeKit category (CATEGORY_OUTLET).
+        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.
+        is_in_use: Current in-use state.
+        char_on: On characteristic.
+        char_outlet_in_use: Outlet in-use characteristic.
+    """
 
     category = CATEGORY_OUTLET
     event_bus: EventBus
@@ -28,6 +46,14 @@ class Outlet(Accessory):
         accessory: HomekitAccessoryConfig,
         event_bus: EventBus,
     ):
+        """Initialize the outlet accessory.
+
+        Args:
+            driver: HAP accessory driver.
+            module: Module configuration.
+            accessory: Accessory configuration.
+            event_bus: Event bus for inter-service communication.
+        """
         super().__init__(driver=driver, display_name=accessory.description)
 
         self.logger = logging.getLogger(__name__)
@@ -62,6 +88,11 @@ class Outlet(Accessory):
         )
 
     def set_outlet_in_use(self, value: bool) -> None:
+        """Set the in-use state of the outlet.
+
+        Args:
+            value: True if in use, False otherwise.
+        """
         self.logger.debug(f"set_outlet_in_use {value}")
 
         self.is_in_use = value
@@ -77,6 +108,11 @@ class Outlet(Accessory):
         self.logger.debug(f"set_outlet_in_use {value} end")
 
     def get_outlet_in_use(self) -> bool:
+        """Get the in-use state of the outlet.
+
+        Returns:
+            True if in use, False otherwise.
+        """
         # Emit event and get response
         self.logger.debug("get_outlet_in_use")
 
@@ -92,6 +128,11 @@ class Outlet(Accessory):
         return self.is_in_use
 
     def set_on(self, value: bool) -> None:
+        """Set the on/off state of the outlet.
+
+        Args:
+            value: True to turn on, False to turn off.
+        """
         # Emit set event
         self.logger.debug(f"set_on {value}")
 
@@ -108,6 +149,11 @@ class Outlet(Accessory):
             )
 
     def get_on(self) -> bool:
+        """Get the on/off state of the outlet.
+
+        Returns:
+            True if on, False if off.
+        """
         # Emit event and get response
         self.logger.debug("get_on")
 

xp/services/homekit/homekit_outlet_service.py

@@ -1,3 +1,8 @@
+"""HomeKit Outlet Service.
+
+This module provides service implementation for outlet accessories.
+"""
+
 import logging
 
 from bubus import EventBus
@@ -13,11 +18,21 @@ from xp.models.telegram.datapoint_type import DataPointType
 
 
 class HomeKitOutletService:
-    """Outlet service for HomeKit"""
+    """Outlet service for HomeKit.
+
+    Attributes:
+        event_bus: Event bus for inter-service communication.
+        logger: Logger instance.
+    """
 
     event_bus: EventBus
 
     def __init__(self, event_bus: EventBus):
+        """Initialize the outlet service.
+
+        Args:
+            event_bus: Event bus instance.
+        """
         self.event_bus = event_bus
         self.logger = logging.getLogger(__name__)
 
@@ -27,6 +42,14 @@ class HomeKitOutletService:
         self.event_bus.on(OutletGetInUseEvent, self.handle_outlet_get_in_use)
 
     def handle_outlet_get_on(self, event: OutletGetOnEvent) -> bool:
+        """Handle outlet get on event.
+
+        Args:
+            event: Outlet get on event.
+
+        Returns:
+            True if request was dispatched successfully.
+        """
         self.logger.debug(
             f"Getting outlet state for serial {event.serial_number}, output {event.output_number}"
         )
@@ -42,8 +65,19 @@ class HomeKitOutletService:
         return True
 
     def handle_outlet_set_on(self, event: OutletSetOnEvent) -> bool:
+        """Handle outlet set on event.
+
+        Args:
+            event: Outlet set on event.
+
+        Returns:
+            True if command was sent successfully.
+        """
         self.logger.info(
-            f"Setting outlet for serial {event.serial_number}, output {event.output_number} to {'ON' if event.value else 'OFF'}"
+            f"Setting outlet "
+            f"for serial {event.serial_number}, "
+            f"output {event.output_number} "
+            f"to {'ON' if event.value else 'OFF'}"
         )
         self.logger.debug(f"outlet_set_on {event}")
 
@@ -61,6 +95,14 @@ class HomeKitOutletService:
         return True
 
     def handle_outlet_get_in_use(self, event: OutletGetInUseEvent) -> bool:
+        """Handle outlet get in-use event.
+
+        Args:
+            event: Outlet get in-use event.
+
+        Returns:
+            True if request was dispatched successfully.
+        """
         self.logger.info(
             f"Getting outlet in-use status for serial {event.serial_number}"
         )