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

xp/services/telegram/telegram_output_service.py

@@ -12,17 +12,22 @@ from xp.utils.checksum import calculate_checksum
 
 
 class XPOutputError(Exception):
-    """Raised when XP24 action operations fail"""
+    """Raised when XP24 action operations fail."""
 
     pass
 
 
 class TelegramOutputService:
-    """
-    Service for XP action operations.
+    """Service for XP action operations.
 
     Handles parsing and validation of XP24 action telegrams,
     status queries, and action command generation.
+
+    Attributes:
+        MAX_OUTPUTS: Maximum number of outputs supported.
+        XP_OUTPUT_PATTERN: Regex pattern for XP24 action telegrams.
+        XP_ACK_NAK_PATTERN: Regex pattern for ACK/NAK response telegrams.
+        telegram_service: TelegramService instance for parsing.
     """
 
     MAX_OUTPUTS = 99
@@ -32,18 +37,21 @@ class TelegramOutputService:
     XP_ACK_NAK_PATTERN = re.compile(r"^<R(\d{10})F(1[89])D([A-Z0-9]{2})>$")
 
     def __init__(self, telegram_service: TelegramService) -> None:
-        """Initialize the XP output service"""
+        """Initialize the XP output service.
+
+        Args:
+            telegram_service: TelegramService instance for parsing operations.
+        """
         self.telegram_service = telegram_service
 
     def validate_output_number(self, output_number: int) -> None:
-        """
-        Validate XP24 output number according to architecture constraints.
+        """Validate XP24 output number according to architecture constraints.
 
         Args:
-            output_number: Output number to validate (0-3)
+            output_number: Output number to validate (0-3).
 
         Raises:
-            XPOutputError: If output number is invalid
+            XPOutputError: If output number is invalid.
         """
         if not isinstance(output_number, int):
             raise XPOutputError(
@@ -58,14 +66,13 @@ class TelegramOutputService:
 
     @staticmethod
     def validate_serial_number(serial_number: str) -> None:
-        """
-        Validate serial number format.
+        """Validate serial number format.
 
         Args:
-            serial_number: Serial number to validate
+            serial_number: Serial number to validate.
 
         Raises:
-            XP24ActionError: If serial number is invalid
+            XPOutputError: If serial number is invalid.
         """
         if not isinstance(serial_number, str):
             raise XPOutputError(
@@ -81,19 +88,18 @@ class TelegramOutputService:
     def generate_system_action_telegram(
         self, serial_number: str, output_number: int, action: ActionType
     ) -> str:
-        """
-        Generate XP24 action telegram string.
+        """Generate XP24 action telegram string.
 
         Args:
-            serial_number: Target module serial number
-            output_number: Output number (0-3)
-            action: Action type (PRESS/RELEASE)
+            serial_number: Target module serial number.
+            output_number: Output number (0-3).
+            action: Action type (PRESS/RELEASE).
 
         Returns:
-            Complete telegram string with checksum
+            Complete telegram string with checksum.
 
         Raises:
-            XP24ActionError: If parameters are invalid
+            XPOutputError: If parameters are invalid.
         """
         # Validate outputs according to architecture constraints
         self.validate_serial_number(serial_number)
@@ -115,17 +121,13 @@ class TelegramOutputService:
         return f"<{data_part}{checksum}>"
 
     def generate_system_status_telegram(self, serial_number: str) -> str:
-        """
-        Generate XP output status query telegram.
+        """Generate XP output status query telegram.
 
         Args:
-            serial_number: Target module serial number
+            serial_number: Target module serial number.
 
         Returns:
-            Complete status query telegram string
-
-        Raises:
-            XPOutputError: If serial number is invalid
+            Complete status query telegram string.
         """
         # Validate outputs
         self.validate_serial_number(serial_number)
@@ -142,17 +144,16 @@ class TelegramOutputService:
         return f"<{data_part}{checksum}>"
 
     def parse_reply_telegram(self, raw_telegram: str) -> OutputTelegram:
-        """
-        Parse a raw XP output response telegram string.
+        """Parse a raw XP output response telegram string.
 
         Args:
-            raw_telegram: The raw telegram string (e.g., "<R0012345003F18DFF>")
+            raw_telegram: The raw telegram string (e.g., "<R0012345003F18DFF>").
 
         Returns:
-            XPOutputTelegram object with parsed data
+            XPOutputTelegram object with parsed data.
 
         Raises:
-            XPOutputError: If telegram format is invalid
+            XPOutputError: If telegram format is invalid.
         """
         if not raw_telegram:
             raise XPOutputError("Empty telegram string")
@@ -193,17 +194,16 @@ class TelegramOutputService:
             raise XPOutputError(f"Invalid values in XP24 action telegram: {e}")
 
     def parse_system_telegram(self, raw_telegram: str) -> OutputTelegram:
-        """
-        Parse a raw XP output telegram string.
+        """Parse a raw XP output telegram string.
 
         Args:
-            raw_telegram: The raw telegram string (e.g., "<S0012345008F27D00AAFN>")
+            raw_telegram: The raw telegram string (e.g., "<S0012345008F27D00AAFN>").
 
         Returns:
-            XPOutputTelegram object with parsed data
+            XPOutputTelegram object with parsed data.
 
         Raises:
-            XPOutputError: If telegram format is invalid
+            XPOutputError: If telegram format is invalid.
         """
         if not raw_telegram:
             raise XPOutputError("Empty telegram string")
@@ -247,17 +247,16 @@ class TelegramOutputService:
             raise XPOutputError(f"Invalid values in XP24 action telegram: {e}")
 
     def parse_status_response(self, raw_telegram: str) -> list[bool]:
-        """
-        Parse XP24 status response telegram to extract output states.
+        """Parse XP24 status response telegram to extract output states.
 
         Args:
-            raw_telegram: Raw reply telegram (e.g., "<R0012345008F02D12xxxx1110FJ>")
+            raw_telegram: Raw reply telegram (e.g., "<R0012345008F02D12xxxx1110FJ>").
 
         Returns:
-            Dictionary mapping output numbers (0-3) to their states (True=ON, False=OFF)
+            Dictionary mapping output numbers (0-3) to their states (True=ON, False=OFF).
 
         Raises:
-            XP24ActionError: If telegram format is invalid
+            XPOutputError: If output telegram is invalid.
         """
         if not raw_telegram:
             raise XPOutputError("Empty status response telegram")
@@ -285,14 +284,13 @@ class TelegramOutputService:
 
     @staticmethod
     def format_status_summary(status: Dict[int, bool]) -> str:
-        """
-        Format status dictionary into human-readable summary.
+        """Format status dictionary into human-readable summary.
 
         Args:
-            status: Dictionary mapping output numbers to states
+            status: Dictionary mapping output numbers to states.
 
         Returns:
-            Formatted status summary string
+            Formatted status summary string.
         """
         lines = ["XP24 Output Status:"]
         for output_num in sorted(status.keys()):
@@ -303,14 +301,13 @@ class TelegramOutputService:
 
     @staticmethod
     def format_action_summary(telegram: OutputTelegram) -> str:
-        """
-        Format XP24 action telegram for human-readable output.
+        """Format XP24 action telegram for human-readable output.
 
         Args:
-            telegram: The parsed action telegram
+            telegram: The parsed action telegram.
 
         Returns:
-            Formatted string summary
+            Formatted string summary.
         """
         checksum_status = ""
         if telegram.checksum_validated is not None:

xp/services/telegram/telegram_service.py

@@ -1,3 +1,8 @@
+"""Telegram Service for parsing XP telegrams.
+
+This module provides telegram parsing functionality for event, system, and reply telegrams.
+"""
+
 import re
 from typing import Union
 
@@ -13,17 +18,21 @@ from xp.utils.checksum import calculate_checksum
 
 
 class TelegramParsingError(Exception):
-    """Raised when telegram parsing fails"""
+    """Raised when telegram parsing fails."""
 
     pass
 
 
 class TelegramService:
-    """
-    Service for parsing event telegrams from the console bus.
+    """Service for parsing event telegrams from the console bus.
 
     Handles parsing of telegrams in the format:
     <[EO]{module_type}L{link_number}I{output_number}{event_type}{checksum}>
+
+    Attributes:
+        EVENT_TELEGRAM_PATTERN: Regex pattern for event telegrams.
+        SYSTEM_TELEGRAM_PATTERN: Regex pattern for system telegrams.
+        REPLY_TELEGRAM_PATTERN: Regex pattern for reply telegrams.
     """
 
     # <O06L00I07MAG>
@@ -38,21 +47,20 @@ class TelegramService:
     REPLY_TELEGRAM_PATTERN = re.compile(r"^<R(\d{10})F(\d{2})(.+?)([A-Z0-9]{2})>$")
 
     def __init__(self) -> None:
-        """Initialize the telegram service"""
+        """Initialize the telegram service."""
         pass
 
     def parse_event_telegram(self, raw_telegram: str) -> EventTelegram:
-        """
-        Parse a raw telegram string into an EventTelegram object.
+        """Parse a raw telegram string into an EventTelegram object.
 
         Args:
-            raw_telegram: The raw telegram string (e.g., "<E14L00I02MAK>")
+            raw_telegram: The raw telegram string (e.g., "<E14L00I02MAK>").
 
         Returns:
-            EventTelegram object with parsed data
+            EventTelegram object with parsed data.
 
         Raises:
-            TelegramParsingError: If the telegram format is invalid
+            TelegramParsingError: If the telegram format is invalid.
         """
         if not raw_telegram:
             raise TelegramParsingError("Empty telegram string")
@@ -114,14 +122,13 @@ class TelegramService:
     def validate_checksum(
         telegram: Union[EventTelegram, ReplyTelegram, SystemTelegram, OutputTelegram],
     ) -> bool:
-        """
-        Validate the checksum of a parsed telegram.
+        """Validate the checksum of a parsed telegram.
 
         Args:
-            telegram: The parsed telegram
+            telegram: The parsed telegram.
 
         Returns:
-            True if checksum is valid, False otherwise
+            True if checksum is valid, False otherwise.
         """
         if not telegram.checksum or len(telegram.checksum) != 2:
             return False
@@ -141,14 +148,13 @@ class TelegramService:
 
     @staticmethod
     def format_event_telegram_summary(telegram: EventTelegram) -> str:
-        """
-        Format a telegram for human-readable output.
+        """Format a telegram for human-readable output.
 
         Args:
-            telegram: The parsed telegram
+            telegram: The parsed telegram.
 
         Returns:
-            Formatted string summary
+            Formatted string summary.
         """
         checksum_status = ""
         if telegram.checksum_validated is not None:
@@ -163,17 +169,16 @@ class TelegramService:
         )
 
     def parse_system_telegram(self, raw_telegram: str) -> SystemTelegram:
