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

xp/services/conbus/conbus_lightlevel_set_service.py

@@ -21,7 +21,7 @@ from xp.services.protocol import ConbusProtocol
 
 
 class ConbusLightlevelError(Exception):
-    """Raised when Conbus lightlevel operations fail"""
+    """Raised when Conbus lightlevel operations fail."""
 
     pass
 
@@ -39,7 +39,12 @@ class ConbusLightlevelSetService(ConbusProtocol):
         cli_config: ConbusClientConfig,
         reactor: PosixReactorBase,
     ):
-        """Initialize the Conbus lightlevel service"""
+        """Initialize the Conbus lightlevel service.
+
+        Args:
+            cli_config: Configuration for Conbus client connection.
+            reactor: Twisted reactor for event loop.
+        """
         super().__init__(cli_config, reactor)
         self.serial_number: str = ""
         self.output_number: int = 0
@@ -59,8 +64,9 @@ class ConbusLightlevelSetService(ConbusProtocol):
         self.logger = logging.getLogger(__name__)
 
     def connection_established(self) -> None:
+        """Handle connection established event."""
         self.logger.debug(
-            f"Connection established, setting light level for output {self.output_number} to {self.level}%..."
+            f"Connection established, setting light level for output {self.output_number} to {self.level}%."
         )
 
         # Format data as output_number:level (e.g., ""15" + "02:050")
