provide-foundation 0.0.0.dev0__py3-none-any.whl

provide/foundation/errors/handlers.py

@@ -0,0 +1,360 @@
+"""Error handling utilities and context managers.
+
+Provides tools for handling errors in a consistent and structured way.
+"""
+
+from collections.abc import Callable, Generator
+from contextlib import contextmanager
+from typing import Any, TypeVar
+
+from attrs import define, field
+
+from provide.foundation.errors.base import FoundationError
+from provide.foundation.errors.context import capture_error_context
+
+
+def _get_logger():
+    """Get logger instance lazily to avoid circular imports."""
+    from provide.foundation.logger import logger
+
+    return logger
+
+
+T = TypeVar("T")
+
+
+@contextmanager
+def error_boundary(
+    *catch: type[Exception],
+    on_error: Callable[[Exception], Any] | None = None,
+    log_errors: bool = True,
+    reraise: bool = True,
+    context: dict[str, Any] | None = None,
+    fallback: Any = None,
+) -> Generator[None, None, None]:
+    """Context manager for structured error handling with logging.
+
+    Args:
+        *catch: Exception types to catch (defaults to Exception if empty).
+        on_error: Optional callback function when error is caught.
+        log_errors: Whether to log caught errors.
+        reraise: Whether to re-raise after handling.
+        context: Additional context for error logging.
+        fallback: Value to return if error is suppressed (when reraise=False).
+
+    Yields:
+        None
+
+    Examples:
+        >>> with error_boundary(ValueError, on_error=handle_error):
+        ...     risky_operation()
+
+        >>> # Suppress and log specific errors
+        >>> with error_boundary(KeyError, reraise=False, fallback=None):
+        ...     value = data["missing_key"]
+    """
+    # Default to catching all exceptions if none specified
+    catch_types = catch if catch else (Exception,)
+
+    try:
+        yield
+    except catch_types as e:
+        if log_errors:
+            # Build error context
+            error_context = context or {}
+
+            # Add error details
+            error_context.update(
+                {
+                    "error.type": type(e).__name__,
+                    "error.message": str(e),
+                }
+            )
+
+            # If it's a FoundationError, merge its context
+            if isinstance(e, FoundationError) and e.context:
+                error_context.update(e.context)
+
+            # Log the error
+            _get_logger().error(
+                f"Error caught in boundary: {e}", exc_info=True, **error_context
+            )
+
+        # Call error handler if provided
+        if on_error:
+            try:
+                on_error(e)
+            except Exception as handler_error:
+                if log_errors:
+                    _get_logger().error(
+                        f"Error handler failed: {handler_error}",
+                        exc_info=True,
+                        original_error=str(e),
+                    )
+
+        # Re-raise if configured
+        if reraise:
+            raise
+
+        # Return fallback value if not re-raising
+        return fallback
+
+
+@contextmanager
+def transactional(
+    rollback: Callable[[], None],
+    commit: Callable[[], None] | None = None,
+    on_error: Callable[[Exception], None] | None = None,
+    log_errors: bool = True,
+) -> Generator[None, None, None]:
+    """Context manager for transactional operations with rollback.
+
+    Args:
+        rollback: Function to call on error to rollback changes.
+        commit: Optional function to call on success.
+        on_error: Optional error handler before rollback.
+        log_errors: Whether to log errors.
+
+    Yields:
+        None
+
+    Examples:
+        >>> def rollback_changes():
+        ...     db.rollback()
+        ...
+        >>> def commit_changes():
+        ...     db.commit()
+        ...
+        >>> with transactional(rollback_changes, commit_changes):
+        ...     db.execute("INSERT INTO users ...")
+        ...     db.execute("UPDATE accounts ...")
+    """
+    try:
+        yield
+        # Call commit if provided and no exception occurred
+        if commit:
+            commit()
+    except Exception as e:
+        if log_errors:
+            _get_logger().error(
+                "Transaction failed, rolling back", exc_info=True, error=str(e)
+            )
+
+        # Call error handler if provided
+        if on_error:
+            try:
+                on_error(e)
+            except Exception as handler_error:
+                if log_errors:
+                    _get_logger().error(
+                        f"Transaction error handler failed: {handler_error}",
+                        original_error=str(e),
+                    )
+
+        # Perform rollback
+        try:
+            rollback()
+            if log_errors:
+                _get_logger().info("Transaction rolled back successfully")
+        except Exception as rollback_error:
+            if log_errors:
+                _get_logger().critical(
+                    f"Rollback failed: {rollback_error}", original_error=str(e)
+                )
+            # Re-raise the rollback error as it's more critical
+            raise rollback_error from e
+
+        # Re-raise original exception
+        raise
+
+
+def handle_error(
+    error: Exception,
+    *,
+    log: bool = True,
+    capture_context: bool = True,
+    reraise: bool = False,
+    fallback: Any = None,
+) -> Any:
+    """Handle an error with logging and optional context capture.
+
+    Args:
+        error: The exception to handle.
+        log: Whether to log the error.
+        capture_context: Whether to capture error context.
+        reraise: Whether to re-raise the error after handling.
+        fallback: Value to return if not re-raising.
+
+    Returns:
+        The fallback value if not re-raising.
+
+    Raises:
+        The original error if reraise=True.
+
+    Examples:
+        >>> try:
+        ...     risky_operation()
+        ... except ValueError as e:
+        ...     result = handle_error(e, fallback="default")
+    """
+    # Capture context if requested
+    context = None
+    if capture_context:
+        context = capture_error_context(error)
+
+    # Log if requested
+    if log:
+        log_context = context.to_dict() if context else {}
+        _get_logger().error(f"Handling error: {error}", exc_info=True, **log_context)
+
+    # Re-raise if requested
+    if reraise:
+        raise error
+
+    return fallback
+
+
+@define(kw_only=True, slots=True)
+class ErrorHandler:
+    """Configurable error handler with type-based policies.
+
+    Attributes:
+        policies: Mapping of error types to handler functions.
+        default_action: Default handler for unmatched errors.
+        log_all: Whether to log all handled errors.
+        capture_context: Whether to capture error context.
+        reraise_unhandled: Whether to re-raise unhandled errors.
+
+    Examples:
+        >>> def handle_validation(e: ValidationError):
+        ...     return {"error": "Invalid input", "details": e.context}
+        ...
+        >>> handler = ErrorHandler(
+        ...     policies={ValidationError: handle_validation},
+        ...     default_action=lambda e: None
+        ... )
+        >>> result = handler.handle(some_error)
+    """
+
+    policies: dict[type[Exception], Callable[[Exception], Any]] = field(
+        factory=lambda: {}
+    )
+    default_action: Callable[[Exception], Any] = field(default=lambda e: None)
+    log_all: bool = True
+    capture_context: bool = True
+    reraise_unhandled: bool = False
+
+    def add_policy(
+        self, error_type: type[Exception], handler: Callable[[Exception], Any]
+    ) -> "ErrorHandler":
+        """Add or update a handler policy for an error type.
+
+        Args:
+            error_type: Exception type to handle.
+            handler: Handler function for this error type.
+
+        Returns:
+            Self for method chaining.
+        """
+        self.policies[error_type] = handler
+        return self
+
+    def handle(self, error: Exception) -> Any:
+        """Handle an error based on configured policies.
+
+        Args:
+            error: The exception to handle.
+
+        Returns:
+            Result from the handler function.
+
+        Raises:
+            The original error if reraise_unhandled=True and no handler matches.
+
+        Examples:
+            >>> result = handler.handle(ValidationError("Invalid"))
+        """
+        # Find matching handler
+        handler = None
+        for error_type, policy_handler in self.policies.items():
+            if isinstance(error, error_type):
+                handler = policy_handler
+                break
+
+        # Use default if no match
+        if handler is None:
+            handler = self.default_action
+
+            # Check if we should re-raise unhandled
+            if self.reraise_unhandled and handler is self.default_action:
+                if self.log_all:
+                    _get_logger().warning(
+                        f"No handler for {type(error).__name__}, re-raising",
+                        error=str(error),
+                    )
+                raise error
+
+        # Capture context if configured
+        context = None
+        if self.capture_context:
+            context = capture_error_context(error)
+
+        # Log if configured
+        if self.log_all:
+            log_context = context.to_dict() if context else {}
+            _get_logger().info(
+                f"Handling {type(error).__name__} with {handler.__name__}",
+                **log_context,
+            )
+
+        # Execute handler
+        try:
+            return handler(error)
+        except Exception as handler_error:
+            if self.log_all:
+                _get_logger().error(
+                    f"Error handler failed: {handler_error}",
+                    exc_info=True,
+                    original_error=str(error),
+                    handler=handler.__name__,
+                )
+            raise handler_error from error
+
+
+def create_error_handler(**policies: Callable[[Exception], Any]) -> ErrorHandler:
+    """Create an error handler with policies from keyword arguments.
+
+    Args:
+        **policies: Error type names mapped to handler functions.
+
+    Returns:
+        Configured ErrorHandler instance.
+
+    Examples:
+        >>> handler = create_error_handler(
+        ...     ValidationError=lambda e: {"error": str(e)},
+        ...     NetworkError=lambda e: retry_operation(),
+        ...     default=lambda e: None
+        ... )
+    """
+    # Extract default if provided
+    default = policies.pop("default", lambda e: None)
+
+    # Import error types
+    import provide.foundation.errors as errors_module
+
+    # Build policies dict
+    error_policies = {}
+    for error_name, handler_func in policies.items():
+        # Try to get the error class from errors module
+        error_class = getattr(errors_module, error_name, None)
+        if (
+            error_class
+            and isinstance(error_class, type)
+            and issubclass(error_class, Exception)
+        ):
+            error_policies[error_class] = handler_func
+        else:
+            _get_logger().warning(f"Unknown error type: {error_name}")
+
+    return ErrorHandler(policies=error_policies, default_action=default)

