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

xp/services/conbus/conbus_blink_service.py

@@ -1,7 +1,7 @@
-"""Conbus Client Send Service for TCP communication with Conbus servers.
+"""Conbus Blink Service for TCP communication with Conbus servers.
 
 This service implements a TCP client that connects to Conbus servers and sends
-various types of telegrams including discover, version, and sensor data requests.
+blink/unblink telegrams to control module LED indicators.
 """
 
 import logging
@@ -21,10 +21,10 @@ from xp.services.telegram.telegram_service import TelegramService
 
 class ConbusBlinkService(ConbusProtocol):
     """
-    Service for receiving telegrams from Conbus servers.
+    Service for blinking module LEDs on Conbus servers.
 
-    Uses composition with ConbusService to provide receive-only functionality
-    for collecting waiting event telegrams from the server.
+    Uses ConbusProtocol to provide blink/unblink functionality
+    for controlling module LED indicators.
     """
 
     def __init__(
@@ -33,7 +33,13 @@ class ConbusBlinkService(ConbusProtocol):
         cli_config: ConbusClientConfig,
         reactor: PosixReactorBase,
     ) -> None:
-        """Initialize the Conbus client send service"""
+        """Initialize the Conbus blink service.
+
+        Args:
+            telegram_service: Service for parsing telegrams.
+            cli_config: Configuration for Conbus client connection.
+            reactor: Twisted reactor for event loop.
+        """
         super().__init__(cli_config, reactor)
         self.telegram_service = telegram_service
         self.serial_number: str = ""
@@ -50,7 +56,8 @@ class ConbusBlinkService(ConbusProtocol):
         self.logger = logging.getLogger(__name__)
 
     def connection_established(self) -> None:
-        self.logger.debug("Connection established, retrieving autoreport status...")
+        """Handle connection established event."""
+        self.logger.debug("Connection established, sending blink command.")
         # Blink is 05, Unblink is 06
         system_function = SystemFunction.UNBLINK
         if self.on_or_off.lower() == "on":
@@ -66,11 +73,20 @@ class ConbusBlinkService(ConbusProtocol):
         self.service_response.operation = self.on_or_off
 
     def telegram_sent(self, telegram_sent: str) -> None:
+        """Handle telegram sent event.
+
+        Args:
+            telegram_sent: The telegram that was sent.
+        """
         system_telegram = self.telegram_service.parse_system_telegram(telegram_sent)
         self.service_response.sent_telegram = system_telegram
 
     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 = []
@@ -101,6 +117,11 @@ class ConbusBlinkService(ConbusProtocol):
                 self.finish_callback(self.service_response)
 
     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()
@@ -115,17 +136,20 @@ class ConbusBlinkService(ConbusProtocol):
         finish_callback: Callable[[ConbusBlinkResponse], None],
         timeout_seconds: Optional[float] = None,
     ) -> None:
-        """
-        Send blink command to start blinking module LED.
+        r"""Send blink command to start blinking module LED.
 
-        Examples:
+        Args:
+            serial_number: 10-digit module serial number.
+            on_or_off: "on" to blink or "off" to unblink.
+            finish_callback: Callback function to call when the reply is received.
+            timeout_seconds: Timeout in seconds.
 
-        \b
+        Examples:
+            \b
             xp conbus blink 0012345008 on
             xp conbus blink 0012345008 off
         """
-
-        self.logger.info("Starting get_autoreport_status")
+        self.logger.info("Starting send_blink_telegram")
         if timeout_seconds:
             self.timeout_seconds = timeout_seconds
         self.finish_callback = finish_callback

xp/services/conbus/conbus_custom_service.py

@@ -33,7 +33,13 @@ class ConbusCustomService(ConbusProtocol):
         cli_config: ConbusClientConfig,
         reactor: PosixReactorBase,
     ) -> None:
-        """Initialize the Conbus custom service"""
+        """Initialize the Conbus custom service.
+
+        Args:
+            telegram_service: Service for parsing telegrams.
+            cli_config: Configuration for Conbus client connection.
+            reactor: Twisted reactor for event loop.
+        """
         super().__init__(cli_config, reactor)
         self.telegram_service = telegram_service
         self.serial_number: str = ""
@@ -49,8 +55,9 @@ class ConbusCustomService(ConbusProtocol):
         self.logger = logging.getLogger(__name__)
 
     def connection_established(self) -> None:
+        """Handle connection established event."""
         self.logger.debug(
-            f"Connection established, sending custom telegram F{self.function_code}D{self.data}..."
+            f"Connection established, sending custom telegram F{self.function_code}D{self.data}."
         )
         system_function = SystemFunction.from_code(self.function_code)
         if not system_function:
@@ -66,10 +73,19 @@ class ConbusCustomService(ConbusProtocol):
         )
 
     def telegram_sent(self, telegram_sent: str) -> None:
+        """Handle telegram sent event.
+
+        Args:
+            telegram_sent: The telegram that was sent.
+        """
         self.service_response.sent_telegram = 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 = []
@@ -101,6 +117,11 @@ class ConbusCustomService(ConbusProtocol):
             self.finish_callback(self.service_response)
 
     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()
@@ -116,20 +137,15 @@ class ConbusCustomService(ConbusProtocol):
         finish_callback: Callable[[ConbusCustomResponse], None],
         timeout_seconds: Optional[float] = None,
     ) -> None:
-        """
-        Send a custom telegram to a module.
+        """Send a custom telegram to a module.
 
         Args:
-            serial_number: 10-digit module serial number
-            function_code: Function code (e.g., "02", "17")
-            data: Data code (e.g., "E2", "AA")
-            finish_callback: callback function to call when the reply is received
-            timeout_seconds: timeout in seconds
-
-        Returns:
-            ConbusCustomResponse with operation result
+            serial_number: 10-digit module serial number.
+            function_code: Function code (e.g., "02", "17").
+            data: Data code (e.g., "E2", "AA").
+            finish_callback: Callback function to call when the reply is received.
+            timeout_seconds: Timeout in seconds.
         """
-
         self.logger.info("Starting send_custom_telegram")
         if timeout_seconds:
             self.timeout_seconds = timeout_seconds

xp/services/conbus/conbus_datapoint_queryall_service.py

@@ -1,3 +1,8 @@
+"""Conbus DataPoint Query All Service.
+
+This module provides service for querying all datapoint types from a module.
+"""
+
 import logging
 from datetime import datetime
 from typing import Callable, Optional
@@ -28,12 +33,12 @@ class ConbusDatapointQueryAllService(ConbusProtocol):
         cli_config: ConbusClientConfig,
         reactor: PosixReactorBase,
     ) -> None:
-        """Initialize the query all service
+        """Initialize the query all service.
 
         Args:
-            telegram_service: TelegramService for dependency injection
-            cli_config: ConbusClientConfig for connection settings
-            reactor: PosixReactorBase for async operations
+            telegram_service: TelegramService for dependency injection.
+            cli_config: ConbusClientConfig for connection settings.
+            reactor: PosixReactorBase for async operations.
         """
         super().__init__(cli_config, reactor)
         self.telegram_service = telegram_service
@@ -51,11 +56,16 @@ class ConbusDatapointQueryAllService(ConbusProtocol):
         self.logger = logging.getLogger(__name__)
 
     def connection_established(self) -> None:
-        self.logger.debug("Connection established, querying datapoints...")
+        """Handle connection established event."""
+        self.logger.debug("Connection established, querying datapoints.")
         self.next_datapoint()
 
     def next_datapoint(self) -> bool:
+        """Query the next datapoint type.
 
+        Returns:
+            True if there are more datapoints to query, False otherwise.
+        """
         self.logger.debug("Querying next datapoint")
 
         if self.current_index >= len(self.datapoint_types):
