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

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)
 

xp/services/reverse_proxy_service.py

@@ -16,7 +16,7 @@ from xp.models.response import Response
 
 
 class ReverseProxyError(Exception):
-    """Raised when Conbus reverse proxy operations fail"""
+    """Raised when Conbus reverse proxy operations fail."""
 
     pass
 
@@ -28,6 +28,17 @@ class ReverseProxyService:
     Accepts client connections on port 10001 and forwards all telegrams
     to the target server configured in cli.yml. Monitors and prints all
     bidirectional traffic with timestamps.
+
+    Attributes:
+        logger: Logger instance for the service.
+        listen_port: Port to listen on for client connections.
+        server_socket: Main server socket for accepting connections.
+        is_running: Flag indicating if proxy is running.
+        active_connections: Dictionary of active connection information.
+        connection_counter: Counter for connection IDs.
+        cli_config: Conbus client configuration.
+        target_ip: Target server IP address.
+        target_port: Target server port number.
     """
 
     def __init__(
@@ -35,7 +46,12 @@ class ReverseProxyService:
         cli_config: ConbusClientConfig,
         listen_port: int,
     ):
-        """Initialize the Conbus reverse proxy service"""
+        """Initialize the Conbus reverse proxy service.
+
+        Args:
+            cli_config: Conbus client configuration.
+            listen_port: Port to listen on for client connections.
+        """
         # Set up logging first
         self.logger = logging.getLogger(__name__)
 
@@ -50,16 +66,28 @@ class ReverseProxyService:
 
     @property
     def target_ip(self) -> str:
-        """Get target server IP"""
+        """Get target server IP.
+
+        Returns:
+            Target server IP address.
+        """
         return self.cli_config.conbus.ip
 
     @property
     def target_port(self) -> int:
-        """Get target server port"""
+        """Get target server port.
+
+        Returns:
+            Target server port number.
+        """
         return self.cli_config.conbus.port
 
     def start_proxy(self) -> Response:
-        """Start the reverse proxy server"""
+        """Start the reverse proxy server.
+
+        Returns:
+            Response object with success status and proxy details.
+        """
         if self.is_running:
             return Response(
                 success=False, data=None, error="Reverse proxy is already running"
@@ -111,7 +139,11 @@ class ReverseProxyService:
             )
 
     def stop_proxy(self) -> Response:
-        """Stop the reverse proxy server"""
+        """Stop the reverse proxy server.
+
+        Returns:
+            Response object with success status.
+        """
         if not self.is_running:
             return Response(
                 success=False, data=None, error="Reverse proxy is not running"
@@ -139,7 +171,11 @@ class ReverseProxyService:
         )
 
     def get_status(self) -> Response:
-        """Get current proxy status and active connections"""
+        """Get current proxy status and active connections.
+
+        Returns:
+            Response object with proxy status and connection details.
+        """
         return Response(
             success=True,
             data={
@@ -161,7 +197,7 @@ class ReverseProxyService:
         )
 
     def _accept_connections(self) -> None:
-        """Accept and handle client connections"""
+        """Accept and handle client connections."""
         while self.is_running:
             try:
                 # Accept connection
@@ -194,7 +230,13 @@ class ReverseProxyService:
     def _handle_client(
         self, client_socket: socket.socket, client_address: tuple, conn_id: str
     ) -> None:
-        """Handle individual client connection with server relay"""
+        """Handle individual client connection with server relay.
+
+        Args:
+            client_socket: Client socket connection.
+            client_address: Client address tuple (ip, port).
+            conn_id: Connection identifier.
+        """
         try:
             # Connect to target server
             server_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
@@ -272,7 +314,15 @@ class ReverseProxyService:
         dest_label: str,
         conn_id: str,
     ) -> None:
-        """Relay data between sockets with telegram monitoring"""
+        """Relay data between sockets with telegram monitoring.
+
+        Args:
+            source_socket: Source socket to receive from.
+            dest_socket: Destination socket to send to.
+            source_label: Label for source in logs.
+            dest_label: Label for destination in logs.
+            conn_id: Connection identifier.
+        """
         try:
             while self.is_running:
                 # Receive data from source
@@ -316,7 +366,11 @@ class ReverseProxyService:
                 self.logger.error(f"Error in data relay: {e} [{conn_id}]")
 
     def _close_connection_pair(self, conn_id: str) -> None:
-        """Close both client and server sockets for a connection"""
+        """Close both client and server sockets for a connection.
+
+        Args:
+            conn_id: Connection identifier.
+        """
         if conn_id not in self.active_connections:
             return
 
@@ -344,7 +398,10 @@ class ReverseProxyService:
             f"Client {client_address} disconnected [{conn_id}] - {bytes_relayed} bytes relayed"
         )
         print(
-            f"{self.timestamp()} [DISCONNECTION] Client {client_address} disconnected [{conn_id}] - {bytes_relayed} bytes relayed"
+            f"{self.timestamp()} [DISCONNECTION] "
+            f"Client {client_address} "
+            f"disconnected [{conn_id}] - "
+            f"{bytes_relayed} bytes relayed"
         )
 
         # Remove from active connections
@@ -352,11 +409,19 @@ class ReverseProxyService:
 
     @staticmethod
     def timestamp() -> str:
-        """Generate timestamp string for logging"""
+        """Generate timestamp string for logging.
+
+        Returns:
+            Timestamp string in HH:MM:SS,mmm format.
+        """
         return datetime.now().strftime("%H:%M:%S,%f")[:-3]
 
     def run_blocking(self) -> None:
-        """Run the proxy in blocking mode (for CLI usage)"""
+        """Run the proxy in blocking mode (for CLI usage).
+
+        Raises:
+            ReverseProxyError: If proxy fails to start.
+        """
         result = self.start_proxy()
         if not result.success:
             raise ReverseProxyError(result.error)

xp/services/server/__init__.py

@@ -0,0 +1 @@
+"""Server services for XP protocol variants."""