provide/foundation/errors/integration.py

@@ -0,0 +1,105 @@
+"""Integration and network-related exceptions."""
+
+from typing import Any
+
+from provide.foundation.errors.base import FoundationError
+
+
+class IntegrationError(FoundationError):
+    """Raised when external service integration fails.
+
+    Args:
+        message: Error message describing the integration failure.
+        service: Optional service name that failed.
+        endpoint: Optional endpoint that was called.
+        status_code: Optional HTTP status code.
+        **kwargs: Additional context passed to FoundationError.
+
+    Examples:
+        >>> raise IntegrationError("API call failed")
+        >>> raise IntegrationError("Auth failed", service="github", status_code=401)
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        service: str | None = None,
+        endpoint: str | None = None,
+        status_code: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if service:
+            kwargs.setdefault("context", {})["integration.service"] = service
+        if endpoint:
+            kwargs.setdefault("context", {})["integration.endpoint"] = endpoint
+        if status_code:
+            kwargs.setdefault("context", {})["integration.status_code"] = status_code
+        super().__init__(message, **kwargs)
+
+    def _default_code(self) -> str:
+        return "INTEGRATION_ERROR"
+
+
+class NetworkError(IntegrationError):
+    """Raised for network-related failures.
+
+    Args:
+        message: Error message describing the network issue.
+        host: Optional hostname or IP address.
+        port: Optional port number.
+        **kwargs: Additional context passed to IntegrationError.
+
+    Examples:
+        >>> raise NetworkError("Connection refused")
+        >>> raise NetworkError("DNS resolution failed", host="api.example.com")
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        host: str | None = None,
+        port: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if host:
+            kwargs.setdefault("context", {})["network.host"] = host
+        if port:
+            kwargs.setdefault("context", {})["network.port"] = port
+        super().__init__(message, **kwargs)
+
+    def _default_code(self) -> str:
+        return "NETWORK_ERROR"
+
+
+class TimeoutError(IntegrationError):
+    """Raised when operations exceed time limits.
+
+    Args:
+        message: Error message describing the timeout.
+        timeout_seconds: Optional timeout limit in seconds.
+        elapsed_seconds: Optional actual elapsed time.
+        **kwargs: Additional context passed to IntegrationError.
+
+    Examples:
+        >>> raise TimeoutError("Request timed out")
+        >>> raise TimeoutError("Operation exceeded limit", timeout_seconds=30, elapsed_seconds=31.5)
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        timeout_seconds: float | None = None,
+        elapsed_seconds: float | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if timeout_seconds is not None:
+            kwargs.setdefault("context", {})["timeout.limit"] = timeout_seconds
+        if elapsed_seconds is not None:
+            kwargs.setdefault("context", {})["timeout.elapsed"] = elapsed_seconds
+        super().__init__(message, **kwargs)
+
+    def _default_code(self) -> str:
+        return "TIMEOUT_ERROR"

provide/foundation/errors/platform.py

@@ -0,0 +1,37 @@
+"""Platform detection and system-related exceptions."""
+
+from typing import Any
+
+from provide.foundation.errors.base import FoundationError
+
+
+class PlatformError(FoundationError):
+    """Raised when platform detection or system operations fail.
+
+    Args:
+        message: Error message describing the platform issue.
+        platform: Optional platform identifier.
+        operation: Optional operation that failed.
+        **kwargs: Additional context passed to FoundationError.
+
+    Examples:
+        >>> raise PlatformError("Failed to detect OS")
+        >>> raise PlatformError("Unsupported platform", platform="freebsd")
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        platform: str | None = None,
+        operation: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if platform:
+            kwargs.setdefault("context", {})["platform.name"] = platform
+        if operation:
+            kwargs.setdefault("context", {})["platform.operation"] = operation
+        super().__init__(message, **kwargs)
+
+    def _default_code(self) -> str:
+        return "PLATFORM_ERROR"

