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

xp/services/log_file_service.py

@@ -15,7 +15,7 @@ from xp.utils.time_utils import (
 
 
 class LogFileParsingError(Exception):
-    """Raised when log file parsing fails"""
+    """Raised when log file parsing fails."""
 
     pass
 
@@ -26,6 +26,10 @@ class LogFileService:
 
     Handles parsing of log files containing timestamped telegram transmissions
     and receptions with automatic telegram parsing and validation.
+
+    Attributes:
+        telegram_service: Telegram service for parsing telegrams.
+        LOG_LINE_PATTERN: Regex pattern for log line format.
     """
 
     # Regex pattern for log line format: HH:MM:SS,mmm [TX/RX] <telegram>
@@ -34,29 +38,27 @@ class LogFileService:
     )
 
     def __init__(self, telegram_service: TelegramService):
-        """
-        Initialize the log file service
+        """Initialize the log file service.
 
         Args:
-            telegram_service: Telegram service for parsing telegrams
+            telegram_service: Telegram service for parsing telegrams.
         """
         self.telegram_service = telegram_service
 
     def parse_log_file(
         self, file_path: str, base_date: Optional[datetime] = None
     ) -> List[LogEntry]:
-        """
-        Parse a console bus log file into LogEntry objects
+        """Parse a console bus log file into LogEntry objects.
 
         Args:
-            file_path: Path to the log file
-            base_date: Base date for timestamps (defaults to today)
+            file_path: Path to the log file.
+            base_date: Base date for timestamps (defaults to today).
 
         Returns:
-            List of parsed LogEntry objects
+            List of parsed LogEntry objects.
 
         Raises:
-            LogFileParsingError: If file cannot be read or parsed
+            LogFileParsingError: If file cannot be read or parsed.
         """
         try:
             path = Path(file_path)
@@ -77,15 +79,14 @@ class LogFileService:
     def parse_log_lines(
         self, lines: List[str], base_date: Optional[datetime] = None
     ) -> List[LogEntry]:
-        """
-        Parse log lines into LogEntry objects
+        """Parse log lines into LogEntry objects.
 
         Args:
-            lines: List of log lines to parse
-            base_date: Base date for timestamps
+            lines: List of log lines to parse.
+            base_date: Base date for timestamps.
 
         Returns:
-            List of parsed LogEntry objects
+            List of parsed LogEntry objects.
         """
         entries = []
 
@@ -114,16 +115,15 @@ class LogFileService:
     def _parse_log_line(
         self, line: str, line_number: int, base_date: Optional[datetime] = None
     ) -> Optional[LogEntry]:
-        """
-        Parse a single log line into a LogEntry
+        """Parse a single log line into a LogEntry.
 
         Args:
-            line: Log line to parse
-            line_number: Line number in the file
-            base_date: Base date for timestamp
+            line: Log line to parse.
+            line_number: Line number in the file.
+            base_date: Base date for timestamp.
 
         Returns:
-            LogEntry object or None if line format is invalid
+            LogEntry object or None if line format is invalid.
         """
         match = self.LOG_LINE_PATTERN.match(line)
         if not match:
@@ -157,14 +157,13 @@ class LogFileService:
         return entry
 
     def validate_log_format(self, file_path: str) -> bool:
-        """
-        Validate that a file follows the expected log format
+        """Validate that a file follows the expected log format.
 
         Args:
-            file_path: Path to the log file
+            file_path: Path to the log file.
 
         Returns:
-            True if format is valid, False otherwise
+            True if format is valid, False otherwise.
         """
         try:
             entries = self.parse_log_file(file_path)
@@ -175,28 +174,26 @@ class LogFileService:
             return False
 
     def extract_telegrams(self, file_path: str) -> List[str]:
-        """
-        Extract all telegram strings from a log file
+        """Extract all telegram strings from a log file.
 
         Args:
-            file_path: Path to the log file
+            file_path: Path to the log file.
 
         Returns:
-            List of telegram strings
+            List of telegram strings.
         """
         entries = self.parse_log_file(file_path)
         return [entry.raw_telegram for entry in entries]
 
     @staticmethod
     def get_file_statistics(entries: List[LogEntry]) -> Dict[str, Any]:
-        """
-        Generate statistics for a list of log entries
+        """Generate statistics for a list of log entries.
 
         Args:
-            entries: List of LogEntry objects
+            entries: List of LogEntry objects.
 
         Returns:
-            Dictionary containing statistics
+            Dictionary containing statistics.
         """
         if not entries:
             return {"total_entries": 0}
@@ -283,18 +280,17 @@ class LogFileService:
         start_time: Optional[datetime] = None,
         end_time: Optional[datetime] = None,
     ) -> List[LogEntry]:
-        """
-        Filter log entries based on criteria
+        """Filter log entries based on criteria.
 
         Args:
-            entries: List of LogEntry objects to filter
-            telegram_type: Filter by telegram type (event, system, reply)
-            direction: Filter by direction (TX, RX)
-            start_time: Filter entries after this time
-            end_time: Filter entries before this time
+            entries: List of LogEntry objects to filter.
+            telegram_type: Filter by telegram type (event, system, reply).
+            direction: Filter by direction (TX, RX).
+            start_time: Filter entries after this time.
+            end_time: Filter entries before this time.
 
         Returns:
-            Filtered list of LogEntry objects
+            Filtered list of LogEntry objects.
         """
         filtered = entries.copy()
 

xp/services/module_type_service.py

@@ -1,3 +1,8 @@
+"""Module Type Service for XP module management.
+
+This module provides lookup, validation, and search functionality for XP system module types.
+"""
+
 from typing import Dict, List, Optional, Union
 
 from xp.models.telegram.module_type import (
@@ -9,7 +14,7 @@ from xp.models.telegram.module_type import (
 
 
 class ModuleTypeNotFoundError(Exception):
-    """Raised when a module type cannot be found"""
+    """Raised when a module type cannot be found."""
 
     pass
 
@@ -17,11 +22,12 @@ class ModuleTypeNotFoundError(Exception):
 class ModuleTypeService:
     """
     Service for managing module type operations.
+
     Provides lookup, validation, and search functionality for XP system module types.
     """
 
     def __init__(self) -> None:
-        """Initialize the module type service"""
+        """Initialize the module type service."""
         pass
 
     @staticmethod
@@ -193,7 +199,14 @@ class ModuleTypeService:
 
     @staticmethod
     def _format_module_summary(module_type: ModuleType) -> str:
-        """Format a single module type for display"""
+        """Format a single module type for display.
+
+        Args:
+            module_type: The module type to format.
+
+        Returns:
+            Formatted string with module information.
+        """
         summary = f"Module: {module_type.name} (Code {module_type.code})\n"
         summary += f"Description: {module_type.description}\n"
         summary += f"Category: {module_type.category}\n"
@@ -213,7 +226,11 @@ class ModuleTypeService:
 
     @staticmethod
     def _format_all_modules() -> str:
-        """Format all modules in a simple list"""
+        """Format all modules in a simple list.
+
+        Returns:
+            Formatted string with all modules.
+        """
         modules = get_all_module_types()
         lines = ["Code | Name       | Description", "-" * 60]
 
@@ -224,7 +241,11 @@ class ModuleTypeService:
 
     @staticmethod
     def _format_modules_by_category() -> str:
-        """Format modules grouped by category"""
+        """Format modules grouped by category.
+
+        Returns:
+            Formatted string with modules grouped by category.
+        """
         categories = get_module_types_by_category()
         lines = []
 

xp/services/protocol/__init__.py

@@ -1,4 +1,4 @@
-"""Protocol layer services for XP"""
+"""Protocol layer services for XP."""
 
 from xp.models.protocol.conbus_protocol import (
     ConnectionMadeEvent,

xp/services/protocol/conbus_protocol.py

@@ -1,3 +1,8 @@
+"""Conbus Protocol for XP telegram communication.
+
+This module implements the Twisted protocol for Conbus communication.
+"""
+
 import logging
 from typing import Any, Optional
 
@@ -17,8 +22,15 @@ from xp.utils import calculate_checksum
 
 
 class ConbusProtocol(protocol.Protocol, protocol.ClientFactory):
-    """
-    Twisted protocol for XP telegram communication.
+    """Twisted protocol for XP telegram communication.
+
+    Attributes:
+        buffer: Buffer for incoming telegram data.
+        logger: Logger instance for this protocol.
+        cli_config: Conbus configuration settings.
+        reactor: Twisted reactor instance.
+        timeout_seconds: Timeout duration in seconds.
+        timeout_call: Delayed call handle for timeout management.
     """
 
     buffer: bytes
@@ -28,6 +40,12 @@ class ConbusProtocol(protocol.Protocol, protocol.ClientFactory):
         cli_config: ConbusClientConfig,
         reactor: PosixReactorBase,
     ) -> None:
+        """Initialize ConbusProtocol.
+
+        Args:
+            cli_config: Configuration for Conbus client connection.
+            reactor: Twisted reactor for event handling.
+        """
         self.buffer = b""
         self.logger = logging.getLogger(__name__)
         self.cli_config = cli_config.conbus
@@ -36,12 +54,24 @@ class ConbusProtocol(protocol.Protocol, protocol.ClientFactory):
         self.timeout_call: Optional[DelayedCall] = None
 
     def connectionMade(self) -> None:
+        """Handle connection established event.
+
+        Called when TCP connection is successfully established.
+        Starts inactivity timeout monitoring.
+        """
         self.logger.debug("connectionMade")
         self.connection_established()
         # Start inactivity timeout
         self._reset_timeout()
 
     def dataReceived(self, data: bytes) -> None:
+        """Handle received data from TCP connection.
+
+        Parses incoming telegram frames and dispatches events.
+
+        Args:
+            data: Raw bytes received from connection.
+        """
         self.logger.debug("dataReceived")
         self.buffer += data
 
@@ -94,11 +124,13 @@ class ConbusProtocol(protocol.Protocol, protocol.ClientFactory):
             self.telegram_received(telegram_received)
 
     def sendFrame(self, data: bytes) -> None:
-        """
-        Send telegram frame
+        """Send telegram frame.
 
         Args:
-            data: Raw telegram payload (without checksum/framing)
+            data: Raw telegram payload (without checksum/framing).
+
+        Raises:
+            IOError: If transport is not open.
         """
         # Calculate full frame (add checksum and brackets)
         checksum = calculate_checksum(data.decode())
@@ -121,6 +153,14 @@ class ConbusProtocol(protocol.Protocol, protocol.ClientFactory):
         system_function: SystemFunction,
         data_value: str,
     ) -> None:
+        """Send telegram with specified parameters.
+
+        Args:
+            telegram_type: Type of telegram to send.
+            serial_number: Device serial number.
+            system_function: System function code.
+            data_value: Data value to send.
+        """
         payload = (
             f"{telegram_type.value}"
             f"{serial_number}"
@@ -130,33 +170,62 @@ class ConbusProtocol(protocol.Protocol, protocol.ClientFactory):
         self.sendFrame(payload.encode())
 
     def buildProtocol(self, addr: IAddress) -> protocol.Protocol:
+        """Build protocol instance for connection.
+
+        Args:
+            addr: Address of the connection.
+
+        Returns:
+            Protocol instance for this connection.
+        """
         self.logger.debug(f"buildProtocol: {addr}")
         return self
 
     def clientConnectionFailed(self, connector: IConnector, reason: Failure) -> None:
+        """Handle client connection failure.
+
+        Args:
+            connector: Connection connector instance.
+            reason: Failure reason details.
+        """
         self.logger.debug(f"clientConnectionFailed: {reason}")
         self.connection_failed(reason)
         self._cancel_timeout()
         self._stop_reactor()
 
     def clientConnectionLost(self, connector: IConnector, reason: Failure) -> None:
+        """Handle client connection lost event.
+
+        Args:
+            connector: Connection connector instance.
+            reason: Reason for connection loss.
+        """
         self.logger.debug(f"clientConnectionLost: {reason}")
         self.connection_lost(reason)
         self._cancel_timeout()
         self._stop_reactor()
 
     def timeout(self) -> bool:
-        """Timeout callback, return True to continue waiting for next timeout, False to stop"""
+        """Handle timeout event.
+
+        Returns:
+            True to continue waiting for next timeout, False to stop.
+        """
         self.logger.info("Timeout after: %ss", self.timeout_seconds)
         self.failed(f"Timeout after: {self.timeout_seconds}s")
         return False
 
     def connection_failed(self, reason: Failure) -> None:
+        """Handle connection failure.
+
+        Args:
+            reason: Failure reason details.
+        """
         self.logger.debug(f"Client connection failed: {reason}")
         self.failed(reason.getErrorMessage())
 
     def _reset_timeout(self) -> None:
-        """Reset the inactivity timeout"""
+        """Reset the inactivity timeout."""
         self._cancel_timeout()
         self.timeout_call = self.reactor.callLater(
             self.timeout_seconds, self._on_timeout
@@ -164,26 +233,26 @@ class ConbusProtocol(protocol.Protocol, protocol.ClientFactory):
         self.logger.debug(f"Timeout set for {self.timeout_seconds} seconds")
 
     def _cancel_timeout(self) -> None:
-        """Cancel the inactivity timeout"""
+        """Cancel the inactivity timeout."""
         if self.timeout_call and self.timeout_call.active():
             self.timeout_call.cancel()
             self.logger.debug("Timeout cancelled")
 
     def _on_timeout(self) -> None:
-        """Called when inactivity timeout expires"""
+        """Handle inactivity timeout expiration."""
         self.logger.debug(f"Conbus timeout after {self.timeout_seconds} seconds")
         continue_work = self.timeout()
         if not continue_work:
             self._stop_reactor()
 
     def _stop_reactor(self) -> None:
-        """Stop the reactor if it's running"""
+        """Stop the reactor if it's running."""
         if self.reactor.running:
             self.logger.info("Stopping reactor")
             self.reactor.stop()
 
     def start_reactor(self) -> None:
-        """Start the reactor if it's running"""
+        """Start the reactor if it's running."""
         # Connect to TCP server
         self.logger.info(
             f"Connecting to TCP server {self.cli_config.ip}:{self.cli_config.port}"
@@ -191,11 +260,15 @@ class ConbusProtocol(protocol.Protocol, protocol.ClientFactory):
         self.reactor.connectTCP(self.cli_config.ip, self.cli_config.port, self)
 
         # Run the reactor (which now uses asyncio underneath)
-        self.logger.info("Starting reactor event loop...")
+        self.logger.info("Starting reactor event loop.")
         self.reactor.run()
 
     def __enter__(self) -> "ConbusProtocol":
-        """Context manager entry"""
+        """Enter context manager.
+
+        Returns:
+            Self for context management.
+        """
         return self
 
     def __exit__(
@@ -204,23 +277,44 @@ class ConbusProtocol(protocol.Protocol, protocol.ClientFactory):
         _exc_val: Optional[BaseException],
         _exc_tb: Optional[Any],
     ) -> None:
-        """Context manager exit - ensure connection is closed"""
-        self.logger.debug("Exiting the event loop...")
+        """Context manager exit - ensure connection is closed."""
+        self.logger.debug("Exiting the event loop.")
         self._stop_reactor()
 
-    """Override methods"""
+    """Override methods."""
 
     def telegram_sent(self, telegram_sent: str) -> None:
+        """Override callback when telegram has been sent.
+
+        Args:
+            telegram_sent: The telegram that was sent.
+        """
         pass
 
     def telegram_received(self, telegram_received: TelegramReceivedEvent) -> None:
+        """Override callback when telegram is received.
+
+        Args:
+            telegram_received: Event containing received telegram details.
+        """
         pass
 
     def connection_established(self) -> None:
+        """Override callback when connection established."""
         pass
 
     def connection_lost(self, reason: Failure) -> None:
+        """Override callback when connection is lost.
+
+        Args:
+            reason: Reason for connection loss.
+        """
         pass
 
     def failed(self, message: str) -> None:
+        """Override callback when connection failed.
+
+        Args:
+            message: Error message describing the failure.
+        """
         pass

xp/services/protocol/protocol_factory.py

@@ -1,3 +1,8 @@
+"""Protocol Factory for Twisted protocol creation.
+
+This module provides factory classes for protocol instantiation.
+"""
+
 import logging
 
 from bubus import EventBus
@@ -13,26 +18,61 @@ from xp.services.protocol import TelegramProtocol
 
 
 class TelegramFactory(protocol.ClientFactory):
+    """Factory for creating Telegram protocol instances.
+
+    Attributes:
+        event_bus: Event bus for dispatching protocol events.
+        telegram_protocol: Protocol instance to use.
+        connector: Connection connector instance.
+        logger: Logger instance for this factory.
+    """
+
     def __init__(
         self,
         event_bus: EventBus,
         telegram_protocol: TelegramProtocol,
         connector: IConnector,
     ) -> None:
+        """Initialize TelegramFactory.
 
+        Args:
+            event_bus: Event bus for protocol events.
+            telegram_protocol: Protocol instance to use for connections.
+            connector: Connection connector for managing connections.
+        """
         self.event_bus = event_bus
         self.telegram_protocol = telegram_protocol
         self.connector = connector
         self.logger = logging.getLogger(__name__)
 
     def buildProtocol(self, addr: IAddress) -> TelegramProtocol:
+        """Build protocol instance for connection.
+
+        Args:
+            addr: Address of the connection.
+
+        Returns:
+            Telegram protocol instance for this connection.
+        """
         self.logger.debug(f"buildProtocol: {addr}")
         return self.telegram_protocol
 
     def clientConnectionFailed(self, connector: IConnector, reason: Failure) -> None:
+        """Handle connection failure event.
+
+        Args:
+            connector: Connection connector instance.
+            reason: Failure reason details.
+        """
         self.event_bus.dispatch(ConnectionFailedEvent(reason=str(reason)))
         self.connector.stop()
 
     def clientConnectionLost(self, connector: IConnector, reason: Failure) -> None:
+        """Handle connection lost event.
+
+        Args:
+            connector: Connection connector instance.
+            reason: Reason for connection loss.
+        """
         self.event_bus.dispatch(ConnectionLostEvent(reason=str(reason)))
         self.connector.stop()

xp/services/protocol/telegram_protocol.py

@@ -1,3 +1,8 @@
+"""Telegram Protocol for XP telegram communication.
+
+This module provides the protocol implementation for telegram-based communication.
+"""
+
 import asyncio
 import logging
 import time
@@ -15,17 +20,30 @@ from xp.utils import calculate_checksum
 
 
 class TelegramProtocol(protocol.Protocol):
-    """
-    Twisted protocol for XP telegram communication with built-in debouncing.
+    """Twisted protocol for XP telegram communication with built-in debouncing.
 
     Automatically deduplicates identical telegram frames sent within a
     configurable time window (default 50ms).
+
+    Attributes:
+        buffer: Buffer for incoming telegram data.
+        event_bus: Event bus for dispatching protocol events.
+        debounce_ms: Debounce time window in milliseconds.
+        logger: Logger instance for this protocol.
+        send_queue: Dictionary tracking frame send timestamps.
+        timer_handle: Handle for cleanup timer.
     """
 
     buffer: bytes
     event_bus: EventBus
 
     def __init__(self, event_bus: EventBus, debounce_ms: int = 50) -> None:
+        """Initialize TelegramProtocol.
+
+        Args:
+            event_bus: Event bus for dispatching protocol events.
+            debounce_ms: Debounce time window in milliseconds.
+        """
         self.buffer = b""
         self.event_bus = event_bus
         self.debounce_ms = debounce_ms
@@ -36,6 +54,7 @@ class TelegramProtocol(protocol.Protocol):
         self.timer_handle: Optional[asyncio.TimerHandle] = None
 
     def connectionMade(self) -> None:
+        """Handle connection established event."""
         self.logger.debug("connectionMade")
         try:
             self.logger.debug("Scheduling async connection handler")
@@ -45,7 +64,11 @@ class TelegramProtocol(protocol.Protocol):
             self.logger.error(f"Error scheduling async handler: {e}", exc_info=True)
 
     def _on_task_done(self, task: asyncio.Task) -> None:
-        """Callback when async task completes"""
+        """Handle async task completion.
+
+        Args:
+            task: Completed async task.
+        """
         try:
             if task.exception():
                 self.logger.error(
@@ -57,7 +80,7 @@ class TelegramProtocol(protocol.Protocol):
             self.logger.error(f"Error in task done callback: {e}", exc_info=True)
 
     async def _async_connection_made(self) -> None:
-        """Async handler for connection made"""
+        """Async handler for connection made."""
         self.logger.debug("_async_connectionMade starting")
         self.logger.info("Dispatching ConnectionMadeEvent")
         try:
@@ -69,12 +92,16 @@ class TelegramProtocol(protocol.Protocol):
             )
 
     def dataReceived(self, data: bytes) -> None:
-        """Sync callback from Twisted - delegates to async implementation"""
+        """Handle received data from Twisted.
+
+        Args:
+            data: Raw bytes received from connection.
+        """
         task = asyncio.create_task(self._async_dataReceived(data))
         task.add_done_callback(self._on_task_done)
 
     async def _async_dataReceived(self, data: bytes) -> None:
-        """Async handler for received data"""
+        """Async handler for received data."""
         self.logger.debug("dataReceived")
         self.buffer += data
 
@@ -137,7 +164,11 @@ class TelegramProtocol(protocol.Protocol):
             )
 
     def sendFrame(self, data: bytes) -> None:
-        """Sync callback from Twisted - delegates to async implementation"""
+        """Send telegram frame.
+
+        Args:
+            data: Raw telegram payload (without checksum/framing).
+        """
         task = asyncio.create_task(self._async_sendFrame(data))
         task.add_done_callback(self._on_task_done)