conson-xp 1.18.0__py3-none-any.whl

xp/cli/utils/formatters.py

@@ -0,0 +1,312 @@
+"""Output formatting utilities for CLI commands."""
+
+import json
+from typing import Any, Dict, Optional
+
+
+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.
+
+        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)
+
+    def error_response(
+        self, error: str, extra_data: Optional[Dict[str, Any]] = None
+    ) -> str:
+        """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)
+
+        if self.json_output:
+            return json.dumps(error_data, indent=2)
+        return f"Error: {error}"
+
+    def validation_response(self, is_valid: bool, data: Dict[str, Any]) -> str:
+        """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)
+
+        status = "✓ Valid" if is_valid else "✗ Invalid"
+        return f"Status: {status}"
+
+    def checksum_status(self, is_valid: bool) -> str:
+        """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)
+
+        return "✓ Valid" if is_valid else "✗ Invalid"
+
+    @staticmethod
+    def _format_text_response(data: Dict[str, Any]) -> str:
+        """Format data for human-readable text output.
+
+        Args:
+            data: Data dictionary to format.
+
+        Returns:
+            Formatted text output as string.
+        """
+        lines = []
+
+        # Handle common data patterns
+        if "telegram" in data:
+            lines.append(f"Telegram: {data['telegram']}")
+
+        if "serial_number" in data:
+            lines.append(f"Serial: {data['serial_number']}")
+
+        if "operation" in data:
+            lines.append(f"Operation: {data['operation']}")
+
+        if "count" in data:
+            lines.append(f"Count: {data['count']}")
+
+        # Add any remaining fields
+        for key, value in data.items():
+            if key not in ("telegram", "serial_number", "operation", "count"):
+                if isinstance(value, (str, int, float)):
+                    lines.append(f"{key.replace('_', ' ').title()}: {value}")
+
+        return "\n".join(lines)
+
+
+class TelegramFormatter(OutputFormatter):
+    """Specialized formatter for telegram-related output."""
+
+    def format_telegram_summary(
+        self, telegram_data: Dict[str, Any], service_formatter_method: Any = None
+    ) -> str:
+        """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)
+
+        if service_formatter_method:
+            return str(service_formatter_method)
+
+        # Fallback formatting
+        lines = []
+        if "telegram_type" in telegram_data:
+            lines.append(f"Type: {telegram_data['telegram_type'].title()}")
+        if "raw_telegram" in telegram_data:
+            lines.append(f"Raw: {telegram_data['raw_telegram']}")
+        if "timestamp" in telegram_data:
+            lines.append(f"Timestamp: {telegram_data['timestamp']}")
+
+        return "\n".join(lines)
+
+    def format_validation_result(
+        self, parsed_telegram: Any, checksum_valid: Optional[bool], service_summary: str
+    ) -> str:
+        """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
+            return json.dumps(output, indent=2)
+
+        lines = [service_summary]
+        if checksum_valid is not None:
+            status = "✓ Valid" if checksum_valid else "✗ Invalid"
+            lines.append(f"Checksum validation: {status}")
+
+        return "\n".join(lines)
+
+
+class ListFormatter(OutputFormatter):
+    """Specialized formatter for list-based output."""
+
+    def format_list_response(
+        self, items: list, title: str, item_formatter: Any = None
+    ) -> str:
+        """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(
+                {
+                    "items": [
+                        item.to_dict() if hasattr(item, "to_dict") else item
+                        for item in items
+                    ],
+                    "count": len(items),
+                },
+                indent=2,
+            )
+
+        lines = [f"{title}: {len(items)} items", "-" * 50]
+
+        for i, item in enumerate(items, 1):
+            if item_formatter:
+                lines.append(f"{i}. {item_formatter(item)}")
+            elif hasattr(item, "__str__"):
+                lines.append(f"{i}. {item}")
+            else:
+                lines.append(f"{i}. {item}")
+
+        return "\n".join(lines)
+
+    def format_search_results(self, matches: list, query: str) -> str:
+        """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(
+                {
+                    "query": query,
+                    "matches": [
+                        item.to_dict() if hasattr(item, "to_dict") else item
+                        for item in matches
+                    ],
+                    "count": len(matches),
+                },
+                indent=2,
+            )
+
+        if not matches:
+            return f"No items found matching '{query}'"
+
+        lines = [f"Found {len(matches)} items matching '{query}':", "-" * 60]
+        for item in matches:
+            if (
+                hasattr(item, "code")
+                and hasattr(item, "name")
+                and hasattr(item, "description")
+            ):
+                lines.append(f"{item.code:2} - {item.name}: {item.description}")
+            else:
+                lines.append(str(item))
+
+        return "\n".join(lines)
+
+
+class StatisticsFormatter(OutputFormatter):
+    """Specialized formatter for statistics and analysis output."""
+
+    def format_file_statistics(
+        self, file_path: str, stats: Dict[str, Any], entry_count: int
+    ) -> str:
+        """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(
+                {
+                    "file_path": file_path,
+                    "statistics": stats,
+                    "entry_count": entry_count,
+                },
+                indent=2,
+            )
+
+        lines = [
+            "=== Console Bus Log Summary ===",
+            f"File: {file_path}",
+            f"Entries: {entry_count}",
+        ]
+
+        # Time range
+        if stats.get("time_range", {}).get("start"):
+            time_range = stats["time_range"]
+            lines.extend(
+                [
+                    f"Time Range: {time_range['start']} - {time_range['end']}",
+                    f"Duration: {time_range['duration_seconds']:.3f} seconds",
+                ]
+            )
+
+        # Telegram distribution
+        lines.append("\nTelegram Distribution:")
+        type_counts = stats.get("telegram_type_counts", {})
+        total = stats.get("total_entries", 0)
+
+        for t_type, count in type_counts.items():
+            percentage = (count / total * 100) if total > 0 else 0
+            lines.append(f"  {t_type.capitalize()}: {count} ({percentage:.1f}%)")
+
+        # Direction distribution
+        lines.append("\nDirection Distribution:")
+        dir_counts = stats.get("direction_counts", {})
+        for direction, count in dir_counts.items():
+            percentage = (count / total * 100) if total > 0 else 0
+            lines.append(f"  {direction.upper()}: {count} ({percentage:.1f}%)")
+
+        return "\n".join(lines)