provide/foundation/errors/process.py

@@ -0,0 +1,140 @@
+#
+# provide/foundation/errors/process.py
+#
+"""Process execution related errors."""
+
+from provide.foundation.errors.base import FoundationError
+
+
+class ProcessError(FoundationError):
+    """Error for external process execution failures with output capture."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        command: str | list[str] | None = None,
+        return_code: int | None = None,
+        stdout: str | bytes | None = None,
+        stderr: str | bytes | None = None,
+        timeout: bool = False,
+        **extra_context,
+    ) -> None:
+        """Initialize ProcessError with command execution details.
+
+        Args:
+            message: Human-readable error message
+            command: The command that was executed
+            return_code: Process return/exit code
+            stdout: Standard output from the process
+            stderr: Standard error from the process
+            timeout: Whether the process timed out
+            **extra_context: Additional context information
+        """
+        # Build comprehensive error message
+        full_message = message
+
+        if command:
+            cmd_str = command if isinstance(command, str) else " ".join(command)
+            full_message += f"\nCommand: {cmd_str}"
+
+        if return_code is not None:
+            full_message += f"\nReturn code: {return_code}"
+
+        if timeout:
+            full_message += "\nProcess timed out"
+
+        if stdout:
+            stdout_str = (
+                stdout.decode("utf-8", "replace")
+                if isinstance(stdout, bytes)
+                else stdout
+            )
+            if stdout_str.strip():
+                full_message += f"\n--- STDOUT ---\n{stdout_str.strip()}"
+
+        if stderr:
+            stderr_str = (
+                stderr.decode("utf-8", "replace")
+                if isinstance(stderr, bytes)
+                else stderr
+            )
+            if stderr_str.strip():
+                full_message += f"\n--- STDERR ---\n{stderr_str.strip()}"
+
+        # Store structured data
+        context = extra_context.copy()
+        context.update(
+            {
+                "process.command": command,
+                "process.return_code": return_code,
+                "process.timeout": timeout,
+            }
+        )
+
+        # Store clean stdout/stderr for programmatic access
+        self.stdout = (
+            stdout.decode("utf-8", "replace").strip()
+            if isinstance(stdout, bytes)
+            else stdout.strip()
+            if stdout
+            else None
+        )
+
+        self.stderr = (
+            stderr.decode("utf-8", "replace").strip()
+            if isinstance(stderr, bytes)
+            else stderr.strip()
+            if stderr
+            else None
+        )
+
+        self.command = command
+        self.return_code = return_code
+        self.timeout = timeout
+
+        super().__init__(full_message, context=context)
+
+    def _default_code(self) -> str:
+        """Return default error code for process errors."""
+        return "PROCESS_ERROR"
+
+
+class CommandNotFoundError(ProcessError):
+    """Error when a command/executable is not found."""
+
+    def _default_code(self) -> str:
+        return "COMMAND_NOT_FOUND"
+
+
+class ProcessTimeoutError(ProcessError):
+    """Error when a process times out."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        command: str | list[str] | None = None,
+        timeout_seconds: float | None = None,
+        stdout: str | bytes | None = None,
+        stderr: str | bytes | None = None,
+        **extra_context,
+    ) -> None:
+        context = extra_context.copy()
+        if timeout_seconds is not None:
+            context["process.timeout_seconds"] = timeout_seconds
+
+        super().__init__(
+            message,
+            command=command,
+            stdout=stdout,
+            stderr=stderr,
+            timeout=True,
+            **context,
+        )
+
+    def _default_code(self) -> str:
+        return "PROCESS_TIMEOUT"
+
+
+# 🏗️⚡️⚙️🪄