spatelier 0.3.0__py3-none-any.whl

core/decorators.py

@@ -0,0 +1,263 @@
+"""
+Decorators for Spatelier modules.
+
+This module provides decorators for common patterns like
+error handling, timing, and validation.
+"""
+
+import functools
+import time
+from pathlib import Path
+from typing import Any, Callable, Optional, Union
+
+from core.base import ProcessingResult
+from core.error_handler import get_error_handler
+
+
+def format_duration(seconds: float) -> str:
+    """Format duration in seconds to human-readable format."""
+    if seconds < 60:
+        return f"{seconds:.1f} seconds"
+    elif seconds < 3600:
+        minutes = int(seconds // 60)
+        remaining_seconds = seconds % 60
+        return f"{minutes}m {remaining_seconds:.1f}s"
+    else:
+        hours = int(seconds // 3600)
+        remaining_minutes = int((seconds % 3600) // 60)
+        remaining_seconds = seconds % 60
+        return f"{hours}h {remaining_minutes}m {remaining_seconds:.1f}s"
+
+
+def handle_errors(context: str = "", return_result: bool = True, verbose: bool = False):
+    """
+    Decorator for automatic error handling.
+
+    Args:
+        context: Context for error reporting
+        return_result: Whether to return ProcessingResult on error
+        verbose: Enable verbose logging
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> Union[Any, ProcessingResult]:
+            try:
+                return func(*args, **kwargs)
+            except Exception as e:
+                handler = get_error_handler(verbose=verbose)
+                error_result = handler.handle_error(
+                    e, context, return_result=return_result
+                )
+                if return_result:
+                    return error_result
+                raise
+
+        return wrapper
+
+    return decorator
+
+
+def time_operation(verbose: bool = False):
+    """
+    Decorator for timing operations.
+
+    Args:
+        verbose: Enable verbose logging
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            start_time = time.time()
+            try:
+                result = func(*args, **kwargs)
+                duration = time.time() - start_time
+
+                if verbose:
+                    print(f"{func.__name__} completed in {format_duration(duration)}")
+
+                # Add timing to result if it's a ProcessingResult
+                if isinstance(result, ProcessingResult):
+                    result.duration_seconds = duration
+
+                return result
+            except Exception as e:
+                duration = time.time() - start_time
+                if verbose:
+                    print(
+                        f"{func.__name__} failed after {format_duration(duration)}: {e}"
+                    )
+                raise
+
+        return wrapper
+
+    return decorator
+
+
+def validate_input(
+    input_validator: Optional[Callable] = None,
+    output_validator: Optional[Callable] = None,
+):
+    """
+    Decorator for input/output validation.
+
+    Args:
+        input_validator: Function to validate inputs
+        output_validator: Function to validate outputs
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            # Validate inputs
+            if input_validator:
+                try:
+                    input_validator(*args, **kwargs)
+                except Exception as e:
+                    raise ValueError(f"Input validation failed: {e}")
+
+            result = func(*args, **kwargs)
+
+            # Validate outputs
+            if output_validator:
+                try:
+                    output_validator(result)
+                except Exception as e:
+                    raise ValueError(f"Output validation failed: {e}")
+
+            return result
+
+        return wrapper
+
+    return decorator
+
+
+def retry_on_failure(
+    max_retries: int = 3,
+    delay: float = 1.0,
+    backoff_factor: float = 2.0,
+    exceptions: tuple = (Exception,),
+):
+    """
+    Decorator for retrying operations on failure.
+
+    Args:
+        max_retries: Maximum number of retries
+        delay: Initial delay between retries
+        backoff_factor: Factor to multiply delay by after each retry
+        exceptions: Tuple of exceptions to retry on
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            current_delay = delay
+            last_exception = None
+
+            for attempt in range(max_retries + 1):
+                try:
+                    return func(*args, **kwargs)
+                except exceptions as e:
+                    last_exception = e
+                    if attempt < max_retries:
+                        time.sleep(current_delay)
+                        current_delay *= backoff_factor
+                    else:
+                        raise last_exception
+
+            return None  # Should never reach here
+
+        return wrapper
+
+    return decorator
+
+
+def log_operation(
+    level: str = "INFO", include_args: bool = False, include_result: bool = False
+):
+    """
+    Decorator for logging operations.
+
+    Args:
+        level: Log level
+        include_args: Whether to include function arguments in log
+        include_result: Whether to include result in log
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            from core.logger import get_logger
+
+            logger = get_logger(func.__module__)
+
+            # Log function start
+            log_msg = f"Starting {func.__name__}"
+            if include_args:
+                log_msg += f" with args={args}, kwargs={kwargs}"
+
+            if level.upper() == "DEBUG":
+                logger.debug(log_msg)
+            elif level.upper() == "INFO":
+                logger.info(log_msg)
+            elif level.upper() == "WARNING":
+                logger.warning(log_msg)
+            elif level.upper() == "ERROR":
+                logger.error(log_msg)
+
+            try:
+                result = func(*args, **kwargs)
+
+                # Log function completion
+                log_msg = f"Completed {func.__name__}"
+                if include_result:
+                    log_msg += f" with result={result}"
+
+                if level.upper() == "DEBUG":
+                    logger.debug(log_msg)
+                elif level.upper() == "INFO":
+                    logger.info(log_msg)
+                elif level.upper() == "WARNING":
+                    logger.warning(log_msg)
+                elif level.upper() == "ERROR":
+                    logger.error(log_msg)
+
+                return result
+            except Exception as e:
+                logger.error(f"Failed {func.__name__}: {e}")
+                raise
+
+        return wrapper
+
+    return decorator
+
+
+def ensure_path_exists(path_arg: str = "path"):
+    """
+    Decorator to ensure a path argument exists.
+
+    Args:
+        path_arg: Name of the path argument to validate
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            # Get the path argument
+            if path_arg in kwargs:
+                path = kwargs[path_arg]
+            else:
+                # Try to get from positional args (this is a simplified approach)
+                path = args[0] if args else None
+
+            if path:
+                path_obj = Path(path)
+                if not path_obj.exists():
+                    raise FileNotFoundError(f"Path does not exist: {path}")
+
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

core/error_handler.py

@@ -0,0 +1,210 @@
+"""
+Centralized error handling for Spatelier.
+
+This module provides consistent error handling patterns
+across all services and modules.
+"""
+
+import traceback
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Type, Union
+
+from core.base import ProcessingResult
+from core.logger import get_logger
+
+
+class ErrorHandler:
+    """Centralized error handler for consistent error management."""
+
+    def __init__(self, logger_name: str = "ErrorHandler", verbose: bool = False):
+        """
+        Initialize error handler.
+
+        Args:
+            logger_name: Name for logger
+            verbose: Enable verbose logging
+        """
+        self.verbose = verbose
+        self.logger = get_logger(logger_name, verbose=verbose)
+        self.error_handlers: Dict[Type[Exception], Callable] = {}
+        self._register_default_handlers()
+
+    def _register_default_handlers(self):
+        """Register default error handlers."""
+        self.error_handlers[FileNotFoundError] = self._handle_file_not_found
+        self.error_handlers[PermissionError] = self._handle_permission_error
+        self.error_handlers[OSError] = self._handle_os_error
+        self.error_handlers[ValueError] = self._handle_value_error
+        self.error_handlers[KeyError] = self._handle_key_error
+        self.error_handlers[ImportError] = self._handle_import_error
+
+    def handle_error(
+        self, error: Exception, context: str = "", return_result: bool = True, **kwargs
+    ) -> Optional[ProcessingResult]:
+        """
+        Handle an error with appropriate response.
+
+        Args:
+            error: Exception to handle
+            context: Context where error occurred
+            return_result: Whether to return ProcessingResult
+            **kwargs: Additional context for error handling
+
+        Returns:
+            ProcessingResult if return_result=True, None otherwise
+        """
+        error_type = type(error)
+
+        # Log the error
+        self.logger.error(f"Error in {context}: {error}")
+        if self.verbose:
+            self.logger.debug(f"Error traceback: {traceback.format_exc()}")
+
+        # Get specific handler or use generic handler
+        handler = self.error_handlers.get(error_type, self._handle_generic_error)
+        result = handler(error, context, **kwargs)
+
+        if return_result:
+            return result
+        return None
+
+    def _handle_file_not_found(
+        self, error: FileNotFoundError, context: str, **kwargs
+    ) -> ProcessingResult:
+        """Handle FileNotFoundError."""
+        file_path = getattr(error, "filename", "unknown file")
+        return ProcessingResult.error_result(
+            message=f"File not found: {file_path}",
+            errors=[f"FileNotFoundError in {context}: {str(error)}"],
+        )
+
+    def _handle_permission_error(
+        self, error: PermissionError, context: str, **kwargs
+    ) -> ProcessingResult:
+        """Handle PermissionError."""
+        return ProcessingResult.error_result(
+            message="Permission denied",
+            errors=[f"PermissionError in {context}: {str(error)}"],
+        )
+
+    def _handle_os_error(
+        self, error: OSError, context: str, **kwargs
+    ) -> ProcessingResult:
+        """Handle OSError."""
+        return ProcessingResult.error_result(
+            message=f"System error: {error.strerror}",
+            errors=[f"OSError in {context}: {str(error)}"],
+        )
+
+    def _handle_value_error(
+        self, error: ValueError, context: str, **kwargs
+    ) -> ProcessingResult:
+        """Handle ValueError."""
+        return ProcessingResult.error_result(
+            message=f"Invalid value: {str(error)}",
+            errors=[f"ValueError in {context}: {str(error)}"],
+        )
+
+    def _handle_key_error(
+        self, error: KeyError, context: str, **kwargs
+    ) -> ProcessingResult:
+        """Handle KeyError."""
+        key = str(error).strip("'\"")
+        return ProcessingResult.error_result(
+            message=f"Missing key: {key}",
+            errors=[f"KeyError in {context}: Missing key '{key}'"],
+        )
+
+    def _handle_import_error(
+        self, error: ImportError, context: str, **kwargs
+    ) -> ProcessingResult:
+        """Handle ImportError."""
+        module = getattr(error, "name", "unknown module")
+        return ProcessingResult.error_result(
+            message=f"Import error: {module}",
+            errors=[f"ImportError in {context}: Cannot import {module}"],
+        )
+
+    def _handle_generic_error(
+        self, error: Exception, context: str, **kwargs
+    ) -> ProcessingResult:
+        """Handle generic errors."""
+        return ProcessingResult.error_result(
+            message=f"Unexpected error: {type(error).__name__}",
+            errors=[f"{type(error).__name__} in {context}: {str(error)}"],
+        )
+
+    def register_handler(self, exception_type: Type[Exception], handler: Callable):
+        """Register a custom error handler."""
+        self.error_handlers[exception_type] = handler
+
+    def safe_execute(
+        self,
+        func: Callable,
+        context: str = "",
+        default_result: Optional[ProcessingResult] = None,
+        *args,
+        **kwargs,
+    ) -> ProcessingResult:
+        """
+        Safely execute a function with error handling.
+
+        Args:
+            func: Function to execute
+            context: Context for error reporting
+            default_result: Default result if function fails
+            *args: Function arguments
+            **kwargs: Function keyword arguments
+
+        Returns:
+            ProcessingResult from function or error result
+        """
+        try:
+            result = func(*args, **kwargs)
+            if isinstance(result, ProcessingResult):
+                return result
+            else:
+                return ProcessingResult.success_result(
+                    message="Operation completed successfully",
+                    metadata={"result": result},
+                )
+        except Exception as e:
+            error_result = self.handle_error(e, context, return_result=True)
+            if default_result:
+                return default_result
+            return error_result or ProcessingResult.error_result(
+                message="Operation failed", errors=[f"Unexpected error in {context}"]
+            )
+
+
+# Global error handler instance
+_error_handler: Optional[ErrorHandler] = None
+
+
+def get_error_handler(verbose: bool = False) -> ErrorHandler:
+    """Get global error handler instance."""
+    global _error_handler
+    if _error_handler is None:
+        _error_handler = ErrorHandler(verbose=verbose)
+    return _error_handler
+
+
+def handle_error(
+    error: Exception, context: str = "", verbose: bool = False, **kwargs
+) -> ProcessingResult:
+    """Convenience function for handling errors."""
+    handler = get_error_handler(verbose=verbose)
+    return handler.handle_error(error, context, **kwargs)
+
+
+def safe_execute(
+    func: Callable,
+    context: str = "",
+    verbose: bool = False,
+    default_result: Optional[ProcessingResult] = None,
+    *args,
+    **kwargs,
+) -> ProcessingResult:
+    """Convenience function for safe execution."""
+    handler = get_error_handler(verbose=verbose)
+    return handler.safe_execute(func, context, default_result, *args, **kwargs)