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

xp/cli/commands/module_commands.py

@@ -17,9 +17,7 @@ from xp.services.module_type_service import ModuleTypeNotFoundError, ModuleTypeS
     cls=HelpColorsGroup, help_headers_color="yellow", help_options_color="green"
 )
 def module() -> None:
-    """
-    Module type operations
-    """
+    """Perform module type operations."""
     pass
 
 
@@ -28,12 +26,14 @@ def module() -> None:
 @click.pass_context
 @list_command(ModuleTypeNotFoundError)
 def module_info(ctx: Context, identifier: str) -> None:
-    """
-    Get information about a module type by code or name.
+    r"""Get information about a module type by code or name.
 
-    Examples:
+    Args:
+        ctx: Click context object.
+        identifier: Module code or name.
 
-    \b
+    Examples:
+        \b
         xp module info 14
         xp module info XP2606
     """
@@ -63,12 +63,15 @@ def module_info(ctx: Context, identifier: str) -> None:
 @click.pass_context
 @list_command(Exception)
 def module_list(ctx: Context, category: str, group_by_category: bool) -> None:
-    """
-    List module types, optionally filtered by category.
+    r"""List module types, optionally filtered by category.
 
-    Examples:
+    Args:
+        ctx: Click context object.
+        category: Filter by category.
+        group_by_category: Group modules by category.
 
-    \b
+    Examples:
+        \b
         xp module list
         xp module list --category "Interface Panels"
         xp module list --group-by-category
@@ -115,12 +118,15 @@ def module_list(ctx: Context, category: str, group_by_category: bool) -> None:
 @click.pass_context
 @list_command(Exception)
 def module_search(ctx: Context, query: str, field: tuple) -> None:
-    """
-    Search for module types by name or description.
+    r"""Search for module types by name or description.
 
-    Examples:
+    Args:
+        ctx: Click context object.
+        query: Search query.
+        field: Fields to search in.
 
-    \b
+    Examples:
+        \b
         xp module search "push button"
         xp module search --field name "XP"
     """
@@ -147,12 +153,13 @@ def module_search(ctx: Context, query: str, field: tuple) -> None:
 @click.pass_context
 @list_command(Exception)
 def module_categories(ctx: Context) -> None:
-    """
-    List all available module categories.
+    r"""List all available module categories.
 
-    Examples:
+    Args:
+        ctx: Click context object.
 
-    \b
+    Examples:
+        \b
         xp module categories
     """
     service = ctx.obj.get("container").get_container().resolve(ModuleTypeService)

xp/cli/commands/reverse_proxy_commands.py

@@ -29,9 +29,7 @@ global_proxy_instance: Optional[ReverseProxyService] = None
     help_options_color="green",
 )
 def reverse_proxy() -> None:
-    """
-    Conbus reverse proxy operations
-    """
+    """Perform Conbus reverse proxy operations."""
     pass
 
 
@@ -43,18 +41,24 @@ def reverse_proxy() -> None:
 @handle_service_errors(ReverseProxyError)
 @click.pass_context
 def start_proxy(ctx: Context, port: int, config: str) -> None:
-    """
-    Start the Conbus reverse proxy server.
+    r"""Start the Conbus reverse proxy server.
 
     The proxy listens on the specified port and forwards all telegrams
     to the target server configured in cli.yml. All traffic is monitored
     and printed with timestamps.
 
-    Examples:
+    Args:
+        ctx: Click context object.
+        port: Port to listen on.
+        config: Configuration file path.
 
-    \b
+    Examples:
+        \b
         xp rp start
         xp rp start --port 10002 --config my_cli.yml
+
+    Raises:
+        SystemExit: If proxy is already running.
     """
     global global_proxy_instance
 
@@ -74,6 +78,12 @@ def start_proxy(ctx: Context, port: int, config: str) -> None:
 
         # Handle graceful shutdown on SIGINT
         def signal_handler(signum: int, frame: Optional[FrameType]) -> None:
+            """Handle shutdown signals for graceful proxy termination.
+
+            Args:
+                signum: Signal number received.
+                frame: Current stack frame (may be None).
+            """
             if global_proxy_instance and global_proxy_instance.is_running:
                 timestamp = global_proxy_instance.timestamp()
                 print(f"\n{timestamp} [SHUTDOWN] Received interrupt signal ({signum})")
@@ -104,16 +114,15 @@ def start_proxy(ctx: Context, port: int, config: str) -> None:
 @reverse_proxy.command("stop")
 @handle_service_errors(ReverseProxyError)
 def stop_proxy() -> None:
-    """
-    Stop the running Conbus reverse proxy server.
+    r"""Stop the running Conbus reverse proxy server.
 
     Examples:
-
-    \b
+        \b
         xp rp stop
-    """
-    global global_proxy_instance
 
+    Raises:
+        SystemExit: If proxy is not running.
+    """
     try:
         if global_proxy_instance is None or not global_proxy_instance.is_running:
             error_response = {
@@ -135,18 +144,15 @@ def stop_proxy() -> None:
 @reverse_proxy.command("status")
 @handle_service_errors(Exception)
 def proxy_status() -> None:
-    """
-    Get status of the Conbus reverse proxy server.
+    r"""Get status of the Conbus reverse proxy server.
 
     Shows current running state, listen port, target server,
     and active connection details.
 
     Examples:
-
-    \b
+        \b
         xp rp status
     """
-    global global_proxy_instance
     OutputFormatter(True)
 
     try:

xp/cli/commands/server/server_commands.py

@@ -20,9 +20,7 @@ _server_instance: Optional[ServerService] = None
     cls=HelpColorsGroup, help_headers_color="yellow", help_options_color="green"
 )
 def server() -> None:
-    """
-    Conbus emulator server operations
-    """
+    """Perform Conbus emulator server operations."""
     pass
 
 
@@ -34,14 +32,20 @@ def server() -> None:
 @click.pass_context
 @handle_service_errors(ServerError)
 def start_server(ctx: Context, port: int, config: str) -> None:
-    """
-    Start the Conbus emulator server.
+    r"""Start the Conbus emulator server.
 
-    Examples:
+    Args:
+        ctx: Click context object.
+        port: Port to listen on.
+        config: Configuration file path.
 
-    \b
+    Examples:
+        \b
         xp server start
         xp server start --port 1001 --config my_config.yml
+
+    Raises:
+        SystemExit: If server is already running.
     """
     global _server_instance
 
@@ -76,16 +80,12 @@ def start_server(ctx: Context, port: int, config: str) -> None:
 @server.command("stop")
 @handle_service_errors(ServerError)
 def stop_server() -> None:
-    """
-    Stop the running Conbus emulator server.
+    r"""Stop the running Conbus emulator server.
 
     Examples:
-
-    \b
+        \b
         xp server stop
     """
-    global _server_instance
-
     try:
         if _server_instance is None or not _server_instance.is_running:
             ServerErrorHandler.handle_server_not_running_error()
@@ -104,15 +104,15 @@ def stop_server() -> None:
 @server.command("status")
 @handle_service_errors(Exception)
 def server_status() -> None:
-    """
-    Get status of the Conbus emulator server.
+    r"""Get status of the Conbus emulator server.
 
     Examples:
-
-    \b
+        \b
         xp server status
+
+    Raises:
+        SystemExit: If status cannot be retrieved.
     """
-    global _server_instance
     formatter = OutputFormatter(True)
 
     try:

xp/cli/commands/telegram/telegram.py

@@ -8,9 +8,7 @@ from click_help_colors import HelpColorsGroup
     cls=HelpColorsGroup, help_headers_color="yellow", help_options_color="green"
 )
 def telegram() -> None:
-    """
-    Event telegram operations
-    """
+    """Perform event telegram operations."""
     pass
 
 
@@ -18,9 +16,7 @@ def telegram() -> None:
     cls=HelpColorsGroup, help_headers_color="yellow", help_options_color="green"
 )
 def linknumber() -> None:
-    """
-    Link number operations for module configuration
-    """
+    """Perform link number operations for module configuration."""
     pass
 
 
@@ -28,9 +24,7 @@ def linknumber() -> None:
     cls=HelpColorsGroup, help_headers_color="yellow", help_options_color="green"
 )
 def blink() -> None:
-    """
-    Blink operations for module LED control
-    """
+    """Perform blink operations for module LED control."""
     pass
 
 
@@ -38,9 +32,7 @@ def blink() -> None:
     cls=HelpColorsGroup, help_headers_color="yellow", help_options_color="green"
 )
 def checksum() -> None:
-    """
-    Checksum calculation and validation operations
-    """
+    """Perform checksum calculation and validation operations."""
     pass
 
 

xp/cli/commands/telegram/telegram_blink_commands.py

@@ -16,12 +16,13 @@ from xp.services.telegram.telegram_blink_service import BlinkError, TelegramBlin
 @click.argument("serial_number", type=SERIAL)
 @handle_service_errors(BlinkError)
 def blink_on(serial_number: str) -> None:
-    """
-    Generate a telegram to start blinking module LED.
+    r"""Generate a telegram to start blinking module LED.
 
-    Examples:
+    Args:
+        serial_number: 10-digit module serial number.
 