@@ -75,6 +85,11 @@ class ConbusDatapointQueryAllService(ConbusProtocol):
         return True
 
     def timeout(self) -> bool:
+        """Handle timeout event by querying next datapoint.
+
+        Returns:
+            True to continue, False to stop the reactor.
+        """
         self.logger.debug("Timeout, querying next datapoint")
         query_next_datapoint = self.next_datapoint()
         if not query_next_datapoint:
@@ -89,10 +104,19 @@ class ConbusDatapointQueryAllService(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.sent_telegram = 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 = []
@@ -122,6 +146,11 @@ class ConbusDatapointQueryAllService(ConbusProtocol):
             self.progress_callback(datapoint_telegram)
 
     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()
@@ -136,20 +165,15 @@ class ConbusDatapointQueryAllService(ConbusProtocol):
         progress_callback: Callable[[ReplyTelegram], None],
         timeout_seconds: Optional[float] = None,
     ) -> None:
-        """
-        Query a specific datapoint from a module.
+        """Query all datapoints from a module.
 
         Args:
-            serial_number: 10-digit module serial number
-            finish_callback: callback function to call when all the datapoint are received
-            progress_callback: callback function to call when a datapoint is received
-            timeout_seconds: timeout in seconds
-
-        Returns:
-            ConbusDatapointResponse with operation result and datapoint value
+            serial_number: 10-digit module serial number.
+            finish_callback: Callback function to call when all datapoints are received.
+            progress_callback: Callback function to call when each datapoint is received.
+            timeout_seconds: Timeout in seconds.
         """
-
-        self.logger.info("Starting query_datapoint")
+        self.logger.info("Starting query_all_datapoints")
         if timeout_seconds:
             self.timeout_seconds = timeout_seconds
         self.finish_callback = finish_callback

xp/services/conbus/conbus_datapoint_service.py

@@ -33,7 +33,13 @@ class ConbusDatapointService(ConbusProtocol):
         cli_config: ConbusClientConfig,
         reactor: PosixReactorBase,
     ) -> None:
-        """Initialize the Conbus datapoint service"""
+        """Initialize the Conbus datapoint service.
+
+        Args:
+            telegram_service: Service for parsing telegrams.
+            cli_config: Configuration for Conbus client connection.
+            reactor: Twisted reactor for event loop.
+        """
         super().__init__(cli_config, reactor)
         self.telegram_service = telegram_service
         self.serial_number: str = ""
@@ -48,8 +54,9 @@ class ConbusDatapointService(ConbusProtocol):
         self.logger = logging.getLogger(__name__)
 
     def connection_established(self) -> None:
+        """Handle connection established event."""
         self.logger.debug(
-            f"Connection established, querying datapoint {self.datapoint_type}..."
+            f"Connection established, querying datapoint {self.datapoint_type}."
         )
         if self.datapoint_type is None:
             self.failed("Datapoint type not set")
@@ -63,10 +70,19 @@ class ConbusDatapointService(ConbusProtocol):
         )
 
     def telegram_sent(self, telegram_sent: str) -> None:
+        """Handle telegram sent event.
+
+        Args:
+            telegram_sent: The telegram that was sent.
+        """
         self.service_response.sent_telegram = 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 = []
@@ -97,6 +113,11 @@ class ConbusDatapointService(ConbusProtocol):
         self.succeed(datapoint_telegram)
 
     def succeed(self, datapoint_telegram: ReplyTelegram) -> None:
+        """Handle successful datapoint query.
+
+        Args:
+            datapoint_telegram: The parsed datapoint telegram.
+        """
         self.logger.debug("Succeed querying datapoint")
         self.service_response.success = True
         self.service_response.timestamp = datetime.now()
@@ -108,6 +129,11 @@ class ConbusDatapointService(ConbusProtocol):
             self.finish_callback(self.service_response)
 
     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()
@@ -123,19 +149,14 @@ class ConbusDatapointService(ConbusProtocol):
         finish_callback: Callable[[ConbusDatapointResponse], None],
         timeout_seconds: Optional[float] = None,
     ) -> None:
-        """
-        Query a specific datapoint from a module.
+        """Query a specific datapoint from a module.
 
         Args:
-            serial_number: 10-digit module serial number
-            datapoint_type: Type of datapoint to query
-            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.
+            datapoint_type: Type of datapoint to query.
+            finish_callback: Callback function to call when the datapoint is received.
+            timeout_seconds: Timeout in seconds.
         """
