exonware-xwsystem 0.1.0.1__py3-none-any.whl → 0.1.0.4__py3-none-any.whl

exonware/xwsystem/{cli → console/cli}/contracts.py

@@ -1,193 +1,175 @@
+#exonware/xwsystem/src/exonware/xwsystem/console/cli/contracts.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: September 04, 2025
 
 CLI module contracts - interfaces and enums for command-line interface functionality.
 """
 
-from abc import ABC, abstractmethod
-from typing import Any, Optional, Union
+from typing import Protocol, runtime_checkable
+from typing import Any, Optional
 
-# Import enums from types module
+# Import general console enums from console level (priority)
+from ..defs import Alignment, BorderStyle, Colors, Style
+# Import CLI-specific enums from defs
 from .defs import (
     ColorType,
     ProgressStyle,
     TableStyle,
     PromptType,
-    Alignment,
-    BorderStyle,
-    Colors,
-    Style,
     ArgumentType
 )
 
 
-class IConsole(ABC):
+@runtime_checkable
+class IConsole(Protocol):
     """Interface for console operations."""
     
-    @abstractmethod
     def print(self, text: str, color: Optional[ColorType] = None, **kwargs) -> None:
         """Print text to console."""
-        pass
+        ...
     
-    @abstractmethod
     def input(self, prompt: str, **kwargs) -> str:
         """Get input from user."""
-        pass
+        ...
     
-    @abstractmethod
     def clear(self) -> None:
         """Clear console screen."""
-        pass
+        ...
 
 
-class IProgressBar(ABC):
+@runtime_checkable
+class IProgressBar(Protocol):
     """Interface for progress bar operations."""
     
-    @abstractmethod
     def start(self, total: int, description: str = "") -> None:
         """Start progress bar."""
-        pass
+        ...
     
-    @abstractmethod
     def update(self, increment: int = 1) -> None:
         """Update progress."""
-        pass
+        ...
     
-    @abstractmethod
     def finish(self) -> None:
         """Finish progress bar."""
-        pass
+        ...
 
 
-class ITable(ABC):
+@runtime_checkable
+class ITable(Protocol):
     """Interface for table operations."""
     
-    @abstractmethod
     def add_row(self, *values: Any) -> None:
         """Add row to table."""
-        pass
+        ...
     
-    @abstractmethod
     def render(self) -> str:
         """Render table as string."""
-        pass
+        ...
 
 
-class IPrompt(ABC):
+@runtime_checkable
+class IPrompt(Protocol):
     """Interface for user prompts."""
     
-    @abstractmethod
     def ask(self, question: str, **kwargs) -> Any:
         """Ask user a question."""
-        pass
+        ...
 
 
-class IArgumentParser(ABC):
+@runtime_checkable
+class IArgumentParser(Protocol):
     """Interface for argument parsing."""
     
-    @abstractmethod
     def add_argument(self, *args, **kwargs) -> None:
         """Add argument to parser."""
-        pass
+        ...
     
-    @abstractmethod
     def parse_args(self, args: Optional[list[str]] = None) -> Any:
         """Parse command line arguments."""
-        pass
+        ...
 
 
-class ICLI(ABC):
+@runtime_checkable
+class ICLI(Protocol):
     """Interface for CLI operations."""
     
     @property
-    @abstractmethod
     def name(self) -> str:
         """Get CLI name."""
-        pass
+        ...
     
     @property
-    @abstractmethod
     def version(self) -> str:
         """Get CLI version."""
-        pass
+        ...
     
-    @abstractmethod
     def add_command(self, name: str, command: Any) -> None:
         """Add a command to the CLI."""
-        pass
+        ...
     
-    @abstractmethod
     def add_option(self, name: str, option: Any) -> None:
         """Add an option to the CLI."""
-        pass
+        ...
     
-    @abstractmethod
     def run(self, args: Optional[list[str]] = None) -> int:
         """Run the CLI."""
-        pass
+        ...
     
-    @abstractmethod
     def get_help(self) -> str:
         """Get help text."""
-        pass
+        ...
 
 
-class IProgress(ABC):
+@runtime_checkable
+class IProgress(Protocol):
     """Interface for progress operations."""
     
-    @abstractmethod
     def start(self, total: int, description: str = "") -> None:
         """Start progress tracking."""
-        pass
+        ...
     
-    @abstractmethod
     def update(self, increment: int = 1) -> None:
         """Update progress."""
-        pass
+        ...
     
-    @abstractmethod
     def finish(self) -> None:
         """Finish progress tracking."""
-        pass
+        ...
 
 
-class IPrompts(ABC):
+@runtime_checkable
+class IPrompts(Protocol):
     """Interface for user prompts."""
     
-    @abstractmethod
     def ask(self, question: str, **kwargs) -> Any:
         """Ask user a question."""
-        pass
+        ...
     
-    @abstractmethod
     def confirm(self, message: str, default: bool = False) -> bool:
         """Ask for confirmation."""
-        pass
+        ...
     
-    @abstractmethod
     def select(self, message: str, choices: list[str], default: Optional[str] = None) -> str:
         """Ask user to select from choices."""
-        pass
+        ...
 
 
-class ITableFormatter(ABC):
+@runtime_checkable
+class ITableFormatter(Protocol):
     """Interface for table formatting."""
     
-    @abstractmethod
     def add_row(self, *values: Any) -> None:
         """Add row to table."""
-        pass
+        ...
     
-    @abstractmethod
     def render(self) -> str:
         """Render table as string."""
-        pass
+        ...
     
-    @abstractmethod
     def clear(self) -> None:
         """Clear all rows."""
-        pass
+        ...

exonware/xwsystem/console/cli/defs.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/console/cli/defs.py
+#exonware/xwsystem/console/cli/cli_defs.py
+"""
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.4
+Generation Date: 07-Sep-2025
+
+CLI-specific types and enums for XWSystem.
+"""
+
+from enum import Enum
+# Import general console enums from console level (priority)
+from ..defs import Alignment, BorderStyle, Colors, Style
+
+
+# ============================================================================
+# CLI-SPECIFIC ENUMS
+# ============================================================================
+
+class ColorType(Enum):
+    """Color types for CLI output."""
+    RESET = "reset"
+    BOLD = "bold"
+    DIM = "dim"
+    UNDERLINE = "underline"
+    RED = "red"
+    GREEN = "green"
+    YELLOW = "yellow"
+    BLUE = "blue"
+    MAGENTA = "magenta"
+    CYAN = "cyan"
+    WHITE = "white"
+    GRAY = "gray"
+
+
+class ProgressStyle(Enum):
+    """Progress bar styles."""
+    BAR = "bar"
+    SPINNER = "spinner"
+    PERCENTAGE = "percentage"
+    COUNTER = "counter"
+
+
+class TableStyle(Enum):
+    """Table display styles."""
+    SIMPLE = "simple"
+    GRID = "grid"
+    FANCY = "fancy"
+    MINIMAL = "minimal"
+
+
+class PromptType(Enum):
+    """Prompt input types."""
+    TEXT = "text"
+    PASSWORD = "password"
+    CONFIRM = "confirm"
+    SELECT = "select"
+    MULTISELECT = "multiselect"
+
+
+class ArgumentType(Enum):
+    """Types of command-line arguments."""
+    STRING = "string"
+    INTEGER = "int"
+    FLOAT = "float"
+    BOOLEAN = "bool"
+    FILE = "file"
+    DIRECTORY = "dir"
+    CHOICE = "choice"
+
+
+__all__ = [
+    # Re-export general console enums
+    'Alignment',
+    'BorderStyle',
+    'Colors',
+    'Style',
+    # CLI-specific enums
+    'ColorType',
+    'ProgressStyle',
+    'TableStyle',
+    'PromptType',
+    'ArgumentType',
+]

exonware/xwsystem/console/cli/encoding.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/console/cli/encoding.py
+"""
+Console encoding utilities.
+
+Best-effort UTF-8 configuration for Windows consoles (safe for uvicorn logging).
+No-op on non-Windows platforms.
+"""
+
+from __future__ import annotations
+
+import io
+import sys
+
+
+def ensure_utf8_console() -> None:
+    """
+    Configure UTF-8 encoding for Windows console output streams.
+
+    - No-op on non-Windows platforms.
+    - Best-effort: never raises.
+    """
+    if sys.platform != "win32":
+        return
+
+    try:
+        # Prefer reconfigure when available (Python 3.7+)
+        if hasattr(sys.stdout, "reconfigure"):
+            try:
+                sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+                sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+                return
+            except (AttributeError, OSError):
+                # Fall back to wrapper below
+                pass
+
+        class _UTF8Wrapper(io.TextIOWrapper):
+            """Wrapper that delegates key methods to the original stream."""
+
+            def __init__(self, buffer, **kwargs):
+                super().__init__(buffer, **kwargs)
+                self._original = buffer
+
+            def isatty(self):
+                return getattr(self._original, "isatty", lambda: False)()
+
+            def fileno(self):
+                return getattr(self._original, "fileno", lambda: -1)()
+
+        sys.stdout = _UTF8Wrapper(
+            sys.stdout.buffer,
+            encoding="utf-8",
+            errors="replace",
+            line_buffering=True,
+        )
+        sys.stderr = _UTF8Wrapper(
+            sys.stderr.buffer,
+            encoding="utf-8",
+            errors="replace",
+            line_buffering=True,
+        )
+    except Exception:
+        # Fallback on error
+        pass
+
+
+__all__ = [
+    "ensure_utf8_console",
+]

exonware/xwsystem/{cli → console/cli}/errors.py

@@ -1,13 +1,17 @@
+#exonware/xwsystem/src/exonware/xwsystem/console/cli/errors.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: September 04, 2025
 
 CLI module errors - exception classes for command-line interface functionality.
 """
 