-    \b
+    Examples:
+        \b
         xp blink on 0012345008
         xp blink on 0012345008
     """
@@ -49,12 +50,13 @@ def blink_on(serial_number: str) -> None:
 @click.argument("serial_number", type=SERIAL)
 @handle_service_errors(BlinkError)
 def blink_off(serial_number: str) -> None:
-    """
-    Generate a telegram to stop blinking module LED.
+    r"""Generate a telegram to stop blinking module LED.
 
-    Examples:
+    Args:
+        serial_number: 10-digit module serial number.
 
-    \b
+    Examples:
+        \b
         xp blink off 0012345011
     """
     service = TelegramBlinkService()

xp/cli/commands/telegram/telegram_checksum_commands.py

@@ -22,14 +22,19 @@ from xp.services.telegram.telegram_checksum_service import TelegramChecksumServi
 )
 @handle_service_errors(Exception)
 def calculate_checksum(data: str, algorithm: str) -> None:
-    """
-    Calculate checksum for given data string.
+    r"""Calculate checksum for given data string.
 
-    Examples:
+    Args:
+        data: Data string to calculate checksum for.
+        algorithm: Checksum algorithm to use.
 
-    \b
+    Examples:
+        \b
         xp checksum calculate "E14L00I02M"
         xp checksum calculate "E14L00I02M" --algorithm crc32
+
+    Raises:
+        SystemExit: If checksum calculation fails.
     """
     service = TelegramChecksumService()
     formatter = OutputFormatter(True)
@@ -65,14 +70,20 @@ def calculate_checksum(data: str, algorithm: str) -> None:
 )
 @handle_service_errors(Exception)
 def validate_checksum(data: str, expected_checksum: str, algorithm: str) -> None:
-    """
-    Validate data against expected checksum.
+    r"""Validate data against expected checksum.
 
-    Examples:
+    Args:
+        data: Data string to validate.
+        expected_checksum: Expected checksum value.
+        algorithm: Checksum algorithm to use.
 
-    \b
+    Examples:
+        \b
         xp checksum validate "E14L00I02M" "AK"
         xp checksum validate "E14L00I02M" "ABCDABCD" --algorithm crc32
+
+    Raises:
+        SystemExit: If checksum validation fails.
     """
     service = TelegramChecksumService()
     formatter = OutputFormatter(True)

xp/cli/commands/telegram/telegram_discover_commands.py