-
         self.logger.info("Starting query_datapoint")
         if timeout_seconds:
             self.timeout_seconds = timeout_seconds

xp/services/conbus/conbus_discover_service.py

@@ -1,7 +1,7 @@
-"""Conbus Client Send Service for TCP communication with Conbus servers.
+"""Conbus Discover Service for TCP communication with Conbus servers.
 
 This service implements a TCP client that connects to Conbus servers and sends
-various types of telegrams including discover, version, and sensor data requests.
+discover telegrams to find modules on the network.
 """
 
 import logging
@@ -18,10 +18,10 @@ from xp.services.protocol.conbus_protocol import ConbusProtocol
 
 class ConbusDiscoverService(ConbusProtocol):
     """
-    TCP client service for sending telegrams to Conbus servers.
+    Service for discovering modules on Conbus servers.
 
-    Manages TCP socket connections, handles telegram generation and transmission,
-    and processes server responses.
+    Uses ConbusProtocol to provide discovery functionality for finding
+    modules connected to the Conbus network.
     """
 
     def __init__(
@@ -29,7 +29,12 @@ class ConbusDiscoverService(ConbusProtocol):
         cli_config: ConbusClientConfig,
         reactor: PosixReactorBase,
     ) -> None:
-        """Initialize the Conbus client send service"""
+        """Initialize the Conbus discover service.
+
+        Args:
+            cli_config: Conbus client configuration.
+            reactor: Twisted reactor instance.
+        """
         super().__init__(cli_config, reactor)
         self.progress_callback: Optional[Callable[[str], None]] = None
         self.finish_callback: Optional[Callable[[ConbusDiscoverResponse], None]] = None
@@ -39,6 +44,7 @@ class ConbusDiscoverService(ConbusProtocol):
         self.logger = logging.getLogger(__name__)
 
     def connection_established(self) -> None:
+        """Handle connection established event."""
         self.logger.debug("Connection established, sending discover telegram")
         self.send_telegram(
             telegram_type=TelegramType.SYSTEM,
@@ -48,11 +54,20 @@ class ConbusDiscoverService(ConbusProtocol):
         )
 
     def telegram_sent(self, telegram_sent: str) -> None:
+        """Handle telegram sent event.
+
+        Args:
+            telegram_sent: The telegram that was sent.
+        """
         self.logger.debug(f"Telegram sent: {telegram_sent}")
         self.discovered_device_result.sent_telegram = 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.discovered_device_result.received_telegrams:
             self.discovered_device_result.received_telegrams = []
@@ -69,6 +84,11 @@ class ConbusDiscoverService(ConbusProtocol):
             self.logger.debug("Not a discover response")
 
     def discovered_device(self, serial_number: str) -> None:
+        """Handle discovered device event.
+
+        Args:
+            serial_number: Serial number of the discovered device.
+        """
         self.logger.info("discovered_device: %s", serial_number)
         if not self.discovered_device_result.discovered_devices:
             self.discovered_device_result.discovered_devices = []
@@ -77,6 +97,11 @@ class ConbusDiscoverService(ConbusProtocol):
             self.progress_callback(serial_number)
 
     def timeout(self) -> bool:
+        """Handle timeout event to stop discovery.
+
+        Returns:
+            False to stop the reactor.
+        """
         self.logger.info("Discovery stopped after: %ss", self.timeout_seconds)
         self.discovered_device_result.success = True
         if self.finish_callback:
@@ -84,6 +109,11 @@ class ConbusDiscoverService(ConbusProtocol):
         return False
 
     def failed(self, message: str) -> None:
+        """Handle failed connection event.
+
+        Args:
+            message: Failure message.
+        """
         self.logger.debug(f"Failed: {message}")
         self.discovered_device_result.success = False
         self.discovered_device_result.error = message
@@ -96,7 +126,13 @@ class ConbusDiscoverService(ConbusProtocol):
         finish_callback: Callable[[ConbusDiscoverResponse], None],
         timeout_seconds: Optional[float] = None,
     ) -> None:
-        """Run reactor in dedicated thread with its own event loop"""
+        """Run reactor in dedicated thread with its own event loop.
+
+        Args:
+            progress_callback: Callback for each discovered device.
+            finish_callback: Callback when discovery completes.
+            timeout_seconds: Optional timeout in seconds.
+        """
         self.logger.info("Starting discovery")
         if timeout_seconds:
             self.timeout_seconds = timeout_seconds

xp/services/conbus/conbus_lightlevel_get_service.py

@@ -1,6 +1,6 @@
-"""Conbus Auto Report Service for getting and setting module auto report status.
+"""Conbus Lightlevel Get Service for getting module light levels.
 
-This service handles auto report status operations for modules through Conbus telegrams.
+This service handles light level query operations for modules through Conbus telegrams.
 """
 
 import logging
