kollabor 0.4.9__py3-none-any.whl

core/utils/dict_utils.py

@@ -0,0 +1,212 @@
+"""Dictionary utility functions for configuration and data manipulation."""
+
+import logging
+from typing import Any, Dict, List, Optional, Union
+
+logger = logging.getLogger(__name__)
+
+
+def deep_merge(target: Dict[str, Any], source: Dict[str, Any]) -> Dict[str, Any]:
+    """Deep merge source dictionary into target dictionary.
+    
+    Recursively merges dictionaries, with source values taking precedence.
+    Non-dict values in source will overwrite target values.
+    
+    Args:
+        target: Target dictionary to merge into (not modified).
+        source: Source dictionary to merge from.
+        
+    Returns:
+        New dictionary with merged values.
+        
+    Example:
+        >>> target = {"a": {"b": 1, "c": 2}, "d": 3}
+        >>> source = {"a": {"b": 10, "e": 4}, "f": 5}
+        >>> deep_merge(target, source)
+        {"a": {"b": 10, "c": 2, "e": 4}, "d": 3, "f": 5}
+    """
+    if not isinstance(target, dict):
+        logger.warning(f"Target is not a dict: {type(target)}")
+        return source if isinstance(source, dict) else {}
+    
+    if not isinstance(source, dict):
+        logger.warning(f"Source is not a dict: {type(source)}")
+        return target.copy()
+    
+    result = target.copy()
+    
+    for key, value in source.items():
+        if (key in result and 
+            isinstance(result[key], dict) and 
+            isinstance(value, dict)):
+            # Recursively merge nested dictionaries
+            result[key] = deep_merge(result[key], value)
+        else:
+            # Overwrite with source value
+            result[key] = value
+    
+    return result
+
+
+def safe_get(data: Dict[str, Any], key_path: str, default: Any = None) -> Any:
+    """Safely get a value from nested dictionary using dot notation.
+    
+    Args:
+        data: Dictionary to search in.
+        key_path: Dot-separated path to the value (e.g., "section.subsection.key").
+        default: Default value if key not found.
+        
+    Returns:
+        Value at key_path or default if not found.
+        
+    Example:
+        >>> data = {"terminal": {"render_fps": 20}}
+        >>> safe_get(data, "terminal.render_fps")
+        20
+        >>> safe_get(data, "missing.key", "fallback")
+        "fallback"
+    """
+    if not isinstance(data, dict):
+        return default
+    
+    if not key_path:
+        return default
+        
+    keys = key_path.split('.')
+    current = data
+    
+    for key in keys:
+        if not isinstance(current, dict) or key not in current:
+            return default
+        current = current[key]
+    
+    return current
+
+
+def safe_set(data: Dict[str, Any], key_path: str, value: Any) -> bool:
+    """Safely set a value in nested dictionary using dot notation.
+    
+    Creates intermediate dictionaries as needed.
+    
+    Args:
+        data: Dictionary to modify (modified in place).
+        key_path: Dot-separated path to set (e.g., "section.subsection.key").
+        value: Value to set.
+        
+    Returns:
+        True if successful, False otherwise.
+        
+    Example:
+        >>> data = {}
+        >>> safe_set(data, "terminal.render_fps", 30)
+        True
+        >>> data
+        {"terminal": {"render_fps": 30}}
+    """
+    if not isinstance(data, dict):
+        logger.error(f"Cannot set key in non-dict: {type(data)}")
+        return False
+    
+    if not key_path:
+        logger.error("Empty key_path provided")
+        return False
+    
+    try:
+        keys = key_path.split('.')
+        current = data
+        
+        # Navigate to parent of target key, creating dicts as needed
+        for key in keys[:-1]:
+            if key not in current:
+                current[key] = {}
+            elif not isinstance(current[key], dict):
+                logger.warning(f"Overwriting non-dict value at key '{key}'")
+                current[key] = {}
+            current = current[key]
+        
+        # Set the final value
+        current[keys[-1]] = value
+        return True
+        
+    except Exception as e:
+        logger.error(f"Failed to set key '{key_path}': {e}")
+        return False
+
+
+def merge_multiple(configs: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """Merge multiple dictionaries in order.
+    
+    Args:
+        configs: List of dictionaries to merge (later configs take precedence).
+        
+    Returns:
+        Merged dictionary.
+        
+    Example:
+        >>> configs = [{"a": 1}, {"b": 2}, {"a": 10}]
+        >>> merge_multiple(configs)
+        {"a": 10, "b": 2}
+    """
+    if not configs:
+        return {}
+    
+    result = {}
+    for config in configs:
+        if isinstance(config, dict):
+            result = deep_merge(result, config)
+        else:
+            logger.warning(f"Skipping non-dict config: {type(config)}")
+    
+    return result
+
+
+def flatten_dict(data: Dict[str, Any], prefix: str = "", separator: str = ".") -> Dict[str, Any]:
+    """Flatten nested dictionary to dot-notation keys.
+    
+    Args:
+        data: Dictionary to flatten.
+        prefix: Prefix for keys (used internally for recursion).
+        separator: Separator for nested keys.
+        
+    Returns:
+        Flattened dictionary.
+        
+    Example:
+        >>> data = {"a": {"b": 1, "c": 2}, "d": 3}
+        >>> flatten_dict(data)
+        {"a.b": 1, "a.c": 2, "d": 3}
+    """
+    result = {}
+    
+    for key, value in data.items():
+        new_key = f"{prefix}{separator}{key}" if prefix else key
+        
+        if isinstance(value, dict):
+            result.update(flatten_dict(value, new_key, separator))
+        else:
+            result[new_key] = value
+    
+    return result
+
+
+def unflatten_dict(data: Dict[str, Any], separator: str = ".") -> Dict[str, Any]:
+    """Unflatten dot-notation keys to nested dictionary.
+    
+    Args:
+        data: Dictionary with dot-notation keys.
+        separator: Separator used in keys.
+        
+    Returns:
+        Nested dictionary.
+        
+    Example:
+        >>> data = {"a.b": 1, "a.c": 2, "d": 3}
+        >>> unflatten_dict(data)
+        {"a": {"b": 1, "c": 2}, "d": 3}
+    """
+    result = {}
+    
+    for key, value in data.items():
+        safe_set(result, key.replace(separator, "."), value)
+    
+    return result

core/utils/error_utils.py

@@ -0,0 +1,275 @@
+"""Error handling utility functions for consistent error management."""
+
+import asyncio
+import functools
+import logging
+from typing import Any, Callable, Optional, TypeVar, Union
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar('T')
+
+
+def log_and_continue(operation_logger: logging.Logger, operation: str, exception: Exception) -> None:
+    """Log an error and continue execution.
+    
+    Standardized error logging format for non-fatal errors.
+    
+    Args:
+        operation_logger: Logger to use for error message.
+        operation: Description of the operation that failed.
+        exception: Exception that occurred.
+        
+    Example:
+        >>> try:
+        ...     risky_operation()
+        ... except Exception as e:
+        ...     log_and_continue(logger, "loading plugin config", e)
+    """
+    operation_logger.error(f"Failed {operation}: {exception}")
+
+
+def safe_execute(func: Callable[[], T], error_msg: str, default: T = None, 
+                logger_instance: logging.Logger = None) -> T:
+    """Execute function with error handling and default return value.
+    
+    Args:
+        func: Function to execute.
+        error_msg: Error message to log if function fails.
+        default: Default value to return on error.
+        logger_instance: Logger to use (defaults to module logger).
+        
+    Returns:
+        Function result or default value on error.
+        
+    Example:
+        >>> def risky_function():
+        ...     return 1 / 0
+        >>> result = safe_execute(risky_function, "dividing by zero", default=42)
+        >>> result  # Returns 42 since function raises exception
+        42
+    """
+    log = logger_instance or logger
+    
+    try:
+        return func()
+    except Exception as e:
+        log.error(f"{error_msg}: {e}")
+        return default
+
+
+async def safe_execute_async(func: Callable[[], T], error_msg: str, default: T = None, 
+                           logger_instance: logging.Logger = None, timeout: float = None) -> T:
+    """Execute async function with error handling and default return value.
+    
+    Args:
+        func: Async function to execute.
+        error_msg: Error message to log if function fails.
+        default: Default value to return on error.
+        logger_instance: Logger to use (defaults to module logger).
+        timeout: Optional timeout in seconds.
+        
+    Returns:
+        Function result or default value on error/timeout.
+        
+    Example:
+        >>> async def risky_async_function():
+        ...     await asyncio.sleep(10)  # Long operation
+        >>> result = await safe_execute_async(
+        ...     risky_async_function, 
+        ...     "long operation", 
+        ...     default="timed_out",
+        ...     timeout=1.0
+        ... )
+        >>> result  # Returns "timed_out" due to timeout
+        "timed_out"
+    """
+    log = logger_instance or logger
+    
+    try:
+        if timeout is not None:
+            return await asyncio.wait_for(func(), timeout=timeout)
+        else:
+            return await func()
+    except asyncio.TimeoutError:
+        log.warning(f"{error_msg}: operation timed out after {timeout}s")
+        return default
+    except Exception as e:
+        log.error(f"{error_msg}: {e}")
+        return default
+
+
+def retry_on_failure(max_attempts: int = 3, delay: float = 0.1, 
+                    backoff_multiplier: float = 2.0,
+                    logger_instance: logging.Logger = None):
+    """Decorator to retry function on failure with exponential backoff.
+    
+    Args:
+        max_attempts: Maximum number of attempts.
+        delay: Initial delay between attempts in seconds.
+        backoff_multiplier: Multiplier for delay after each failure.
+        logger_instance: Logger to use for retry messages.
+        
+    Example:
+        >>> @retry_on_failure(max_attempts=3, delay=0.1)
+        ... def flaky_function():
+        ...     import random
+        ...     if random.random() < 0.7:  # 70% chance of failure
+        ...         raise Exception("Random failure")
+        ...     return "success"
+    """
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            log = logger_instance or logger
+            current_delay = delay
+            
+            for attempt in range(max_attempts):
+                try:
+                    return func(*args, **kwargs)
+                except Exception as e:
+                    if attempt == max_attempts - 1:
+                        # Last attempt, re-raise the exception
+                        log.error(f"Function {func.__name__} failed after {max_attempts} attempts: {e}")
+                        raise
+                    else:
+                        log.warning(f"Function {func.__name__} failed (attempt {attempt + 1}/{max_attempts}): {e}")
+                        if current_delay > 0:
+                            import time
+                            time.sleep(current_delay)
+                            current_delay *= backoff_multiplier
+        
+        return wrapper
+    return decorator
+
+
+class ErrorAccumulator:
+    """Accumulate errors during batch operations for later reporting."""
+    
+    def __init__(self, logger_instance: logging.Logger = None):
+        """Initialize error accumulator.
+        
+        Args:
+            logger_instance: Logger to use for error reporting.
+        """
+        self.errors = []
+        self.warnings = []
+        self.logger = logger_instance or logger
+    
+    def add_error(self, operation: str, error: Union[str, Exception]) -> None:
+        """Add an error to the accumulator.
+        
+        Args:
+            operation: Description of operation that failed.
+            error: Error message or exception.
+        """
+        error_msg = str(error)
+        self.errors.append(f"{operation}: {error_msg}")
+        self.logger.error(f"Accumulated error - {operation}: {error_msg}")
+    
+    def add_warning(self, operation: str, warning: Union[str, Exception]) -> None:
+        """Add a warning to the accumulator.
+        
+        Args:
+            operation: Description of operation that had issues.
+            warning: Warning message or exception.
+        """
+        warning_msg = str(warning)
+        self.warnings.append(f"{operation}: {warning_msg}")
+        self.logger.warning(f"Accumulated warning - {operation}: {warning_msg}")
+    
+    def has_errors(self) -> bool:
+        """Check if any errors were accumulated."""
+        return len(self.errors) > 0
+    
+    def has_warnings(self) -> bool:
+        """Check if any warnings were accumulated."""
+        return len(self.warnings) > 0
+    
+    def get_summary(self) -> str:
+        """Get summary of accumulated errors and warnings."""
+        parts = []
+        if self.errors:
+            parts.append(f"{len(self.errors)} errors")
+        if self.warnings:
+            parts.append(f"{len(self.warnings)} warnings")
+        
+        if not parts:
+            return "No issues"
+        
+        return ", ".join(parts)
+    
+    def report_summary(self) -> None:
+        """Log a summary of accumulated errors and warnings."""
+        if self.errors:
+            self.logger.error(f"Batch operation completed with {len(self.errors)} errors:")
+            for error in self.errors:
+                self.logger.error(f"  - {error}")
+        
+        if self.warnings:
+            self.logger.warning(f"Batch operation completed with {len(self.warnings)} warnings:")
+            for warning in self.warnings:
+                self.logger.warning(f"  - {warning}")
+        
+        if not self.errors and not self.warnings:
+            self.logger.info("Batch operation completed successfully")
+
+
+def handle_startup_errors(operation_name: str, logger_instance: logging.Logger = None):
+    """Decorator for startup operations that should not crash the application.
+    
+    Args:
+        operation_name: Name of the startup operation.
+        logger_instance: Logger to use for error reporting.
+        
+    Example:
+        >>> @handle_startup_errors("plugin initialization")
+        ... def initialize_plugin():
+        ...     # Plugin initialization code that might fail
+        ...     pass
+    """
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            log = logger_instance or logger
+            try:
+                return func(*args, **kwargs)
+            except Exception as e:
+                log.error(f"Startup operation '{operation_name}' failed: {e}")
+                log.info(f"Continuing startup despite {operation_name} failure")
+                return None
+        
+        return wrapper
+    return decorator
+
+
+def validate_and_log(condition: bool, error_msg: str, 
+                    logger_instance: logging.Logger = None, 
+                    raise_on_failure: bool = False) -> bool:
+    """Validate condition and log error if validation fails.
+    
+    Args:
+        condition: Condition to validate.
+        error_msg: Error message to log if condition is False.
+        logger_instance: Logger to use for error reporting.
+        raise_on_failure: Whether to raise exception on validation failure.
+        
+    Returns:
+        True if condition is True, False otherwise.
+        
+    Raises:
+        ValueError: If condition is False and raise_on_failure is True.
+        
+    Example:
+        >>> validate_and_log(len("test") > 10, "String too short")
+        False  # Logs error and returns False
+        >>> validate_and_log(len("test") > 0, "String empty") 
+        True   # Returns True, no logging
+    """
+    if not condition:
+        log = logger_instance or logger
+        log.error(error_msg)
+        if raise_on_failure:
+            raise ValueError(error_msg)
+        return False
+    return True

core/utils/key_reader.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Key reader utility for debugging terminal input sequences.
+
+This tool helps debug what actual key sequences are sent by the terminal
+when pressing various key combinations. Useful for implementing new
+keyboard shortcuts and understanding terminal behavior.
+
+Usage:
+    python core/utils/key_reader.py
+
+Press keys to see their sequences, Ctrl+C to exit.
+"""
+
+import sys
+import signal
+
+# Platform-specific imports
+IS_WINDOWS = sys.platform == "win32"
+
+if IS_WINDOWS:
+    import msvcrt
+else:
+    import tty
+    import termios
+    import select
+
+
+def signal_handler(sig, frame):
+    """Handle Ctrl+C gracefully."""
+    print('\n\nExiting key reader...')
+    sys.exit(0)
+
+
+def main_unix():
+    """Main key reader loop for Unix systems."""
+    print("Key Reader (Unix) - Press keys to see their sequences (Ctrl+C to exit)")
+    print("=" * 60)
+
+    # Set up signal handler for graceful exit
+    signal.signal(signal.SIGINT, signal_handler)
+
+    # Save terminal settings
+    fd = sys.stdin.fileno()
+    old_settings = termios.tcgetattr(fd)
+
+    try:
+        # Set terminal to raw mode
+        tty.setraw(sys.stdin.fileno())
+
+        key_count = 0
+
+        while True:
+            # Read one character
+            char = sys.stdin.read(1)
+            key_count += 1
+
+            # Get character info
+            ascii_code = ord(char)
+            hex_code = hex(ascii_code)
+
+            # Determine key name
+            if ascii_code == 3:  # Ctrl+C
+                print(f"\n\r[{key_count:03d}] Key: 'CTRL+C' | ASCII: {ascii_code} | Hex: {hex_code} | Raw: {repr(char)}")
+                break
+            elif ascii_code == 27:  # ESC or start of escape sequence
+                key_name = "ESC"
+                # Try to read more characters for escape sequences
+                try:
+                    # Set a short timeout to see if more chars follow
+                    if select.select([sys.stdin], [], [], 0.1)[0]:
+                        sequence = char
+                        while select.select([sys.stdin], [], [], 0.05)[0]:
+                            next_char = sys.stdin.read(1)
+                            sequence += next_char
+                            if len(sequence) > 10:  # Prevent infinite sequences
+                                break
+
+                        # Update display info
+                        char = sequence
+                        ascii_code = f"ESC sequence"
+                        hex_code = " ".join(hex(ord(c)) for c in sequence)
+                        key_name = f"ESC_SEQ({sequence[1:]})" if len(sequence) > 1 else "ESC"
+                except:
+                    pass
+            elif 1 <= ascii_code <= 26:  # Ctrl+A through Ctrl+Z
+                key_name = f"CTRL+{chr(ascii_code + 64)}"
+            elif ascii_code == 127:
+                key_name = "BACKSPACE"
+            elif 32 <= ascii_code <= 126:
+                key_name = f"'{char}'"
+            else:
+                key_name = f"SPECIAL({ascii_code})"
+
+            # Display the key info
+            print(f"\r[{key_count:03d}] Key: {key_name} | ASCII: {ascii_code} | Hex: {hex_code} | Raw: {repr(char)}")
+
+    finally:
+        # Restore terminal settings
+        termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+
+
+def main_windows():
+    """Main key reader loop for Windows systems."""
+    print("Key Reader (Windows) - Press keys to see their sequences (Ctrl+C to exit)")
+    print("=" * 60)
+
+    key_count = 0
+
+    try:
+        while True:
+            if msvcrt.kbhit():
+                # Read a key
+                char = msvcrt.getch()
+                key_count += 1
+
+                # Get character info
+                ascii_code = char[0] if isinstance(char, bytes) else ord(char)
+                hex_code = hex(ascii_code)
+
+                # Handle special keys (arrow keys, function keys, etc.)
+                if ascii_code in (0, 224):  # Extended key prefix
+                    # Read the actual key code
+                    ext_char = msvcrt.getch()
+                    ext_code = ext_char[0] if isinstance(ext_char, bytes) else ord(ext_char)
+                    key_name = f"EXTENDED({ext_code})"
+                    # Map common extended keys
+                    ext_key_map = {
+                        72: "ArrowUp", 80: "ArrowDown",
+                        75: "ArrowLeft", 77: "ArrowRight",
+                        71: "Home", 79: "End",
+                        73: "PageUp", 81: "PageDown",
+                        82: "Insert", 83: "Delete",
+                        59: "F1", 60: "F2", 61: "F3", 62: "F4",
+                        63: "F5", 64: "F6", 65: "F7", 66: "F8",
+                        67: "F9", 68: "F10", 133: "F11", 134: "F12",
+                    }
+                    if ext_code in ext_key_map:
+                        key_name = ext_key_map[ext_code]
+                    print(f"[{key_count:03d}] Key: {key_name} | Code: {ascii_code},{ext_code} | Hex: {hex_code},{hex(ext_code)}")
+                elif ascii_code == 3:  # Ctrl+C
+                    print(f"[{key_count:03d}] Key: 'CTRL+C' | ASCII: {ascii_code} | Hex: {hex_code}")
+                    break
+                elif ascii_code == 27:  # ESC
+                    print(f"[{key_count:03d}] Key: 'ESC' | ASCII: {ascii_code} | Hex: {hex_code}")
+                elif 1 <= ascii_code <= 26:  # Ctrl+A through Ctrl+Z
+                    key_name = f"CTRL+{chr(ascii_code + 64)}"
+                    print(f"[{key_count:03d}] Key: {key_name} | ASCII: {ascii_code} | Hex: {hex_code}")
+                elif ascii_code == 8:
+                    print(f"[{key_count:03d}] Key: BACKSPACE | ASCII: {ascii_code} | Hex: {hex_code}")
+                elif ascii_code == 13:
+                    print(f"[{key_count:03d}] Key: ENTER | ASCII: {ascii_code} | Hex: {hex_code}")
+                elif 32 <= ascii_code <= 126:
+                    char_str = chr(ascii_code)
+                    print(f"[{key_count:03d}] Key: '{char_str}' | ASCII: {ascii_code} | Hex: {hex_code}")
+                else:
+                    print(f"[{key_count:03d}] Key: SPECIAL({ascii_code}) | Hex: {hex_code}")
+
+    except KeyboardInterrupt:
+        print('\n\nExiting key reader...')
+
+
+def main():
+    """Main entry point - selects platform-specific implementation."""
+    if IS_WINDOWS:
+        main_windows()
+    else:
+        main_unix()
+
+
+if __name__ == "__main__":
+    main()