+# Import base console errors from console level (priority)
+from ..errors import ConsoleError as BaseConsoleError
+
 
 class CLIError(Exception):
     """Base exception for CLI errors."""
@@ -24,8 +28,9 @@ class CommandError(CLIError):
     pass
 
 
-class ConsoleError(CLIError):
-    """Raised when console operation fails."""
+# ConsoleError extends base ConsoleError from console level
+class ConsoleError(BaseConsoleError):
+    """Raised when console operation fails (CLI-specific)."""
     pass
 
 

exonware/xwsystem/console/cli/event_logger.py

@@ -0,0 +1,166 @@
+#exonware/xwsystem/src/exonware/xwsystem/console/cli/event_logger.py
+"""
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.4
+Generation Date: January 2025
+
+CLI Event Logger - Extends Python's logging.Logger with event logging capabilities.
+"""
+
+import logging
+from typing import Optional, Any
+from ..event_logger import ConsoleEventLogger
+from ..contracts import IEventLogger
+from ..defs import LogLevel, ConsoleEventType, ConsoleEvent
+
+
+class CliEventLogger(logging.Logger):
+    """
+    CLI Event Logger that extends Python's logging.Logger.
+    
+    Combines Python's standard logging.Logger with structured event logging
+    from ConsoleEventLogger. All standard logging.Logger methods work as expected,
+    and additional event logging methods are available.
+    """
+    
+    def __init__(self, name: str, level: int = logging.NOTSET):
+        """
+        Initialize CLI Event Logger.
+        
+        Args:
+            name: Logger name
+            level: Logging level
+        """
+        # Initialize Python's Logger
+        super().__init__(name, level)
+        
+        # Initialize internal event logger for structured logging
+        self._event_logger = ConsoleEventLogger(
+            max_entries=1000,
+            use_milliseconds=True,
+            default_source=name
+        )
+    
+    # Event logging methods (from IEventLogger)
+    
+    def log_event(
+        self,
+        msg: str,
+        source: Optional[str] = None,
+        data: Optional[Any] = None,
+        color: Optional[str] = None,
+        label: Optional[str] = None
+    ) -> ConsoleEvent:
+        """Log a general event message."""
+        event = self._event_logger.log(msg, source=source, data=data, color=color, label=label)
+        # Also log using standard logger
+        super().info(msg)
+        return event
+    
+    def info_event(
+        self,
+        msg: str,
+        source: Optional[str] = None,
+        data: Optional[Any] = None
+    ) -> ConsoleEvent:
+        """Log an info event."""
+        event = self._event_logger.info(msg, source=source, data=data)
+        super().info(msg)
+        return event
+    
+    def warn_event(
+        self,
+        msg: str,
+        source: Optional[str] = None,
+        data: Optional[Any] = None
+    ) -> ConsoleEvent:
+        """Log a warning event."""
+        event = self._event_logger.warn(msg, source=source, data=data)
+        super().warning(msg)
+        return event
+    
+    def error_event(
+        self,
+        msg: str,
+        source: Optional[str] = None,
+        data: Optional[Any] = None,
+        stack: Optional[str] = None
+    ) -> ConsoleEvent:
+        """Log an error event."""
+        event = self._event_logger.error(msg, source=source, data=data, stack=stack)
+        super().error(msg, exc_info=stack is not None)
+        return event
+    
+    def debug_event(
+        self,
+        msg: str,
+        source: Optional[str] = None,
+        data: Optional[Any] = None
+    ) -> ConsoleEvent:
+        """Log a debug event."""
+        event = self._event_logger.debug(msg, source=source, data=data)
+        super().debug(msg)
+        return event
+    
+    # Override standard logging methods to also log events
+    def info(self, msg: object, *args, **kwargs) -> None:
+        """Log info message (standard logger + event logger)."""
+        msg_str = str(msg) % args if args else str(msg)
+        self._event_logger.info(msg_str, source=self.name)
+        super().info(msg, *args, **kwargs)
+    
+    def warning(self, msg: object, *args, **kwargs) -> None:
+        """Log warning message (standard logger + event logger)."""
+        msg_str = str(msg) % args if args else str(msg)
+        self._event_logger.warn(msg_str, source=self.name)
+        super().warning(msg, *args, **kwargs)
+    
+    def error(self, msg: object, *args, **kwargs) -> None:
+        """Log error message (standard logger + event logger)."""
+        msg_str = str(msg) % args if args else str(msg)
+        self._event_logger.error(msg_str, source=self.name)
+        super().error(msg, *args, **kwargs)
+    
+    def debug(self, msg: object, *args, **kwargs) -> None:
+        """Log debug message (standard logger + event logger)."""
+        msg_str = str(msg) % args if args else str(msg)
+        self._event_logger.debug(msg_str, source=self.name)
+        super().debug(msg, *args, **kwargs)
+    
+    def critical(self, msg: object, *args, **kwargs) -> None:
+        """Log critical message (standard logger + event logger)."""
+        msg_str = str(msg) % args if args else str(msg)
+        self._event_logger.error(msg_str, source=self.name)
+        super().critical(msg, *args, **kwargs)
+    
+    # Event logger methods (delegate to internal event logger)
+    
+    def get_events(
+        self,
+        event_type: Optional[ConsoleEventType] = None,
+        level: Optional[LogLevel] = None,
+        source: Optional[str] = None,
+        limit: Optional[int] = None
+    ) -> list[dict]:
+        """Get logged events as dictionaries."""
+        return self._event_logger.get_events(event_type=event_type, level=level, source=source, limit=limit)
+    
+    def clear_events(self) -> None:
+        """Clear all logged events."""
+        self._event_logger.clear()
+    
+    def count_events(self) -> int:
+        """Get the number of logged events."""
+        return self._event_logger.count()
+    
+    @property
+    def event_logger(self) -> ConsoleEventLogger:
+        """Get the internal event logger instance."""
+        return self._event_logger
+
+
+__all__ = [
+    'CliEventLogger',
+]