@@ -18,10 +18,10 @@ from xp.services.telegram.telegram_service import TelegramService
 
 class ConbusLightlevelGetService(ConbusDatapointService):
     """
-    Service for receiving telegrams from Conbus servers.
+    Service for getting light levels from Conbus modules.
 
-    Uses composition with ConbusService to provide receive-only functionality
-    for collecting waiting event telegrams from the server.
+    Uses ConbusProtocol to provide light level query functionality
+    for reading the current light level configuration from module outputs.
     """
 
     def __init__(
@@ -30,7 +30,13 @@ class ConbusLightlevelGetService(ConbusDatapointService):
         cli_config: ConbusClientConfig,
         reactor: PosixReactorBase,
     ) -> None:
-        """Initialize the Conbus client send service"""
+        """Initialize the Conbus lightlevel get service.
+
+        Args:
+            telegram_service: Service for parsing telegrams.
+            cli_config: Configuration for Conbus client connection.
+            reactor: Twisted reactor for event loop.
+        """
         super().__init__(telegram_service, cli_config, reactor)
         self.output_number: int = 0
         self.service_callback: Optional[Callable[[ConbusLightlevelResponse], None]] = (
@@ -43,7 +49,11 @@ class ConbusLightlevelGetService(ConbusDatapointService):
     def finish_service_callback(
         self, datapoint_response: ConbusDatapointResponse
     ) -> None:
+        """Process datapoint response and extract light level.
 
+        Args:
+            datapoint_response: The datapoint response from the module.
+        """
         self.logger.debug("Parsing datapoint response")
 
         level = 0
@@ -79,17 +89,15 @@ class ConbusLightlevelGetService(ConbusDatapointService):
         finish_callback: Callable[[ConbusLightlevelResponse], None],
         timeout_seconds: Optional[float] = None,
     ) -> None:
-        """
-        Get the current auto report status for a specific module.
+        """Get the current light level for a specific module output.
 
         Args:
-            :param  serial_number: 10-digit module serial number
-            :param  output_number: output module number
-            :param  finish_callback: callback function to call when the lightlevel status is
-            :param  timeout_seconds: timeout in seconds
-
+            serial_number: 10-digit module serial number.
+            output_number: Output module number.
+            finish_callback: Callback function to call when the light level is received.
+            timeout_seconds: Timeout in seconds.
         """
-        self.logger.info("Starting get_lightlevel_status")
+        self.logger.info("Starting get_light_level")
         if timeout_seconds:
             self.timeout_seconds = timeout_seconds
         self.serial_number = serial_number