@@ -75,9 +81,19 @@ class ConbusLightlevelSetService(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,7 @@ class ConbusLightlevelSetService(ConbusProtocol):
             self.succeed()
 
     def succeed(self) -> None:
+        """Handle successful light level set operation."""
         self.logger.debug("Succeed")
         self.service_response.success = True
         self.service_response.serial_number = self.serial_number
@@ -108,6 +125,11 @@ class ConbusLightlevelSetService(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.serial_number = self.serial_number
@@ -130,18 +152,16 @@ class ConbusLightlevelSetService(ConbusProtocol):
         """Set light level for a specific output on a module.
 
         Args:
-            serial_number: Module serial number
-            output_number: Output number (0-based, 0-8)
-            level: Light level percentage (0-100)
-            finish_callback: Callback function to call when operation completes
-            timeout_seconds: Optional timeout in seconds
+            serial_number: Module serial number.
+            output_number: Output number (0-based, 0-8).
+            level: Light level percentage (0-100).
+            finish_callback: Callback function to call when operation completes.
+            timeout_seconds: Optional timeout in seconds.
 
         Examples:
-            \b
-                xp conbus lightlevel set 0012345008 2 50
-                xp conbus lightlevel set 0012345008 0 100
+            xp conbus lightlevel set 0012345008 2 50
+            xp conbus lightlevel set 0012345008 0 100
         """
-
         self.logger.info(
             f"Setting light level for {serial_number} output {output_number} to {level}%"
         )
@@ -176,10 +196,10 @@ class ConbusLightlevelSetService(ConbusProtocol):
         """Turn off light (set level to 0) for a specific output.
 
         Args:
-            serial_number: Module serial number
-            output_number: Output number (0-8)
-            finish_callback: Callback function to call when operation completes
-            timeout_seconds: Optional timeout in seconds
+            serial_number: Module serial number.
+            output_number: Output number (0-8).
+            finish_callback: Callback function to call when operation completes.
+            timeout_seconds: Optional timeout in seconds.
         """
         self.set_lightlevel(
             serial_number, output_number, 0, finish_callback, timeout_seconds
@@ -195,10 +215,10 @@ class ConbusLightlevelSetService(ConbusProtocol):
         """Turn on light (set level to 80%) for a specific output.
 
         Args:
-            serial_number: Module serial number
-            output_number: Output number (0-8)
-            finish_callback: Callback function to call when operation completes
-            timeout_seconds: Optional timeout in seconds
+            serial_number: Module serial number.
+            output_number: Output number (0-8).
+            finish_callback: Callback function to call when operation completes.
+            timeout_seconds: Optional timeout in seconds.
         """
         self.set_lightlevel(
             serial_number, output_number, 80, finish_callback, timeout_seconds

xp/services/conbus/conbus_linknumber_get_service.py

@@ -17,10 +17,10 @@ from xp.services.telegram.telegram_service import TelegramService
 
 class ConbusLinknumberGetService(ConbusDatapointService):
     """
-    Service for receiving telegrams from Conbus servers.
+    Service for getting link numbers from Conbus modules.
 
-    Uses composition with ConbusService to provide receive-only functionality
-    for collecting waiting event telegrams from the server.
+    Uses ConbusProtocol to provide link number query functionality
+    for reading the current link number configuration from modules.
     """
 
     def __init__(
@@ -29,7 +29,13 @@ class ConbusLinknumberGetService(ConbusDatapointService):
         cli_config: ConbusClientConfig,
         reactor: PosixReactorBase,
     ) -> None:
-        """Initialize the Conbus client send service"""
+        """Initialize the Conbus linknumber 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.service_callback: Optional[Callable[[ConbusLinknumberResponse], None]] = (
             None
@@ -41,7 +47,11 @@ class ConbusLinknumberGetService(ConbusDatapointService):
     def finish_service_callback(
         self, datapoint_response: ConbusDatapointResponse
     ) -> None:
+        """Process datapoint response and extract link number.
 
+        Args:
+            datapoint_response: The datapoint response from the module.
+        """
         self.logger.debug("Parsing datapoint response")
         link_number_value = 0
         if datapoint_response.success and datapoint_response.datapoint_telegram:
@@ -67,14 +77,12 @@ class ConbusLinknumberGetService(ConbusDatapointService):
         finish_callback: Callable[[ConbusLinknumberResponse], None],
         timeout_seconds: Optional[float] = None,
     ) -> None:
-        """
-        Get the current auto report status for a specific module.
+        """Get the current link number for a specific module.
 
         Args:
-            :param  serial_number: 10-digit module serial number
-            :param  finish_callback: callback function to call when the linknumber status is
-            :param  timeout_seconds: timeout in seconds
-
+            serial_number: 10-digit module serial number.
+            finish_callback: Callback function to call when the link number is received.
+            timeout_seconds: Timeout in seconds.
         """
         self.logger.info("Starting get_linknumber")
         if timeout_seconds:

xp/services/conbus/conbus_linknumber_set_service.py

@@ -33,7 +33,13 @@ class ConbusLinknumberSetService(ConbusProtocol):
         cli_config: ConbusClientConfig,
         reactor: PosixReactorBase,
     ) -> None:
-        """Initialize the Conbus link number set service"""
+        """Initialize the Conbus link number set 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 ConbusLinknumberSetService(ConbusProtocol):
         self.logger = logging.getLogger(__name__)
 
     def connection_established(self) -> None:
+        """Handle connection established event."""
         self.logger.debug(
-            f"Connection established, setting link number {self.link_number}..."
+            f"Connection established, setting link number {self.link_number}."
         )
 
         # Validate parameters before sending
@@ -72,9 +79,19 @@ class ConbusLinknumberSetService(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:
@@ -111,6 +128,11 @@ class ConbusLinknumberSetService(ConbusProtocol):
             )
 
     def succeed(self, system_function: SystemFunction) -> None:
+        """Handle successful link number set operation.
+
+        Args:
+            system_function: The system function from the reply telegram.
+        """
         self.logger.debug("Successfully set link number")
         self.service_response.success = True
         self.service_response.timestamp = datetime.now()
@@ -121,6 +143,11 @@ class ConbusLinknumberSetService(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()
@@ -137,14 +164,13 @@ class ConbusLinknumberSetService(ConbusProtocol):
         finish_callback: Callable[[ConbusLinknumberResponse], None],
         timeout_seconds: Optional[float] = None,
     ) -> None:
-        """
-        Set the link number for a specific module.
+        """Set the link number for a specific module.
 
         Args:
-            serial_number: 10-digit module serial number
-            link_number: Link number to set (0-99)
-            finish_callback: Callback function to call when operation completes
-            timeout_seconds: Optional timeout in seconds
+            serial_number: 10-digit module serial number.
+            link_number: Link number to set (0-99).
+            finish_callback: Callback function to call when operation completes.
+            timeout_seconds: Optional timeout in seconds.
         """
         self.logger.info("Starting set_linknumber")
         if timeout_seconds:

xp/services/conbus/conbus_output_service.py

@@ -25,7 +25,7 @@ from xp.services.telegram.telegram_output_service import (
 
 
 class ConbusOutputError(Exception):
-    """Raised when Conbus output operations fail"""
+    """Raised when Conbus output operations fail."""
 
     pass
 
@@ -44,12 +44,12 @@ class ConbusOutputService(ConbusProtocol):
         cli_config: ConbusClientConfig,
         reactor: PosixReactorBase,
     ):
-        """Initialize the Conbus output service
+        """Initialize the Conbus output service.
 
         Args:
-            telegram_output_service: TelegramOutputService for telegram generation/parsing
-            cli_config: Conbus client configuration
-            reactor: Twisted reactor for async operations
+            telegram_output_service: TelegramOutputService for telegram generation/parsing.
+            cli_config: Conbus client configuration.
+            reactor: Twisted reactor for async operations.
         """
         super().__init__(cli_config, reactor)
         self.telegram_output_service = telegram_output_service
@@ -69,8 +69,9 @@ class ConbusOutputService(ConbusProtocol):
         self.logger = logging.getLogger(__name__)
 
     def connection_established(self) -> None:
+        """Handle connection established event."""
         self.logger.debug(
-            f"Connection established, sending action {self.action_type} to output {self.output_number}..."
+            f"Connection established, sending action {self.action_type} to output {self.output_number}."
         )
 
         # Validate parameters before sending
@@ -91,9 +92,19 @@ class ConbusOutputService(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:
@@ -125,6 +136,11 @@ class ConbusOutputService(ConbusProtocol):
             )
 
     def succeed(self, output_telegram: OutputTelegram) -> None:
+        """Handle successful output action.
+
+        Args:
+            output_telegram: The output telegram received as response.
+        """
         self.logger.debug("Successfully sent action to output")
         self.service_response.success = True
         self.service_response.timestamp = datetime.now()
@@ -136,6 +152,11 @@ class ConbusOutputService(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()
@@ -154,15 +175,14 @@ class ConbusOutputService(ConbusProtocol):
         finish_callback: Callable[[ConbusOutputResponse], None],
         timeout_seconds: Optional[float] = None,
     ) -> None:
-        """
-        Send an action telegram to a module output.
+        """Send an action telegram to a module output.
 
         Args:
-            serial_number: 10-digit module serial number
-            output_number: Output number (0-99)
-            action_type: Action to perform (ON_RELEASE, OFF_PRESS, etc.)
-            finish_callback: Callback function to call when operation completes
-            timeout_seconds: Optional timeout in seconds
+            serial_number: 10-digit module serial number.
+            output_number: Output number (0-99).
+            action_type: Action to perform (ON_RELEASE, OFF_PRESS, etc.).
+            finish_callback: Callback function to call when operation completes.
+            timeout_seconds: Optional timeout in seconds.
         """
         self.logger.info("Starting send_action")
         if timeout_seconds:

xp/services/conbus/conbus_raw_service.py

@@ -17,10 +17,10 @@ from xp.services.protocol import ConbusProtocol
 
 class ConbusRawService(ConbusProtocol):
     """
-    Service for querying datapoints from Conbus modules.
+    Service for sending raw telegram sequences to Conbus modules.
 
-    Uses ConbusProtocol to provide datapoint query functionality
-    for reading sensor data and module information.
+    Uses ConbusProtocol to provide raw telegram functionality
+    for sending arbitrary telegram strings without validation.
     """
 
     def __init__(
@@ -28,7 +28,12 @@ class ConbusRawService(ConbusProtocol):
         cli_config: ConbusClientConfig,
         reactor: PosixReactorBase,
     ) -> None:
-        """Initialize the Conbus datapoint service"""
+        """Initialize the Conbus raw service.
+
+        Args:
+            cli_config: Configuration for Conbus client connection.
+            reactor: Twisted reactor for event loop.
+        """
         super().__init__(cli_config, reactor)
         self.raw_input: str = ""
         self.progress_callback: Optional[Callable[[str], None]] = None
@@ -40,17 +45,27 @@ class ConbusRawService(ConbusProtocol):
         self.logger = logging.getLogger(__name__)
 
     def connection_established(self) -> None:
+        """Handle connection established event."""
         self.logger.debug(f"Connection established, sending {self.raw_input}")
         self.sendFrame(self.raw_input.encode())
 
     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 = telegram_sent
         self.service_response.timestamp = datetime.now()
         self.service_response.received_telegrams = []
-        pass
 
     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 = []
@@ -60,12 +75,22 @@ class ConbusRawService(ConbusProtocol):
             self.progress_callback(telegram_received.frame)
 
     def timeout(self) -> bool:
+        """Handle timeout event.
+
+        Returns:
+            False to indicate connection should be closed.
+        """
         self.logger.debug(f"Timeout: {self.timeout_seconds}s")
         if self.finish_callback:
             self.finish_callback(self.service_response)
         return False
 
     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()
@@ -80,20 +105,15 @@ class ConbusRawService(ConbusProtocol):
         finish_callback: Callable[[ConbusRawResponse], None],
         timeout_seconds: Optional[float] = None,
     ) -> None:
-        """
-        Query a specific datapoint from a module.
+        """Send a raw telegram string to the Conbus server.
 
         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
+            raw_input: Raw telegram string to send.
+            progress_callback: Callback to handle progress updates.
+            finish_callback: Callback function to call when the operation is complete.
+            timeout_seconds: Timeout in seconds.
         """
-
-        self.logger.info("Starting query_datapoint")
+        self.logger.info("Starting send_raw_telegram")
         if timeout_seconds:
             self.timeout_seconds = timeout_seconds
         self.progress_callback = progress_callback

xp/services/conbus/conbus_receive_service.py

@@ -1,6 +1,6 @@
 """Conbus Receive Service for receiving telegrams from Conbus servers.
 
-This service uses composition with ConbusService to provide receive-only functionality,
+This service uses ConbusProtocol to provide receive-only functionality,
 allowing clients to receive waiting event telegrams using empty telegram sends.
 """
 
@@ -19,7 +19,7 @@ class ConbusReceiveService(ConbusProtocol):
     """
     Service for receiving telegrams from Conbus servers.
 
-    Uses composition with ConbusService to provide receive-only functionality
+    Uses ConbusProtocol to provide receive-only functionality
     for collecting waiting event telegrams from the server.
     """
 
@@ -28,7 +28,12 @@ class ConbusReceiveService(ConbusProtocol):
         cli_config: ConbusClientConfig,
         reactor: PosixReactorBase,
     ) -> None:
-        """Initialize the Conbus client send service"""
+        """Initialize the Conbus receive 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[[ConbusReceiveResponse], None]] = None
@@ -40,12 +45,23 @@ class ConbusReceiveService(ConbusProtocol):
         self.logger = logging.getLogger(__name__)
 
     def connection_established(self) -> None:
-        self.logger.debug("Connection established, waiting for telegrams...")
+        """Handle connection established event."""
+        self.logger.debug("Connection established, waiting for telegrams.")
 
     def telegram_sent(self, telegram_sent: str) -> None:
+        """Handle telegram sent event.
+
+        Args:
+            telegram_sent: The telegram that was sent.
+        """
         pass
 
     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 self.progress_callback:
             self.progress_callback(telegram_received.frame)
@@ -55,6 +71,11 @@ class ConbusReceiveService(ConbusProtocol):
         self.receive_response.received_telegrams.append(telegram_received.frame)
 
     def timeout(self) -> bool:
+        """Handle timeout event to stop receiving.
+
+        Returns:
+            False to stop the reactor.
+        """
         self.logger.info("Receive stopped after: %ss", self.timeout_seconds)
         self.receive_response.success = True
         if self.finish_callback:
@@ -62,6 +83,11 @@ class ConbusReceiveService(ConbusProtocol):
         return False
 
     def failed(self, message: str) -> None:
+        """Handle failed connection event.
+
+        Args:
+            message: Failure message.
+        """
         self.logger.debug("Failed %s:", message)
         self.receive_response.success = False
         self.receive_response.error = message
@@ -74,8 +100,14 @@ class ConbusReceiveService(ConbusProtocol):
         finish_callback: Callable[[ConbusReceiveResponse], None],
         timeout_seconds: Optional[float] = None,
     ) -> None:
-        """Run reactor in dedicated thread with its own event loop"""
-        self.logger.info("Starting discovery")
+        """Run reactor in dedicated thread with its own event loop.
+
+        Args:
+            progress_callback: Callback for each received telegram.
+            finish_callback: Callback when receiving completes.
+            timeout_seconds: Optional timeout in seconds.
+        """
+        self.logger.info("Starting receive")
         if timeout_seconds:
             self.timeout_seconds = timeout_seconds
         self.progress_callback = progress_callback