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

xp/services/telegram/telegram_link_number_service.py

@@ -15,7 +15,7 @@ from xp.utils.checksum import calculate_checksum
 
 
 class LinkNumberError(Exception):
-    """Raised when link number operations fail"""
+    """Raised when link number operations fail."""
 
     pass
 
@@ -29,23 +29,22 @@ class LinkNumberService:
     """
 
     def __init__(self) -> None:
-        """Initialize the link number service"""
+        """Initialize the link number service."""
         pass
 
     @staticmethod
     def generate_set_link_number_telegram(serial_number: str, link_number: int) -> str:
-        """
-        Generate a telegram to set a module's link number.
+        """Generate a telegram to set a module's link number.
 
         Args:
-            serial_number: The 10-digit module serial number
-            link_number: The link number to set (0-99)
+            serial_number: The 10-digit module serial number.
+            link_number: The link number to set (0-99).
 
         Returns:
-            Formatted telegram string (e.g., "<S0012345005F04D0425FO>")
+            Formatted telegram string (e.g., "<S0012345005F04D0425FO>").
 
         Raises:
-            LinkNumberError: If parameters are invalid
+            LinkNumberError: If parameters are invalid.
         """
         # Validate serial number
         if not serial_number or len(serial_number) != 10:
@@ -80,17 +79,16 @@ class LinkNumberService:
 
     @staticmethod
     def generate_read_link_number_telegram(serial_number: str) -> str:
-        """
-        Generate a telegram to read a module's current link number.
+        """Generate a telegram to read a module's current link number.
 
         Args:
-            serial_number: The 10-digit module serial number
+            serial_number: The 10-digit module serial number.
 
         Returns:
-            Formatted telegram string for reading link number
+            Formatted telegram string for reading link number.
 
         Raises:
-            LinkNumberError: If serial number is invalid
+            LinkNumberError: If serial number is invalid.
         """
         # Validate serial number
         if not serial_number or len(serial_number) != 10:
@@ -117,18 +115,14 @@ class LinkNumberService:
     def create_set_link_number_telegram_object(
         self, serial_number: str, link_number: int
     ) -> SystemTelegram:
-        """
-        Create a SystemTelegram object for setting link number.
+        """Create a SystemTelegram object for setting link number.
 
         Args:
-            serial_number: The 10-digit module serial number
-            link_number: The link number to set (0-99)
+            serial_number: The 10-digit module serial number.
+            link_number: The link number to set (0-99).
 
         Returns:
-            SystemTelegram object representing the set link number command
-
-        Raises:
-            LinkNumberError: If parameters are invalid
+            SystemTelegram object representing the set link number command.
         """
         raw_telegram = self.generate_set_link_number_telegram(
             serial_number, link_number
@@ -150,17 +144,13 @@ class LinkNumberService:
     def create_read_link_number_telegram_object(
         self, serial_number: str
     ) -> SystemTelegram:
-        """
-        Create a SystemTelegram object for reading link number.
+        """Create a SystemTelegram object for reading link number.
 
         Args:
-            serial_number: The 10-digit module serial number
+            serial_number: The 10-digit module serial number.
 
         Returns:
-            SystemTelegram object representing the read link number command
-
-        Raises:
-            LinkNumberError: If serial number is invalid
+            SystemTelegram object representing the read link number command.
         """
         raw_telegram = self.generate_read_link_number_telegram(serial_number)
 
@@ -179,14 +169,13 @@ class LinkNumberService:
 
     @staticmethod
     def parse_link_number_from_reply(reply_telegram: ReplyTelegram) -> Optional[int]:
-        """
-        Parse the link number value from a reply telegram.
+        """Parse the link number value from a reply telegram.
 
         Args:
-            reply_telegram: Reply telegram containing link number data
+            reply_telegram: Reply telegram containing link number data.
 
         Returns:
-            Link number if successfully parsed, None otherwise
+            Link number if successfully parsed, None otherwise.
         """
         if (
             reply_telegram.datapoint_type != DataPointType.LINK_NUMBER
@@ -204,26 +193,24 @@ class LinkNumberService:
 
     @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_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