-        """
-        Parse a raw system telegram string into a SystemTelegram object.
+        """Parse a raw system telegram string into a SystemTelegram object.
 
         Args:
-            raw_telegram: The raw telegram string (e.g., "<S0020012521F02D18FN>")
+            raw_telegram: The raw telegram string (e.g., "<S0020012521F02D18FN>").
 
         Returns:
-            SystemTelegram object with parsed data
+            SystemTelegram object with parsed data.
 
         Raises:
-            TelegramParsingError: If the telegram format is invalid
+            TelegramParsingError: If the telegram format is invalid.
         """
         if not raw_telegram:
             raise TelegramParsingError("Empty telegram string")
@@ -222,17 +227,16 @@ class TelegramService:
             raise TelegramParsingError(f"Invalid values in system telegram: {e}")
 
     def parse_reply_telegram(self, raw_telegram: str) -> ReplyTelegram:
-        """
-        Parse a raw reply telegram string into a ReplyTelegram object.
+        """Parse a raw reply telegram string into a ReplyTelegram object.
 
         Args:
-            raw_telegram: The raw telegram string (e.g., "<R0020012521F02D18+26,0§CIL>")
+            raw_telegram: The raw telegram string (e.g., "<R0020012521F02D18+26,0§CIL>").
 
         Returns:
-            ReplyTelegram object with parsed data
+            ReplyTelegram object with parsed data.
 
         Raises:
-            TelegramParsingError: If the telegram format is invalid
+            TelegramParsingError: If the telegram format is invalid.
         """
         if not raw_telegram:
             raise TelegramParsingError("Empty telegram string")