xp/cli/utils/module_type_choice.py

@@ -0,0 +1,56 @@
+"""Click parameter type for ModuleTypeCode enum validation."""
+
+from typing import Any, Optional
+
+import click
+
+from xp.models.telegram.module_type_code import ModuleTypeCode
+
+
+class ModuleTypeChoice(click.ParamType):
+    """Click parameter type for validating ModuleTypeCode enum values.
+
+    Attributes:
+        name: The parameter type name.
+        choices: List of valid choice strings.
+    """
+
+    name = "module_type"
+
+    def __init__(self) -> None:
+        """Initialize the ModuleTypeChoice parameter type."""
+        self.choices = [key for key in ModuleTypeCode.__members__.keys()]
+
+    def convert(
+        self, value: Any, param: Optional[click.Parameter], ctx: Optional[click.Context]
+    ) -> int:
+        """Convert and validate input to ModuleTypeCode value.
+
+        Args:
+            value: The input value to convert.
+            param: The Click parameter.
+            ctx: The Click context.
+
+        Returns:
+            Module type code integer value if valid.
+        """
+        if value is None:
+            self.fail("Module type is required", param, ctx)
+
+        # Convert to upper for comparison
+        normalized_value = value.upper()
+
+        if normalized_value in self.choices:
+            # Return the actual enum value (integer)
+            return ModuleTypeCode[normalized_value].value
+
+        # If not found, show error with available choices
+        choices_list = "\n".join(f" - {choice}" for choice in sorted(self.choices))
+        self.fail(
+            f"{value!r} is not a valid module type. " f"Choose from:\n{choices_list}",
+            param,
+            ctx,
+        )
+
+
+MODULE_TYPE = ModuleTypeChoice()

xp/cli/utils/serial_number_type.py

@@ -0,0 +1,52 @@
+"""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
+
+        # Convert to string if not already
+        str_value = str(value)
+
+        # Check if contains only numeric characters (empty string should be treated as "0")
+        if not str_value.isdigit() and str_value != "":
+            self.fail(f"{value!r} contains non-numeric characters", param, ctx)
+
+        # Handle empty string as zero
+        if str_value == "":
+            str_value = "0"
+
+        # Check length constraints
+        if len(str_value) > 10:
+            self.fail(f"{value!r} is longer than 10 characters", param, ctx)
+
+        # Pad left with zeros if length < 10
+        return str_value.zfill(10)
+
+
+SERIAL = SerialNumberParamType()

xp/cli/utils/system_function_choice.py

@@ -0,0 +1,57 @@
+"""Click parameter type for SystemFunction enum validation."""
+
+from typing import Any, Optional
+
+import click
+
+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
+
+        # Convert to lower for comparison
+        normalized_value = value.lower()
+
+        if normalized_value in self.choices:
+            # Return the actual enum member
+            return SystemFunction[normalized_value.upper()]
+
+        # If not found, show error with available choices
+        self.fail(
+            f"{value!r} is not a valid choice. "
+            f'Choose from: {", ".join(self.choices)}',
+            param,
+            ctx,
+        )
+
+
+SYSTEM_FUNCTION = SystemFunctionChoice()

xp/cli/utils/xp_module_type.py

@@ -0,0 +1,53 @@
+"""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
+
+        # Convert to lower for comparison
+        normalized_value = value.lower()
+
+        if normalized_value in self.choices:
+            return normalized_value
+
+        # If not found, show error with available choices
+        choices_list = "\n".join(f" - {choice}" for choice in sorted(self.choices))
+        self.fail(
+            f"{value!r} is not a valid choice. " f"Choose from:\n{choices_list}",
+            param,
+            ctx,
+        )
+
+
+XP_MODULE_TYPE = XpModuleTypeChoice()