@@ -17,12 +17,10 @@ from xp.services.telegram.telegram_discover_service import (
 @telegram.command("discover")
 @handle_service_errors(DiscoverError)
 def generate_discover() -> None:
-    """
-    Generate a discover telegram for device enumeration.
+    r"""Generate a discover telegram for device enumeration.
 
     Examples:
-
-    \b
+        \b
         xp telegram discover
     """
     service = TelegramDiscoverService()

xp/cli/commands/telegram/telegram_linknumber_commands.py

@@ -20,12 +20,14 @@ from xp.services.telegram.telegram_link_number_service import (
 @click.argument("link_number", type=int)
 @handle_service_errors(LinkNumberError)
 def generate_set_link_number(serial_number: str, link_number: int) -> None:
-    """
-    Generate a telegram to set module link number.
+    r"""Generate a telegram to set module link number.
 
-    Examples:
+    Args:
+        serial_number: 10-digit module serial number.
+        link_number: Link number to set.
 
-    \b
+    Examples:
+        \b
         xp telegram linknumber write 0012345005 25
     """
     service = LinkNumberService()
@@ -55,12 +57,13 @@ def generate_set_link_number(serial_number: str, link_number: int) -> None:
 @click.argument("serial_number", type=SERIAL)
 @handle_service_errors(LinkNumberError)
 def generate_read_link_number(serial_number: str) -> None:
-    """
-    Generate a telegram to read module link number.
+    r"""Generate a telegram to read module link number.
 
-    Examples:
+    Args:
+        serial_number: 10-digit module serial number.
 
-    \b
+    Examples:
+        \b
         xp telegram linknumber read 0012345005
     """
     service = LinkNumberService()

xp/cli/commands/telegram/telegram_parse_commands.py

@@ -17,19 +17,19 @@ from xp.services.telegram.telegram_service import TelegramParsingError, Telegram
 @click.argument("telegram_string")
 @handle_service_errors(TelegramParsingError)
 def parse_any_telegram(telegram_string: str) -> None:
-    """
-    Auto-detect and parse any type of telegram (event, system, reply, or discover).
+    r"""Auto-detect and parse any type of telegram (event, system, reply, or discover).
 
-    Examples:
+    Args:
+        telegram_string: Telegram string to parse.
 
-    \b
+    Examples:
+        \b
         xp telegram parse "<E14L00I02MAK>"
         xp telegram parse "<S0020012521F02D18FN>"
         xp telegram parse "<R0020012521F02D18+26,0§CIL>"
         xp telegram parse "<S0000000000F01D00FA>"
         xp telegram parse "<R0012345011F01DFM>"
         xp telegram parse "<R0012345003F18DFF>"
-
     """
     service = TelegramService()
     TelegramFormatter(True)
@@ -47,12 +47,13 @@ def parse_any_telegram(telegram_string: str) -> None:
 @click.argument("telegram_string")
 @handle_service_errors(TelegramParsingError)
 def validate_telegram(telegram_string: str) -> None:
-    """
-    Validate the format of an event telegram.
+    r"""Validate the format of an event telegram.
 
-    Examples:
+    Args:
+        telegram_string: Telegram string to validate.
 
-    \b
+    Examples:
+        \b
         xp telegram validate "<E14L00I02MAK>"
     """
     service = TelegramService()

xp/cli/commands/telegram/telegram_version_commands.py

@@ -19,13 +19,17 @@ from xp.services.telegram.telegram_version_service import (
 @click.argument("serial_number", type=SERIAL)
 @handle_service_errors(VersionParsingError)
 def generate_version_request(serial_number: str) -> None:
-    """
-    Generate a telegram to request version information from a device.
+    r"""Generate a telegram to request version information from a device.
 
-    Examples:
+    Args:
+        serial_number: 10-digit module serial number.
 
-    \b
+    Examples:
+        \b
         xp telegram version 0012345011
+
+    Raises:
+        SystemExit: If request cannot be generated.
     """
     service = VersionService()
     formatter = OutputFormatter(True)

xp/cli/main.py

@@ -27,7 +27,11 @@ from xp.utils.dependencies import ServiceContainer
 @click.version_option()
 @click.pass_context
 def cli(ctx: click.Context) -> None:
-    """XP CLI tool for remote console bus operations"""
+    """XP CLI tool for remote console bus operations.
+
+    Args:
+        ctx: Click context object for passing state between commands.
+    """
     # Configure logging with thread information
     log_format = "%(asctime)s - [%(threadName)s-%(thread)d] - %(levelname)s - %(name)s - %(message)s"
     date_format = "%H:%M:%S"

xp/cli/utils/click_tree.py

@@ -1,13 +1,29 @@
-# save as click_tree.py
+"""Utilities for displaying Click command trees."""
+
 from typing import Any
 
 import click
 
 
 def add_tree_command(cli_group: click.Group, command_name: str = "help") -> Any:
-    """Add a tree command to any Click group"""
+    """Add a tree command to any Click group.
+
+    Args:
+        cli_group: The Click group to add the tree command to.
+        command_name: Name of the tree command (default: "help").
+
+    Returns:
+        The tree command function.
+    """
 
     def print_command_tree(group: click.Group, ctx: click.Context, suffix: str) -> None:
+        """Print command tree recursively.
+
+        Args:
+            group: The Click group to print.
+            ctx: The Click context.
+            suffix: Prefix string for tree display.
+        """
         for name in sorted(group.list_commands(ctx)):
             cmd = group.get_command(ctx, name)
 
@@ -23,7 +39,11 @@ def add_tree_command(cli_group: click.Group, command_name: str = "help") -> Any:
     @cli_group.command(command_name)
     @click.pass_context
     def tree_command(ctx: click.Context) -> None:
-        """Show complete command tree"""
+        """Show complete command tree.
+
+        Args:
+            ctx: The Click context.
+        """
         root = ctx.find_root().command
         root_ctx = ctx.find_root()
         root_name = root_ctx.info_name or "cli"

xp/cli/utils/datapoint_type_choice.py

@@ -1,3 +1,5 @@
+"""Click parameter type for DataPointType enum validation."""
+
 from typing import Any, Optional
 
 import click
@@ -7,14 +9,32 @@ from xp.models.telegram.datapoint_type import DataPointType
 
 # noinspection DuplicatedCode
 class DatapointTypeChoice(click.ParamType):
+    """Click parameter type for validating DataPointType enum values.
+
+    Attributes:
+        name: The parameter type name.
+        choices: List of valid choice strings.
+    """
+
     name = "telegram_type"
 
     def __init__(self) -> None:
+        """Initialize the DatapointTypeChoice parameter type."""
         self.choices = [key.lower() for key in DataPointType.__members__.keys()]
 
     def convert(
         self, value: Any, param: Optional[click.Parameter], ctx: Optional[click.Context]
     ) -> Any:
+        """Convert and validate input to DataPointType enum.
+
+        Args:
+            value: The input value to convert.
+            param: The Click parameter.
+            ctx: The Click context.
+
+        Returns:
+            DataPointType enum member if valid, None if input is None.
+        """
         if value is None:
             return value