@@ -290,18 +294,16 @@ class TelegramService:
     def parse_telegram(
         self, raw_telegram: str
     ) -> Union[EventTelegram, SystemTelegram, ReplyTelegram]:
-        """
-        Auto-detect and parse any type of telegram.
+        """Auto-detect and parse any type of telegram.
 
         Args:
-            raw_telegram: The raw telegram string
+            raw_telegram: The raw telegram string.
 
         Returns:
-            Appropriate telegram object based on type
+            Appropriate telegram object based on type.
 
         Raises:
-            TelegramParsingError: If the telegram format is invalid or unknown
-            :rtype: Union[EventTelegram, SystemTelegram, ReplyTelegram]
+            TelegramParsingError: If the telegram format is invalid or unknown.
         """
         if not raw_telegram:
             raise TelegramParsingError("Empty telegram string")
@@ -324,14 +326,13 @@ class TelegramService:
 
     @staticmethod
     def format_system_telegram_summary(telegram: SystemTelegram) -> str:
-        """
-        Format a system telegram for human-readable output.
+        """Format a system telegram for human-readable output.
 
         Args:
-            telegram: The parsed system telegram
+            telegram: The parsed system telegram.
 
         Returns:
-            Formatted string summary
+            Formatted string summary.
         """
         checksum_status = ""
         if telegram.checksum_validated is not None:
@@ -347,14 +348,13 @@ class TelegramService:
 
     @staticmethod
     def format_reply_telegram_summary(telegram: ReplyTelegram) -> str:
-        """
-        Format a reply telegram for human-readable output.
+        """Format a reply telegram for human-readable output.
 
         Args:
-            telegram: The parsed reply telegram
+            telegram: The parsed reply telegram.
 
         Returns:
-            Formatted string summary
+            Formatted string summary.
         """
         parsed_data = telegram.parse_datapoint_value
         data_display = (

xp/services/telegram/telegram_version_service.py

@@ -15,7 +15,7 @@ from xp.utils.checksum import calculate_checksum
 
 
 class VersionParsingError(Exception):
-    """Raised when version parsing fails"""
+    """Raised when version parsing fails."""
 
     pass
 
@@ -204,7 +204,9 @@ class VersionService:
                 return Response(
                     success=False,
                     data=None,
-                    error=f"Not a version reply telegram. Data point: {telegram.datapoint_type.name if telegram.datapoint_type else 'Unknown'}",
+                    error=f"Not a version reply telegram. "
+                    f"Data point: "
+                    f"{telegram.datapoint_type.name if telegram.datapoint_type else 'Unknown'}",
                 )
 
             # Parse the version using the telegram's built-in parser

xp/utils/__init__.py

@@ -1,4 +1,4 @@
-"""Utility functions for XP CLI tool"""
+"""Utility functions for XP CLI tool."""
 
 from xp.utils.checksum import calculate_checksum
 from xp.utils.event_helper import get_first_response

xp/utils/dependencies.py

@@ -101,7 +101,6 @@ class ServiceContainer:
 
     def _register_services(self) -> None:
         """Register all services in the container based on dependency graph."""
-
         # ConbusClientConfig
         self.container.register(
             ConbusClientConfig,

xp/utils/serialization.py

@@ -153,6 +153,9 @@ def de_nibble(nibble_str: str) -> int:
 
     Returns:
         Byte value (0-255)
+
+    Raises:
+        ValueError: If nibble string is not exactly 2 characters
     """
     if len(nibble_str) != 2:
         raise ValueError("Nibble string must be exactly 2 characters")
@@ -177,6 +180,9 @@ def de_nibbles(str_val: str) -> bytearray:
 
     Returns:
         List of integers representing the decoded bytes
+
+    Raises:
+        ValueError: If string length is not even for nibble conversion
     """
     if len(str_val) % 2 != 0:
         raise ValueError("String length must be even for nibble conversion")

xp/utils/time_utils.py

@@ -6,7 +6,7 @@ from typing import Optional
 
 
 class TimeParsingError(Exception):
-    """Raised when time parsing fails"""
+    """Raised when time parsing fails."""
 
     pass
 
@@ -14,8 +14,7 @@ class TimeParsingError(Exception):
 def parse_log_timestamp(
     timestamp_str: str, base_date: Optional[datetime] = None
 ) -> datetime:
-    """
-    Parse timestamp from console bus log format: HH:MM:SS,mmm
+    """Parse timestamp from console bus log format: HH:MM:SS,mmm.
 
     Args:
         timestamp_str: Timestamp string (e.g., "22:44:20,352")
@@ -66,8 +65,7 @@ def parse_log_timestamp(
 
 
 def format_log_timestamp(dt: datetime) -> str:
-    """
-    Format datetime to console bus log timestamp format: HH:MM:SS,mmm
+    """Format datetime to console bus log timestamp format: HH:MM:SS,mmm.
 
     Args:
         dt: datetime object to format
@@ -81,8 +79,7 @@ def format_log_timestamp(dt: datetime) -> str:
 def parse_time_range(
     time_range_str: str, base_date: Optional[datetime] = None
 ) -> tuple[datetime, datetime]:
-    """
-    Parse time range string like "22:44:20,352-22:44:25,500"
+    """Parse time range string like "22:44:20,352-22:44:25,500".
 
     Args:
         time_range_str: Time range string
@@ -108,8 +105,7 @@ def parse_time_range(
 
 
 def calculate_duration_ms(start_time: datetime, end_time: datetime) -> int:
-    """
-    Calculate duration between two timestamps in milliseconds
+    """Calculate duration between two timestamps in milliseconds.
 
     Args:
         start_time: Start timestamp
@@ -123,8 +119,7 @@ def calculate_duration_ms(start_time: datetime, end_time: datetime) -> int:
 
 
 def is_valid_log_timestamp(timestamp_str: str) -> bool:
-    """
-    Check if timestamp string is valid console bus log format
+    """Check if timestamp string is valid console bus log format.
 
     Args:
         timestamp_str: Timestamp string to validate