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

xp/services/server/xp24_server_service.py

@@ -13,7 +13,7 @@ from xp.services.server.base_server_service import BaseServerService
 
 
 class XP24ServerError(Exception):
-    """Raised when XP24 server operations fail"""
+    """Raised when XP24 server operations fail."""
 
     pass
 
@@ -27,7 +27,11 @@ class XP24ServerService(BaseServerService):
     """
 
     def __init__(self, serial_number: str):
-        """Initialize XP24 server service"""
+        """Initialize XP24 server service.
+
+        Args:
+            serial_number: The device serial number.
+        """
         super().__init__(serial_number)
         self.device_type = "XP24"
         self.module_type_code = 7  # XP24 module type from registry
@@ -36,7 +40,7 @@ class XP24ServerService(BaseServerService):
     def _handle_device_specific_data_request(
         self, request: SystemTelegram
     ) -> Optional[str]:
-        """Handle XP24-specific data requests"""
+        """Handle XP24-specific data requests."""
         if (
             request.system_function != SystemFunction.READ_DATAPOINT
             or not request.datapoint_type
@@ -49,7 +53,12 @@ class XP24ServerService(BaseServerService):
             DataPointType.MODULE_STATE: "OFF",
             DataPointType.MODULE_OPERATING_HOURS: "00:000[H],01:000[H],02:000[H],03:000[H]",
         }
-        data_part = f"R{self.serial_number}F02{datapoint_type.value}{self.module_type_code}{datapoint_values.get(datapoint_type)}"
+        data_part = (
+            f"R{self.serial_number}"
+            f"F02{datapoint_type.value}"
+            f"{self.module_type_code}"
+            f"{datapoint_values.get(datapoint_type)}"
+        )
         telegram = self._build_response_telegram(data_part)
 
         self.logger.debug(
@@ -60,14 +69,25 @@ class XP24ServerService(BaseServerService):
     def _handle_device_specific_action_request(
         self, request: SystemTelegram
     ) -> Optional[str]:
+        """Handle XP24-specific action requests.
+
+        Args:
+            request: The system telegram request.
 
+        Returns:
+            The response telegram string, or None if request cannot be handled.
+        """
         if request.system_function != SystemFunction.ACTION:
             return None
 
         return self.generate_action_response(request)
 
     def get_device_info(self) -> Dict:
-        """Get XP24 device information"""
+        """Get XP24 device information.
+
+        Returns:
+            Dictionary containing device information.
+        """
         return {
             "serial_number": self.serial_number,
             "device_type": self.device_type,
@@ -77,7 +97,14 @@ class XP24ServerService(BaseServerService):
         }
 
     def generate_action_response(self, request: SystemTelegram) -> Optional[str]:
-        """Generate action response telegram (simulated)"""
+        """Generate action response telegram (simulated).
+
+        Args:
+            request: The system telegram request.
+
+        Returns:
+            The ACK or NAK response telegram string.
+        """
         response = "F19D"  # NAK
         if (
             request.system_function == SystemFunction.ACTION

xp/services/server/xp33_server_service.py

@@ -15,7 +15,7 @@ from xp.utils import calculate_checksum
 
 
 class XP33ServerError(Exception):
-    """Raised when XP33 server operations fail"""
+    """Raised when XP33 server operations fail."""
 
     pass
 
@@ -29,7 +29,12 @@ class XP33ServerService(BaseServerService):
     """
 
     def __init__(self, serial_number: str, variant: str = "XP33LR"):
-        """Initialize XP33 server service"""
+        """Initialize XP33 server service.
+
+        Args:
+            serial_number: The device serial number.
+            variant: Device variant (XP33, XP33LR, or XP33LED).
+        """
         super().__init__(serial_number)
         self.variant = variant  # XP33 or XP33LR or XP33LED
         self.device_type = "XP33"
@@ -69,7 +74,7 @@ class XP33ServerService(BaseServerService):
     def _handle_device_specific_data_request(
         self, request: SystemTelegram
     ) -> Optional[str]:
-        """Handle XP24-specific data requests"""
+        """Handle XP24-specific data requests."""
         if (
             request.system_function != SystemFunction.READ_DATAPOINT
             or not request.datapoint_type
@@ -82,7 +87,12 @@ class XP33ServerService(BaseServerService):
             DataPointType.MODULE_STATE: "OFF",
             DataPointType.MODULE_OPERATING_HOURS: "00:000[H],01:000[H],02:000[H]",
         }
-        data_part = f"R{self.serial_number}F02{datapoint_type.value}{self.module_type_code}{datapoint_values.get(datapoint_type)}"
+        data_part = (
+            f"R{self.serial_number}"
+            f"F02{datapoint_type.value}"
+            f"{self.module_type_code}"
+            f"{datapoint_values.get(datapoint_type)}"
+        )
         checksum = calculate_checksum(data_part)
         telegram = f"<{data_part}{checksum}>"
 
@@ -92,7 +102,15 @@ class XP33ServerService(BaseServerService):
         return telegram
 
     def set_channel_dimming(self, channel: int, level: int) -> bool:
-        """Set individual channel dimming level"""
+        """Set individual channel dimming level.
+
+        Args:
+            channel: Channel number (1-3).
+            level: Dimming level (0-100 percent).
+
+        Returns:
+            True if channel was set successfully, False otherwise.
+        """
         if 1 <= channel <= 3 and 0 <= level <= 100:
             self.channel_states[channel - 1] = level
             self.logger.info(f"XP33 channel {channel} set to {level}%")
@@ -100,7 +118,14 @@ class XP33ServerService(BaseServerService):
         return False
 
     def activate_scene(self, scene: int) -> bool:
-        """Activate a pre-programmed scene"""
+        """Activate a pre-programmed scene.
+
+        Args:
+            scene: Scene number (1-4).
+
+        Returns:
+            True if scene was activated successfully, False otherwise.
+        """
         if scene in self.scenes:
             self.channel_states = self.scenes[scene].copy()
             self.logger.info(f"XP33 scene {scene} activated: {self.channel_states}")
@@ -108,7 +133,11 @@ class XP33ServerService(BaseServerService):
         return False
 
     def get_device_info(self) -> Dict:
-        """Get XP33 device information"""
+        """Get XP33 device information.
+
+        Returns:
+            Dictionary containing device information.
+        """
         return {
             "serial_number": self.serial_number,
             "device_type": self.device_type,
@@ -123,7 +152,11 @@ class XP33ServerService(BaseServerService):
         }
 
     def get_technical_specs(self) -> Dict:
-        """Get technical specifications"""
+        """Get technical specifications.
+
+        Returns:
+            Dictionary containing technical specifications.
+        """
         if self.variant == "XP33LED":
             return {
                 "power_per_channel": "100VA",

xp/services/telegram/__init__.py

@@ -0,0 +1 @@
+"""Telegram parsing and processing services."""

xp/services/telegram/telegram_blink_service.py

@@ -11,7 +11,7 @@ from xp.utils.checksum import calculate_checksum
 
 
 class BlinkError(Exception):
-    """Raised when blink/unblink operations fail"""
+    """Raised when blink/unblink operations fail."""
 
     pass
 
@@ -26,24 +26,22 @@ class TelegramBlinkService:
     """
 
     def __init__(self) -> None:
-        """Initialize the blink service"""
+        """Initialize the blink service."""
         pass
 
     @staticmethod
     def generate_blink_telegram(serial_number: str, on_or_off: str) -> str:
-        """
-        Generate a telegram to start blinking a module's LED.
+        """Generate a telegram to start blinking a module's LED.
 
         Args:
-            serial_number: The 10-digit module serial number
+            serial_number: The 10-digit module serial number.
+            on_or_off: The action to perform ('on' for blink, 'off' for unblink).
 
         Returns:
-            Formatted telegram string (e.g., "<S0012345008F05D00FN>")
+            Formatted telegram string (e.g., "<S0012345008F05D00FN>").
 
         Raises:
-            BlinkError: If parameters are invalid
-            :param serial_number:
-            :param on_or_off:
+            BlinkError: If parameters are invalid.
         """
         # Validate serial number
         if not serial_number or len(serial_number) != 10:
@@ -68,17 +66,13 @@ class TelegramBlinkService:
         return telegram
 
     def create_blink_telegram_object(self, serial_number: str) -> SystemTelegram:
-        """
-        Create a SystemTelegram object for blinking LED.
+        """Create a SystemTelegram object for blinking LED.
 
         Args:
-            serial_number: The 10-digit module serial number
+            serial_number: The 10-digit module serial number.
 
         Returns:
-            SystemTelegram object representing the blink command
-
-        Raises:
-            BlinkError: If parameters are invalid
+            SystemTelegram object representing the blink command.
         """
         raw_telegram = self.generate_blink_telegram(serial_number, "on")
 
@@ -96,17 +90,13 @@ class TelegramBlinkService:
         return telegram
 
     def create_unblink_telegram_object(self, serial_number: str) -> SystemTelegram:
-        """
-        Create a SystemTelegram object for unblink LED.
+        """Create a SystemTelegram object for unblink LED.
 
         Args:
-            serial_number: The 10-digit module serial number
+            serial_number: The 10-digit module serial number.
 
         Returns:
-            SystemTelegram object representing the unblink command
-
-        Raises:
-            BlinkError: If parameters are invalid
+            SystemTelegram object representing the unblink command.
         """
         raw_telegram = self.generate_blink_telegram(serial_number, "off")
 
@@ -125,26 +115,24 @@ class TelegramBlinkService:
 
     @staticmethod
     def is_ack_response(reply_telegram: ReplyTelegram) -> bool:
-        """
-        Check if a reply telegram is an ACK response.
+        """Check if a reply telegram is an ACK response.
 
         Args:
-            reply_telegram: Reply telegram to check
+            reply_telegram: Reply telegram to check.
 
         Returns:
-            True if this is an ACK response (F18D), False otherwise
+            True if this is an ACK response (F18D), False otherwise.
         """
         return reply_telegram.system_function == SystemFunction.ACK
 
     @staticmethod
     def is_nak_response(reply_telegram: ReplyTelegram) -> bool:
-        """
-        Check if a reply telegram is a NAK response.
+        """Check if a reply telegram is a NAK response.
 
         Args:
-            reply_telegram: Reply telegram to check
+            reply_telegram: Reply telegram to check.
 
         Returns:
-            True if this is a NAK response (F19D), False otherwise
+            True if this is a NAK response (F19D), False otherwise.
         """
         return reply_telegram.system_function == SystemFunction.NAK

xp/services/telegram/telegram_checksum_service.py

@@ -22,10 +22,10 @@ class TelegramChecksumService:
         """Calculate simple XOR checksum for string data.
 
         Args:
-            data: String data to calculate checksum for
+            data: String data to calculate checksum for.
 
         Returns:
-            Response object with checksum result
+            Response object with checksum result.
         """
         try:
             checksum = calculate_checksum(data)
@@ -45,10 +45,10 @@ class TelegramChecksumService:
         """Calculate CRC32 checksum for data.
 
         Args:
-            data: String or bytes data to calculate checksum for
+            data: String or bytes data to calculate checksum for.
 
         Returns:
-            Response object with checksum result
+            Response object with checksum result.
         """
         try:
             # Convert string to bytes if needed
@@ -82,11 +82,11 @@ class TelegramChecksumService:
         """Validate data against expected simple checksum.
 
         Args:
-            data: Original data
-            expected_checksum: Expected checksum value
+            data: Original data.
+            expected_checksum: Expected checksum value.
 
         Returns:
-            Response object with validation result
+            Response object with validation result.
         """
         try:
             calculated_checksum = calculate_checksum(data)
@@ -114,11 +114,11 @@ class TelegramChecksumService:
         """Validate data against expected CRC32 checksum.
 
         Args:
-            data: Original data (string or bytes)
-            expected_checksum: Expected CRC32 checksum value
+            data: Original data (string or bytes).
+            expected_checksum: Expected CRC32 checksum value.
 
         Returns:
-            Response object with validation result
+            Response object with validation result.
         """
         try:
             # Convert string to bytes if needed

xp/services/telegram/telegram_datapoint_service.py

@@ -0,0 +1,70 @@
+"""Service for processing Telegram protocol datapoint values."""
+
+
+class TelegramDatapointService:
+    """Service for processing Telegram protocol datapoint values.
+
+    Provides methods to parse and extract values from different types of
+    Telegram datapoints including autoreport status, light level outputs,
+    and link number values.
+    """
+
+    def get_autoreport_status(self, data_value: str) -> bool:
+        """Get the autoreport status value.
+
+        Args:
+            data_value: The raw autoreport status data value (PP or AA).
+
+        Returns:
+            The autoreport status: Enable (True) or disable (False).
+        """
+        status_value = True if data_value == "PP" else False
+        return status_value
+
+    def get_autoreport_status_data_value(self, status_value: bool) -> str:
+        """Get the autoreport status data_value.
+
+        Args:
+            status_value: Enable (True) or disable (False).
+
+        Returns:
+            data_value: The raw autoreport status data value (PP or AA).
+        """
+        data_value = "PP" if status_value else "AA"
+        return data_value
+
+    def get_lightlevel(self, data_value: str, output_number: int) -> int:
+        """Extract the light level for a specific output number.
+
+        Parses comma-separated output data in the format "output:level[%]"
+        and returns the level for the requested output number.
+
+        Args:
+            data_value: Comma-separated string of output:level pairs
+                       (e.g., "1:50[%],2:75[%]").
+            output_number: The output number to get the level for.
+
+        Returns:
+            The light level as an integer (0 if output not found).
+        """
+        level = 0
+        for output_data in data_value.split(","):
+            if ":" in output_data:
+                output_str, level_str = output_data.split(":")
+                if int(output_str) == output_number:
+                    level_str = level_str.replace("[%]", "")
+                    level = int(level_str)
+                    break
+        return level
+
+    def get_linknumber(self, data_value: str) -> int:
+        """Parse and return the link number value.
+
+        Args:
+            data_value: The raw link number data value as a string.
+
+        Returns:
+            The link number as an integer.
+        """
+        link_number_value = int(data_value)
+        return link_number_value

xp/services/telegram/telegram_discover_service.py

@@ -13,30 +13,51 @@ from xp.utils.checksum import calculate_checksum
 
 
 class DiscoverError(Exception):
-    """Raised when discover operations fail"""
+    """Raised when discover operations fail."""
 
     pass
 
 
 class DeviceInfo:
-    """Information about a discovered device"""
+    """Information about a discovered device."""
 
     def __init__(
         self, serial_number: str, checksum_valid: bool = True, raw_telegram: str = ""
     ):
+        """Initialize device info.
+
+        Args:
+            serial_number: 10-digit module serial number.
+            checksum_valid: Whether the telegram checksum is valid.
+            raw_telegram: Raw telegram string.
+        """
         self.serial_number = serial_number
         self.checksum_valid = checksum_valid
         self.raw_telegram = raw_telegram
 
     def __str__(self) -> str:
+        """Return string representation of device.
+
+        Returns:
+            String with serial number and checksum status.
+        """
         status = "✓" if self.checksum_valid else "✗"
         return f"Device {self.serial_number} ({status})"
 
     def __repr__(self) -> str:
+        """Return repr representation of device.
+
+        Returns:
+            DeviceInfo constructor representation.
+        """
         return f"DeviceInfo(serial='{self.serial_number}', checksum_valid={self.checksum_valid})"
 
     def to_dict(self) -> dict:
-        """Convert to dictionary for JSON serialization"""
+        """Convert to dictionary for JSON serialization.
+
+        Returns:
+            Dictionary with device information.
+        """
         return {
             "serial_number": self.serial_number,
             "checksum_valid": self.checksum_valid,
@@ -54,7 +75,7 @@ class TelegramDiscoverService:
     """
 
     def __init__(self) -> None:
-        """Initialize the discover service"""
+        """Initialize the discover service."""
         pass
 
     @staticmethod
@@ -78,11 +99,10 @@ class TelegramDiscoverService:
         return telegram
 
     def create_discover_telegram_object(self) -> SystemTelegram:
-        """
-        Create a SystemTelegram object for discover broadcast.
+        """Create a SystemTelegram object for discover broadcast.
 
         Returns:
-            SystemTelegram object representing the discover command
+            SystemTelegram object representing the discover command.
         """
         raw_telegram = self.generate_discover_telegram()
 
@@ -101,20 +121,26 @@ class TelegramDiscoverService:
 
     @staticmethod
     def is_discover_response(reply_telegram: ReplyTelegram) -> bool:
-        """
-        Check if a reply telegram is a discover response.
+        """Check if a reply telegram is a discover response.
 
         Args:
-            reply_telegram: Reply telegram to check
+            reply_telegram: Reply telegram to check.
 
         Returns:
-            True if this is a discover response, False otherwise
+            True if this is a discover response, False otherwise.
         """
         return reply_telegram.system_function == SystemFunction.DISCOVERY
 
     @staticmethod
     def _generate_discover_response(serial_number: str) -> str:
-        """Generate discover response telegram for a device"""
+        """Generate discover response telegram for a device.
+
+        Args:
+            serial_number: 10-digit module serial number.
+
+        Returns:
+            Formatted discover response telegram.
+        """
         # Format: <R{serial}F01D{checksum}>
         data_part = f"R{serial_number}F01D"
         checksum = calculate_checksum(data_part)
@@ -123,14 +149,13 @@ class TelegramDiscoverService:
 
     @staticmethod
     def get_unique_devices(devices: List[DeviceInfo]) -> List[DeviceInfo]:
-        """
-        Filter out duplicate devices based on serial number.
+        """Filter out duplicate devices based on serial number.
 
         Args:
-            devices: List of discovered devices
+            devices: List of discovered devices.
 
         Returns:
-            List of unique devices (first occurrence of each serial number)
+            List of unique devices (first occurrence of each serial number).
         """
         seen_serials: Set[str] = set()
         unique_devices = []
@@ -144,14 +169,13 @@ class TelegramDiscoverService:
 
     @staticmethod
     def validate_discover_response_format(raw_telegram: str) -> bool:
-        """
-        Validate if a raw telegram matches discover response format.
+        """Validate if a raw telegram matches discover response format.
 
         Args:
-            raw_telegram: Raw telegram string to validate
+            raw_telegram: Raw telegram string to validate.
 
         Returns:
-            True if format matches discover response pattern
+            True if format matches discover response pattern.
         """
         # Discover response format: <R{10-digit-serial}F01D{2-char-checksum}>
         import re
@@ -163,14 +187,13 @@ class TelegramDiscoverService:
         return match is not None
 
     def generate_discover_summary(self, devices: List[DeviceInfo]) -> dict:
-        """
-        Generate a summary of a discover results.
+        """Generate a summary of a discover results.
 
         Args:
-            devices: List of discovered devices
+            devices: List of discovered devices.
 
         Returns:
-            Dictionary with discover statistics
+            Dictionary with discover statistics.
         """
         unique_devices = self.get_unique_devices(devices)
         valid_devices = [d for d in unique_devices if d.checksum_valid]
@@ -200,14 +223,13 @@ class TelegramDiscoverService:
         }
 
     def format_discover_results(self, devices: List[DeviceInfo]) -> str:
-        """
-        Format discover results for human-readable output.
+        """Format discover results for human-readable output.
 
         Args:
-            devices: List of discovered devices
+            devices: List of discovered devices.
 
         Returns:
-            Formatted string summary
+            Formatted string summary.
         """
         if not devices:
             return "No devices discovered"
@@ -241,7 +263,14 @@ class TelegramDiscoverService:
 
     @staticmethod
     def is_discover_request(telegram: SystemTelegram) -> bool:
-        """Check if telegram is a discover request"""
+        """Check if telegram is a discover request.
+
+        Args:
+            telegram: System telegram to check.
+
+        Returns:
+            True if this is a discover request, False otherwise.
+        """
         return (
             telegram.system_function == SystemFunction.DISCOVERY
             and telegram.serial_number == "0000000000"