xp/connection/__init__.py

@@ -0,0 +1,13 @@
+"""Connection layer for XP CLI tool."""
+
+from xp.connection.exceptions import (
+    ProtocolError,
+    ValidationError,
+    XPError,
+)
+
+__all__ = [
+    "XPError",
+    "ProtocolError",
+    "ValidationError",
+]

xp/connection/exceptions.py

@@ -0,0 +1,22 @@
+"""Connection-related exceptions for XP CLI tool.
+
+Following the architecture requirement for structured error handling.
+"""
+
+
+class XPError(Exception):
+    """Base exception for XP CLI tool."""
+
+    pass
+
+
+class ProtocolError(XPError):
+    """Console bus protocol errors."""
+
+    pass
+
+
+class ValidationError(XPError):
+    """Input validation errors."""
+
+    pass

xp/models/__init__.py

@@ -0,0 +1,36 @@
+"""Data models for XP CLI tool."""
+
+from xp.models.conbus.conbus import ConbusRequest, ConbusResponse
+from xp.models.conbus.conbus_client_config import ConbusClientConfig
+from xp.models.conbus.conbus_connection_status import ConbusConnectionStatus
+from xp.models.conbus.conbus_datapoint import ConbusDatapointResponse
+from xp.models.conbus.conbus_discover import ConbusDiscoverResponse
+from xp.models.conbus.conbus_event_raw import ConbusEventRawResponse
+from xp.models.log_entry import LogEntry
+from xp.models.telegram.event_telegram import EventTelegram
+from xp.models.telegram.event_type import EventType
+from xp.models.telegram.input_type import InputType
+from xp.models.telegram.module_type import (
+    ModuleType,
+    get_all_module_types,
+    is_valid_module_code,
+)
+from xp.models.telegram.module_type_code import ModuleTypeCode
+
+__all__ = [
+    "EventTelegram",
+    "EventType",
+    "InputType",
+    "ModuleType",
+    "ModuleTypeCode",
+    "get_all_module_types",
+    "is_valid_module_code",
+    "LogEntry",
+    "ConbusClientConfig",
+    "ConbusRequest",
+    "ConbusResponse",
+    "ConbusDatapointResponse",
+    "ConbusDiscoverResponse",
+    "ConbusEventRawResponse",
+    "ConbusConnectionStatus",
+]

xp/models/actiontable/__init__.py

@@ -0,0 +1 @@
+"""Action table models for XP protocol."""

xp/models/actiontable/actiontable.py

@@ -0,0 +1,43 @@
+"""XP20 Action Table models for input actions and settings."""
+
+from dataclasses import dataclass, field
+
+from xp.models import ModuleTypeCode
+from xp.models.telegram.input_action_type import InputActionType
+from xp.models.telegram.timeparam_type import TimeParam
+
+
+# CP20 0 0 > 1 OFF;
+# CP20 0 0 > 1 ~ON;
+@dataclass
+class ActionTableEntry:
+    """Entry in an action table mapping input events to output actions.
+
+    Attributes:
+        module_type: Type code of the module.
+        link_number: Link number for the action.
+        module_input: Input number on the module.
+        module_output: Output number on the module.
+        command: Action type to perform.
+        parameter: Time parameter for the action.
+        inverted: Whether the action is inverted.
+    """
+
+    module_type: ModuleTypeCode = ModuleTypeCode.CP20
+    link_number: int = 0
+    module_input: int = 0
+    module_output: int = 1
+    command: InputActionType = InputActionType.OFF
+    parameter: TimeParam = TimeParam.NONE
+    inverted: bool = False
+
+
+@dataclass
+class ActionTable:
+    """Action Table for managing action on events.
+
+    Attributes:
+        entries: List of action table entries.
+    """
+
+    entries: list[ActionTableEntry] = field(default_factory=list)