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

xp/cli/utils/decorators.py

@@ -11,15 +11,39 @@ from xp.cli.utils.formatters import OutputFormatter
 def handle_service_errors(
     *service_exceptions: Type[Exception],
 ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
-    """Decorator to handle common service exceptions with consistent JSON error formatting.
+    """Handle common service exceptions with consistent JSON error formatting.
 
     Args:
-        service_exceptions: Tuple of exception types to catch and handle
+        service_exceptions: Tuple of exception types to catch and handle.
+
+    Returns:
+        Decorator function that wraps commands with error handling.
     """
 
     def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        """Apply error handling to the decorated function.
+
+        Args:
+            func: The function to decorate.
+
+        Returns:
+            Wrapped function with error handling.
+        """
+
         @functools.wraps(func)
         def wrapper(*args: Any, **kwargs: Any) -> Any:
+            """Execute function with error handling.
+
+            Args:
+                args: Positional arguments passed to the decorated function.
+                kwargs: Keyword arguments passed to the decorated function.
+
+            Returns:
+                Result from the decorated function.
+
+            Raises:
+                SystemExit: When a service exception or unexpected error occurs.
+            """
             formatter = OutputFormatter(True)
 
             try:
@@ -40,20 +64,38 @@ def handle_service_errors(
 
 
 def common_options(func: Callable[..., Any]) -> Callable[..., Any]:
-    """Decorator to add validation option."""
+    """Add validation option to command.
+
+    Args:
+        func: The function to decorate.
+
+    Returns:
+        Decorated function with common options.
+    """
     return func
 
 
 def telegram_parser_command(
     service_exceptions: Tuple[Type[Exception], ...] = (),
 ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
-    """Decorator for telegram parsing commands with standard error handling.
+    """Apply telegram parsing commands with standard error handling.
 
     Args:
-        service_exceptions: Additional service exceptions to handle
+        service_exceptions: Additional service exceptions to handle.
+
+    Returns:
+        Decorator function for telegram parsing commands.
     """
 
     def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        """Apply telegram parser decorators.
+
+        Args:
+            func: The function to decorate.
+
+        Returns:
+            Decorated function with telegram parsing support.
+        """
         # Apply common options
         func = common_options(func)
 
@@ -71,13 +113,24 @@ def telegram_parser_command(
 def service_command(
     *service_exceptions: Type[Exception],
 ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
-    """Decorator for service-based commands with error handling and JSON output.
+    """Apply service-based commands with error handling and JSON output.
 
     Args:
-        service_exceptions: Service exception types to handle
+        service_exceptions: Service exception types to handle.
+
+    Returns:
+        Decorator function for service commands.
     """
 
     def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        """Apply service command decorators.
+
+        Args:
+            func: The function to decorate.
+
+        Returns:
+            Decorated function with service error handling.
+        """
         func = handle_service_errors(*service_exceptions)(func)
         return func
 
@@ -87,9 +140,24 @@ def service_command(
 def list_command(
     *service_exceptions: Type[Exception],
 ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
-    """Decorator for list/search commands with common options."""
+    """Apply list/search commands with common options.
+
+    Args:
+        service_exceptions: Service exception types to handle.
+
+    Returns:
+        Decorator function for list commands.
+    """
 
     def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        """Apply list command decorators.
+
+        Args:
+            func: The function to decorate.
+
+        Returns:
+            Decorated function with list error handling.
+        """
         func = handle_service_errors(*service_exceptions)(func)
         return func
 
@@ -97,9 +165,21 @@ def list_command(
 
 
 def file_operation_command() -> Callable[[Callable[..., Any]], Callable[..., Any]]:
-    """Decorator for file operation commands with common filters."""
+    """Apply file operation commands with common filters.
+
+    Returns:
+        Decorator function for file operation commands.
+    """
 
     def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        """Apply file operation decorators.
+
+        Args:
+            func: The function to decorate.
+
+        Returns:
+            Decorated function with filter options.
+        """
         func = click.option(
             "--time-range", help="Filter by time range (HH:MM:SS,mmm-HH:MM:SS,mmm)"
         )(func)
@@ -121,15 +201,36 @@ def file_operation_command() -> Callable[[Callable[..., Any]], Callable[..., Any
 def with_formatter(
     formatter_class: Any = None,
 ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
-    """Decorator to inject a formatter instance into the command.
+    """Inject a formatter instance into the command.
 
     Args:
-        formatter_class: Custom formatter class to use
+        formatter_class: Custom formatter class to use.
+
+    Returns:
+        Decorator function that injects a formatter.
     """
 
     def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        """Apply formatter injection.
+
+        Args:
+            func: The function to decorate.
+
+        Returns:
+            Wrapped function with formatter injection.
+        """
+
         @functools.wraps(func)
         def wrapper(*args: Any, **kwargs: Any) -> Any:
+            """Execute function with injected formatter.
+
+            Args:
+                args: Positional arguments passed to the decorated function.
+                kwargs: Keyword arguments passed to the decorated function.
+
+            Returns:
+                Result from the decorated function.
+            """
             formatter_cls = formatter_class or OutputFormatter
             formatter = formatter_cls(True)
             kwargs["formatter"] = formatter
@@ -143,15 +244,39 @@ def with_formatter(
 def require_arguments(
     *required_args: str,
 ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
-    """Decorator to validate required arguments are present.
+    """Validate required arguments are present.
 
     Args:
-        required_args: Names of required arguments
+        required_args: Names of required arguments.
+
+    Returns:
+        Decorator function that validates required arguments.
     """
 
     def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        """Apply argument validation.
+
+        Args:
+            func: The function to decorate.
+
+        Returns:
+            Wrapped function with argument validation.
+        """
+
         @functools.wraps(func)
         def wrapper(*args: Any, **kwargs: Any) -> Any:
+            """Execute function with argument validation.
+
+            Args:
+                args: Positional arguments passed to the decorated function.
+                kwargs: Keyword arguments passed to the decorated function.
+
+            Returns:
+                Result from the decorated function.
+
+            Raises:
+                SystemExit: When required arguments are missing.
+            """
             formatter = OutputFormatter(True)
 
             # Check for missing required arguments
@@ -175,11 +300,37 @@ def require_arguments(
 
 
 def connection_command() -> Callable[[Callable[..., Any]], Callable[..., Any]]:
-    """Decorator for commands that connect to remote services."""
+    """Apply commands that connect to remote services.
+
+    Returns:
+        Decorator function for connection commands.
+    """
 
     def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        """Apply connection command decorators.
+
+        Args:
+            func: The function to decorate.
+
+        Returns:
+            Wrapped function with connection error handling.
+        """
+
         @functools.wraps(func)
         def wrapper(*args: Any, **kwargs: Any) -> Any:
+            """Execute function with connection error handling.
+
+            Args:
+                args: Positional arguments passed to the decorated function.
+                kwargs: Keyword arguments passed to the decorated function.
+
+            Returns:
+                Result from the decorated function.
+
+            Raises:
+                SystemExit: When a connection timeout occurs.
+                Exception: Re-raises other exceptions for handling by other decorators.
+            """
             formatter = OutputFormatter(True)
 
             try:

xp/cli/utils/error_handlers.py

@@ -19,9 +19,12 @@ class CLIErrorHandler:
         """Handle telegram parsing errors with JSON formatting.
 
         Args:
-            error: The parsing error that occurred
-            raw_input: The raw input that failed to parse
-            context: Additional context information
+            error: The parsing error that occurred.
+            raw_input: The raw input that failed to parse.
+            context: Additional context information.
+
+        Raises:
+            SystemExit: Always exits with code 1 after displaying error.
         """
         formatter = OutputFormatter(True)
         error_data = {"raw_input": raw_input}
@@ -40,8 +43,11 @@ class CLIErrorHandler:
         """Handle connection/network errors with JSON formatting.
 
         Args:
-            error: The connection error that occurred
-            config: Configuration information (IP, port, timeout)
+            error: The connection error that occurred.
+            config: Configuration information (IP, port, timeout).
+
+        Raises:
+            SystemExit: Always exits with code 1 after displaying error.
         """
         formatter = OutputFormatter(True)
 
@@ -73,9 +79,12 @@ class CLIErrorHandler:
         """Handle general service errors with JSON formatting.
 
         Args:
-            error: The service error that occurred
-            operation: Description of the operation that failed
-            context: Additional context information
+            error: The service error that occurred.
+            operation: Description of the operation that failed.
+            context: Additional context information.
+
+        Raises:
+            SystemExit: Always exits with code 1 after displaying error.
         """
         formatter = OutputFormatter(True)
         error_data = {"operation": operation}
@@ -92,8 +101,11 @@ class CLIErrorHandler:
         """Handle validation errors with JSON formatting.
 
         Args:
-            error: The validation error that occurred
-            input_data: The input that failed validation
+            error: The validation error that occurred.
+            input_data: The input that failed validation.
+
+        Raises:
+            SystemExit: Always exits with code 1 after displaying error.
         """
         formatter = OutputFormatter(True)
         error_data = {"valid_format": False, "raw_input": input_data}
@@ -111,9 +123,12 @@ class CLIErrorHandler:
         """Handle file operation errors with JSON formatting.
 
         Args:
-            error: The file error that occurred
-            file_path: Path to the file that caused the error
-            operation: Type of file operation (parsing, reading, etc.)
+            error: The file error that occurred.
+            file_path: Path to the file that caused the error.
+            operation: Type of file operation (parsing, reading, etc.).
+
+        Raises:
+            SystemExit: Always exits with code 1 after displaying error.
         """
         formatter = OutputFormatter(True)
         error_data = {"file_path": file_path, "operation": operation}
@@ -129,9 +144,12 @@ class CLIErrorHandler:
         """Handle 'not found' errors with JSON formatting.
 
         Args:
-            error: The not found error that occurred
-            item_type: Type of item that was not found
-            identifier: Identifier used to search for the item
+            error: The not found error that occurred.
+            item_type: Type of item that was not found.
+            identifier: Identifier used to search for the item.
+
+        Raises:
+            SystemExit: Always exits with code 1 after displaying error.
         """
         formatter = OutputFormatter(True)
         error_data = {"item_type": item_type, "identifier": identifier}
@@ -148,7 +166,16 @@ class ServerErrorHandler(CLIErrorHandler):
     def handle_server_startup_error(
         error: Exception, port: int, config_path: str
     ) -> None:
-        """Handle server startup errors with JSON formatting."""
+        """Handle server startup errors with JSON formatting.
+
+        Args:
+            error: The server startup error that occurred.
+            port: Port number the server attempted to use.
+            config_path: Path to the configuration file.
+
+        Raises:
+            SystemExit: Always exits with code 1 after displaying error.
+        """
         formatter = OutputFormatter(True)
         error_data = {
             "port": port,
@@ -162,7 +189,11 @@ class ServerErrorHandler(CLIErrorHandler):
 
     @staticmethod
     def handle_server_not_running_error() -> None:
-        """Handle errors when server is not running with JSON formatting."""
+        """Handle errors when server is not running with JSON formatting.
+
+        Raises:
+            SystemExit: Always exits with code 1 after displaying error.
+        """
         error_response = OutputFormatter(True).error_response(
             "No server is currently running"
         )

xp/cli/utils/formatters.py

@@ -8,10 +8,22 @@ class OutputFormatter:
     """Handles standardized output formatting for CLI commands."""
 
     def __init__(self, json_output: bool = False):
+        """Initialize the output formatter.
+
+        Args:
+            json_output: Whether to format output as JSON (default: False).
+        """
         self.json_output = json_output
 
     def success_response(self, data: Dict[str, Any]) -> str:
-        """Format a successful response."""
+        """Format a successful response.
+
+        Args:
+            data: Response data to format.
+
+        Returns:
+            Formatted success response as string.
+        """
         if self.json_output:
             return json.dumps(data, indent=2)
         return self._format_text_response(data)
@@ -19,7 +31,15 @@ class OutputFormatter:
     def error_response(
         self, error: str, extra_data: Optional[Dict[str, Any]] = None
     ) -> str:
-        """Format an error response."""
+        """Format an error response.
+
+        Args:
+            error: Error message.
+            extra_data: Additional error data to include.
+
+        Returns:
+            Formatted error response as string.
+        """
         error_data = {"success": False, "error": error}
         if extra_data:
             error_data.update(extra_data)
@@ -29,7 +49,15 @@ class OutputFormatter:
         return f"Error: {error}"
 
     def validation_response(self, is_valid: bool, data: Dict[str, Any]) -> str:
-        """Format a validation response."""
+        """Format a validation response.
+
+        Args:
+            is_valid: Whether validation passed.
+            data: Validation data to include.
+
+        Returns:
+            Formatted validation response as string.
+        """
         if self.json_output:
             response_data = {"valid": is_valid} | data
             return json.dumps(response_data, indent=2)
@@ -38,7 +66,14 @@ class OutputFormatter:
         return f"Status: {status}"
 
     def checksum_status(self, is_valid: bool) -> str:
-        """Format checksum validation status."""
+        """Format checksum validation status.
+
+        Args:
+            is_valid: Whether checksum is valid.
+
+        Returns:
+            Formatted checksum status as string.
+        """
         if self.json_output:
             return json.dumps({"checksum_valid": is_valid}, indent=2)
 
@@ -46,7 +81,14 @@ class OutputFormatter:
 
     @staticmethod
     def _format_text_response(data: Dict[str, Any]) -> str:
-        """Format data for human-readable text output."""
+        """Format data for human-readable text output.
+
+        Args:
+            data: Data dictionary to format.
+
+        Returns:
+            Formatted text output as string.
+        """
         lines = []
 
         # Handle common data patterns
@@ -77,7 +119,15 @@ class TelegramFormatter(OutputFormatter):
     def format_telegram_summary(
         self, telegram_data: Dict[str, Any], service_formatter_method: Any = None
     ) -> str:
-        """Format telegram summary using service method when available."""
+        """Format telegram summary using service method when available.
+
+        Args:
+            telegram_data: Telegram data to format.
+            service_formatter_method: Optional service formatter method.
+
+        Returns:
+            Formatted telegram summary as string.
+        """
         if self.json_output:
             return json.dumps(telegram_data, indent=2)
 
@@ -98,7 +148,16 @@ class TelegramFormatter(OutputFormatter):
     def format_validation_result(
         self, parsed_telegram: Any, checksum_valid: Optional[bool], service_summary: str
     ) -> str:
-        """Format telegram validation results."""
+        """Format telegram validation results.
+
+        Args:
+            parsed_telegram: Parsed telegram object.
+            checksum_valid: Whether checksum is valid.
+            service_summary: Summary from service.
+
+        Returns:
+            Formatted validation result as string.
+        """
         if self.json_output:
             output = parsed_telegram.to_dict()
             output["checksum_valid"] = checksum_valid
@@ -118,7 +177,16 @@ class ListFormatter(OutputFormatter):
     def format_list_response(
         self, items: list, title: str, item_formatter: Any = None
     ) -> str:
-        """Format a list of items with optional custom formatter."""
+        """Format a list of items with optional custom formatter.
+
+        Args:
+            items: List of items to format.
+            title: Title for the list.
+            item_formatter: Optional custom formatter function.
+
+        Returns:
+            Formatted list as string.
+        """
         if self.json_output:
             return json.dumps(
                 {
@@ -144,7 +212,15 @@ class ListFormatter(OutputFormatter):
         return "\n".join(lines)
 
     def format_search_results(self, matches: list, query: str) -> str:
-        """Format search results."""
+        """Format search results.
+
+        Args:
+            matches: List of matching items.
+            query: Search query string.
+
+        Returns:
+            Formatted search results as string.
+        """
         if self.json_output:
             return json.dumps(
                 {
@@ -181,7 +257,16 @@ class StatisticsFormatter(OutputFormatter):
     def format_file_statistics(
         self, file_path: str, stats: Dict[str, Any], entry_count: int
     ) -> str:
-        """Format file analysis statistics."""
+        """Format file analysis statistics.
+
+        Args:
+            file_path: Path to the analyzed file.
+            stats: Statistics dictionary.
+            entry_count: Total number of entries.
+
+        Returns:
+            Formatted statistics as string.
+        """
         if self.json_output:
             return json.dumps(
                 {

xp/cli/utils/serial_number_type.py

@@ -1,14 +1,32 @@
+"""Click parameter type for serial number validation."""
+
 from typing import Any, Optional
 
 import click
 
 
 class SerialNumberParamType(click.ParamType):
+    """Click parameter type for validating and formatting serial numbers.
+
+    Attributes:
+        name: The parameter type name.
+    """
+
     name = "serial_number"
 
     def convert(
         self, value: Any, param: Optional[click.Parameter], ctx: Optional[click.Context]
     ) -> Optional[str]:
+        """Convert and validate serial number input.
+
+        Args:
+            value: The input value to convert.
+            param: The Click parameter.
+            ctx: The Click context.
+
+        Returns:
+            10-character zero-padded serial number string, or None if input is None.
+        """
         if value is None:
             return None
 

xp/cli/utils/system_function_choice.py

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

xp/cli/utils/xp_module_type.py

@@ -1,17 +1,37 @@
+"""Click parameter type for XP module type validation."""
+
 from typing import Any, Optional
 
 import click
 
 
 class XpModuleTypeChoice(click.ParamType):
+    """Click parameter type for validating XP module types.
+
+    Attributes:
+        name: The parameter type name.
+        choices: List of valid module type strings.
+    """
+
     name = "xpmoduletype"
 
     def __init__(self) -> None:
+        """Initialize the XpModuleTypeChoice parameter type."""
         self.choices = ["xp20", "xp24", "xp31", "xp33"]
 
     def convert(
         self, value: Any, param: Optional[click.Parameter], ctx: Optional[click.Context]
     ) -> Any:
+        """Convert and validate XP module type input.
+
+        Args:
+            value: The input value to convert.
+            param: The Click parameter.
+            ctx: The Click context.
+
+        Returns:
+            Lowercase module type string if valid, None if input is None.
+        """
         if value is None:
             return value
 

xp/connection/__init__.py

@@ -1,4 +1,4 @@
-"""Connection layer for XP CLI tool"""
+"""Connection layer for XP CLI tool."""
 
 from xp.connection.exceptions import (
     ProtocolError,