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

provide/foundation/errors/resources.py

@@ -0,0 +1,133 @@
+"""Resource and filesystem-related exceptions."""
+
+from typing import Any
+
+from provide.foundation.errors.base import FoundationError
+
+
+class ResourceError(FoundationError):
+    """Raised when resource operations fail.
+
+    Args:
+        message: Error message describing the resource issue.
+        resource_type: Optional type of resource (file, network, etc.).
+        resource_path: Optional path or identifier of the resource.
+        **kwargs: Additional context passed to FoundationError.
+
+    Examples:
+        >>> raise ResourceError("File not found")
+        >>> raise ResourceError("Permission denied", resource_type="file", resource_path="/etc/config")
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        resource_type: str | None = None,
+        resource_path: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if resource_type:
+            kwargs.setdefault("context", {})["resource.type"] = resource_type
+        if resource_path:
+            kwargs.setdefault("context", {})["resource.path"] = resource_path
+        super().__init__(message, **kwargs)
+
+    def _default_code(self) -> str:
+        return "RESOURCE_ERROR"
+
+
+class NotFoundError(FoundationError):
+    """Raised when a requested resource cannot be found.
+
+    Args:
+        message: Error message describing what was not found.
+        resource_type: Optional type of resource.
+        resource_id: Optional resource identifier.
+        **kwargs: Additional context passed to FoundationError.
+
+    Examples:
+        >>> raise NotFoundError("User not found")
+        >>> raise NotFoundError("Entity missing", resource_type="user", resource_id="123")
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        resource_type: str | None = None,
+        resource_id: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if resource_type:
+            kwargs.setdefault("context", {})["notfound.type"] = resource_type
+        if resource_id:
+            kwargs.setdefault("context", {})["notfound.id"] = resource_id
+        super().__init__(message, **kwargs)
+
+    def _default_code(self) -> str:
+        return "NOT_FOUND_ERROR"
+
+
+class AlreadyExistsError(FoundationError):
+    """Raised when attempting to create a resource that already exists.
+
+    Args:
+        message: Error message describing the conflict.
+        resource_type: Optional type of resource.
+        resource_id: Optional resource identifier.
+        **kwargs: Additional context passed to FoundationError.
+
+    Examples:
+        >>> raise AlreadyExistsError("User already registered")
+        >>> raise AlreadyExistsError("Duplicate key", resource_type="user", resource_id="john@example.com")
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        resource_type: str | None = None,
+        resource_id: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if resource_type:
+            kwargs.setdefault("context", {})["exists.type"] = resource_type
+        if resource_id:
+            kwargs.setdefault("context", {})["exists.id"] = resource_id
+        super().__init__(message, **kwargs)
+
+    def _default_code(self) -> str:
+        return "ALREADY_EXISTS_ERROR"
+
+
+class LockError(FoundationError):
+    """Raised when file lock operations fail.
+
+    Args:
+        message: Error message describing the lock issue.
+        lock_path: Optional path to the lock file.
+        timeout: Optional timeout that was exceeded.
+        **kwargs: Additional context passed to FoundationError.
+
+    Examples:
+        >>> raise LockError("Failed to acquire lock")
+        >>> raise LockError("Lock timeout", lock_path="/tmp/app.lock", timeout=30)
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        lock_path: str | None = None,
+        timeout: float | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if lock_path:
+            kwargs.setdefault("context", {})["lock.path"] = lock_path
+        if timeout is not None:
+            kwargs.setdefault("context", {})["lock.timeout"] = timeout
+        super().__init__(message, **kwargs)
+
+    def _default_code(self) -> str:
+        return "LOCK_ERROR"

provide/foundation/errors/runtime.py

@@ -0,0 +1,160 @@
+"""Runtime and process execution exceptions."""
+
+from typing import Any
+
+from provide.foundation.errors.base import FoundationError
+
+
+class RuntimeError(FoundationError):
+    """Raised for runtime operational errors.
+
+    Args:
+        message: Error message describing the runtime issue.
+        operation: Optional operation that failed.
+        retry_possible: Whether the operation can be retried.
+        **kwargs: Additional context passed to FoundationError.
+
+    Examples:
+        >>> raise RuntimeError("Process failed")
+        >>> raise RuntimeError("Lock timeout", operation="acquire_lock", retry_possible=True)
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        operation: str | None = None,
+        retry_possible: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        if operation:
+            kwargs.setdefault("context", {})["runtime.operation"] = operation
+        kwargs.setdefault("context", {})["runtime.retry_possible"] = retry_possible
+        super().__init__(message, **kwargs)
+
+    def _default_code(self) -> str:
+        return "RUNTIME_ERROR"
+
+
+class ProcessError(RuntimeError):
+    """Raised when process execution fails.
+
+    Args:
+        message: Error message describing the process failure.
+        command: Optional command that was executed.
+        returncode: Optional process return code.
+        stdout: Optional captured stdout.
+        stderr: Optional captured stderr.
+        **kwargs: Additional context passed to RuntimeError.
+
+    Examples:
+        >>> raise ProcessError("Command failed")
+        >>> raise ProcessError("Build failed", command="make", returncode=2)
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        command: str | list[str] | None = None,
+        returncode: int | None = None,
+        stdout: str | None = None,
+        stderr: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        # Store as attributes for compatibility
+        self.command = command
+        self.returncode = returncode
+        self.stdout = stdout
+        self.stderr = stderr
+
+        # Also store in context for structured logging
+        if command:
+            cmd_str = " ".join(command) if isinstance(command, list) else command
+            kwargs.setdefault("context", {})["process.command"] = cmd_str
+        if returncode is not None:
+            kwargs.setdefault("context", {})["process.returncode"] = returncode
+        if stdout:
+            kwargs.setdefault("context", {})["process.stdout"] = stdout
+        if stderr:
+            kwargs.setdefault("context", {})["process.stderr"] = stderr
+        super().__init__(message, **kwargs)
+
+    def _default_code(self) -> str:
+        return "PROCESS_ERROR"
+
+
+class StateError(FoundationError):
+    """Raised when an operation is invalid for the current state.
+
+    Args:
+        message: Error message describing the state issue.
+        current_state: Optional current state.
+        expected_state: Optional expected state.
+        transition: Optional attempted transition.
+        **kwargs: Additional context passed to FoundationError.
+
+    Examples:
+        >>> raise StateError("Invalid state transition")
+        >>> raise StateError("Not ready", current_state="initializing", expected_state="ready")
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        current_state: str | None = None,
+        expected_state: str | None = None,
+        transition: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if current_state:
+            kwargs.setdefault("context", {})["state.current"] = current_state
+        if expected_state:
+            kwargs.setdefault("context", {})["state.expected"] = expected_state
+        if transition:
+            kwargs.setdefault("context", {})["state.transition"] = transition
+        super().__init__(message, **kwargs)
+
+    def _default_code(self) -> str:
+        return "STATE_ERROR"
+
+
+class ConcurrencyError(FoundationError):
+    """Raised when concurrency conflicts occur.
+
+    Args:
+        message: Error message describing the concurrency issue.
+        conflict_type: Optional type of conflict (lock, version, etc.).
+        version_expected: Optional expected version.
+        version_actual: Optional actual version.
+        **kwargs: Additional context passed to FoundationError.
+
+    Examples:
+        >>> raise ConcurrencyError("Optimistic lock failure")
+        >>> raise ConcurrencyError("Version mismatch", version_expected=1, version_actual=2)
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        conflict_type: str | None = None,
+        version_expected: Any = None,
+        version_actual: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        if conflict_type:
+            kwargs.setdefault("context", {})["concurrency.type"] = conflict_type
+        if version_expected is not None:
+            kwargs.setdefault("context", {})["concurrency.version_expected"] = str(
+                version_expected
+            )
+        if version_actual is not None:
+            kwargs.setdefault("context", {})["concurrency.version_actual"] = str(
+                version_actual
+            )
+        super().__init__(message, **kwargs)
+
+    def _default_code(self) -> str:
+        return "CONCURRENCY_ERROR"

provide/foundation/errors/safe_decorators.py

@@ -0,0 +1,133 @@
+"""Safe error decorators that preserve original behavior."""
+
+from collections.abc import Callable
+import functools
+import inspect
+from typing import Any, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _get_logger():
+    """Get logger instance lazily to avoid circular imports."""
+    from provide.foundation.logger import logger
+
+    return logger
+
+
+def log_only_error_context(
+    *,
+    context_provider: Callable[[], dict[str, Any]] | None = None,
+    log_level: str = "debug",
+    log_success: bool = False,
+) -> Callable[[F], F]:
+    """Safe decorator that only adds logging context without changing error behavior.
+
+    This decorator preserves the exact original error message and type while adding
+    structured logging context. It never suppresses errors or changes their behavior.
+
+    Args:
+        context_provider: Function that provides additional logging context.
+        log_level: Level for operation logging ('debug', 'trace', etc.)
+        log_success: Whether to log successful operations.
+
+    Returns:
+        Decorated function that preserves all original error behavior.
+
+    Examples:
+        >>> @log_only_error_context(
+        ...     context_provider=lambda: {"operation": "detect_launcher_type"},
+        ...     log_level="trace"
+        ... )
+        ... def detect_launcher_type(self, path):
+        ...     # Original error messages preserved exactly
+        ...     return self._internal_detect(path)
+    """
+
+    def decorator(func: F) -> F:
+        if inspect.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def async_wrapper(*args, **kwargs):
+                context = context_provider() if context_provider else {}
+                logger = _get_logger()
+
+                # Log function entry if debug/trace level
+                if log_level in ("debug", "trace"):
+                    log_method = getattr(logger, log_level)
+                    log_method(
+                        f"Entering {func.__name__}", function=func.__name__, **context
+                    )
+
+                try:
+                    result = await func(*args, **kwargs)
+
+                    # Log success if requested
+                    if log_success:
+                        log_method = getattr(logger, log_level, logger.debug)
+                        log_method(
+                            f"Successfully completed {func.__name__}",
+                            function=func.__name__,
+                            **context,
+                        )
+
+                    return result
+
+                except Exception as e:
+                    # Log error context without changing the error
+                    logger.error(
+                        f"Error in {func.__name__}",
+                        exc_info=True,
+                        function=func.__name__,
+                        error_type=type(e).__name__,
+                        error_message=str(e),
+                        **context,
+                    )
+                    # Re-raise the original error unchanged
+                    raise
+
+            return async_wrapper  # type: ignore
+        else:
+
+            @functools.wraps(func)
+            def wrapper(*args, **kwargs):
+                context = context_provider() if context_provider else {}
+                logger = _get_logger()
+
+                # Log function entry if debug/trace level
+                if log_level in ("debug", "trace"):
+                    log_method = getattr(logger, log_level)
+                    log_method(
+                        f"Entering {func.__name__}", function=func.__name__, **context
+                    )
+
+                try:
+                    result = func(*args, **kwargs)
+
+                    # Log success if requested
+                    if log_success:
+                        log_method = getattr(logger, log_level, logger.debug)
+                        log_method(
+                            f"Successfully completed {func.__name__}",
+                            function=func.__name__,
+                            **context,
+                        )
+
+                    return result
+
+                except Exception as e:
+                    # Log error context without changing the error
+                    logger.error(
+                        f"Error in {func.__name__}",
+                        exc_info=True,
+                        function=func.__name__,
+                        error_type=type(e).__name__,
+                        error_message=str(e),
+                        **context,
+                    )
+                    # Re-raise the original error unchanged
+                    raise
+
+            return wrapper  # type: ignore
+
+    return decorator

provide/foundation/errors/types.py

@@ -0,0 +1,276 @@
+"""Type definitions and constants for error handling.
+
+Provides error codes, metadata structures, and retry policies.
+"""
+
+from enum import Enum
+from typing import Any
+
+from attrs import define, field
+
+
+class ErrorCode(str, Enum):
+    """Standard error codes for programmatic error handling.
+
+    Use these codes for consistent error identification across the system.
+    Codes are grouped by category with prefixes:
+    - CFG: Configuration errors
+    - VAL: Validation errors
+    - INT: Integration errors
+    - RES: Resource errors
+    - AUTH: Authentication/Authorization errors
+    - SYS: System errors
+    """
+
+    # Configuration errors (CFG)
+    CONFIG_INVALID = "CFG_001"
+    CONFIG_MISSING = "CFG_002"
+    CONFIG_PARSE_ERROR = "CFG_003"
+    CONFIG_TYPE_ERROR = "CFG_004"
+
+    # Validation errors (VAL)
+    VALIDATION_TYPE = "VAL_001"
+    VALIDATION_RANGE = "VAL_002"
+    VALIDATION_FORMAT = "VAL_003"
+    VALIDATION_REQUIRED = "VAL_004"
+    VALIDATION_CONSTRAINT = "VAL_005"
+
+    # Integration errors (INT)
+    INTEGRATION_TIMEOUT = "INT_001"
+    INTEGRATION_AUTH = "INT_002"
+    INTEGRATION_UNAVAILABLE = "INT_003"
+    INTEGRATION_RATE_LIMIT = "INT_004"
+    INTEGRATION_PROTOCOL = "INT_005"
+
+    # Resource errors (RES)
+    RESOURCE_NOT_FOUND = "RES_001"
+    RESOURCE_LOCKED = "RES_002"
+    RESOURCE_PERMISSION = "RES_003"
+    RESOURCE_EXHAUSTED = "RES_004"
+    RESOURCE_CONFLICT = "RES_005"
+
+    # Authentication/Authorization errors (AUTH)
+    AUTH_INVALID_CREDENTIALS = "AUTH_001"
+    AUTH_TOKEN_EXPIRED = "AUTH_002"
+    AUTH_INSUFFICIENT_PERMISSION = "AUTH_003"
+    AUTH_SESSION_INVALID = "AUTH_004"
+    AUTH_MFA_REQUIRED = "AUTH_005"
+
+    # System errors (SYS)
+    SYSTEM_UNAVAILABLE = "SYS_001"
+    SYSTEM_OVERLOAD = "SYS_002"
+    SYSTEM_MAINTENANCE = "SYS_003"
+    SYSTEM_INTERNAL = "SYS_004"
+    SYSTEM_PANIC = "SYS_005"
+
+
+@define(kw_only=True, slots=True)
+class ErrorMetadata:
+    """Additional metadata for error tracking and debugging.
+
+    Attributes:
+        request_id: Optional request identifier for tracing.
+        user_id: Optional user identifier.
+        session_id: Optional session identifier.
+        correlation_id: Optional correlation ID for distributed tracing.
+        retry_count: Number of retry attempts made.
+        retry_after: Seconds to wait before retry.
+        help_url: Optional URL for more information.
+        support_id: Optional support ticket/case ID.
+
+    Examples:
+        >>> meta = ErrorMetadata(
+        ...     request_id="req_123",
+        ...     user_id="user_456",
+        ...     retry_count=2
+        ... )
+    """
+
+    request_id: str | None = None
+    user_id: str | None = None
+    session_id: str | None = None
+    correlation_id: str | None = None
+    retry_count: int = 0
+    retry_after: float | None = None
+    help_url: str | None = None
+    support_id: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary, excluding None values.
+
+        Returns:
+            Dictionary with non-None metadata fields.
+        """
+        result = {}
+        for key in [
+            "request_id",
+            "user_id",
+            "session_id",
+            "correlation_id",
+            "retry_count",
+            "retry_after",
+            "help_url",
+            "support_id",
+        ]:
+            value = getattr(self, key)
+            if value is not None:
+                result[key] = value
+        return result
+
+
+class BackoffStrategy(str, Enum):
+    """Backoff strategies for retry policies."""
+
+    FIXED = "fixed"  # Fixed delay between retries
+    LINEAR = "linear"  # Linear increase (delay * attempt)
+    EXPONENTIAL = "exponential"  # Exponential increase (delay * 2^attempt)
+    FIBONACCI = "fibonacci"  # Fibonacci sequence delays
+
+
+@define(kw_only=True, slots=True)
+class RetryPolicy:
+    """Configuration for retry behavior on errors.
+
+    Attributes:
+        max_attempts: Maximum number of retry attempts.
+        backoff: Backoff strategy to use.
+        base_delay: Base delay in seconds between retries.
+        max_delay: Maximum delay in seconds (caps exponential growth).
+        jitter: Whether to add random jitter to delays.
+        retryable_errors: Optional tuple of exception types to retry on.
+
+    Examples:
+        >>> policy = RetryPolicy(
+        ...     max_attempts=5,
+        ...     backoff=BackoffStrategy.EXPONENTIAL,
+        ...     base_delay=1.0,
+        ...     max_delay=30.0
+        ... )
+    """
+
+    max_attempts: int = 3
+    backoff: BackoffStrategy = BackoffStrategy.EXPONENTIAL
+    base_delay: float = 1.0
+    max_delay: float = 60.0
+    jitter: bool = True
+    retryable_errors: tuple[type[Exception], ...] | None = None
+
+    def calculate_delay(self, attempt: int) -> float:
+        """Calculate delay for a given attempt number.
+
+        Args:
+            attempt: Attempt number (1-based).
+
+        Returns:
+            Delay in seconds.
+        """
+        if attempt <= 0:
+            return 0
+
+        if self.backoff == BackoffStrategy.FIXED:
+            delay = self.base_delay
+        elif self.backoff == BackoffStrategy.LINEAR:
+            delay = self.base_delay * attempt
+        elif self.backoff == BackoffStrategy.EXPONENTIAL:
+            delay = self.base_delay * (2 ** (attempt - 1))
+        elif self.backoff == BackoffStrategy.FIBONACCI:
+            # Calculate fibonacci number for attempt
+            a, b = 0, 1
+            for _ in range(attempt):
+                a, b = b, a + b
+            delay = self.base_delay * a
+        else:
+            delay = self.base_delay
+
+        # Cap at max delay
+        delay = min(delay, self.max_delay)
+
+        # Add jitter if configured (±25% random variation)
+        if self.jitter:
+            import random
+
+            jitter_factor = 0.75 + (random.random() * 0.5)
+            delay *= jitter_factor
+
+        return delay
+
+    def should_retry(self, error: Exception, attempt: int) -> bool:
+        """Determine if an error should be retried.
+
+        Args:
+            error: The exception that occurred.
+            attempt: Current attempt number (1-based).
+
+        Returns:
+            True if should retry, False otherwise.
+        """
+        # Check attempt limit
+        if attempt >= self.max_attempts:
+            return False
+
+        # Check error type if filter is configured
+        if self.retryable_errors is not None:
+            return isinstance(error, self.retryable_errors)
+
+        # Default to retry for any error
+        return True
+
+
+@define(kw_only=True, slots=True)
+class ErrorResponse:
+    """Structured error response for APIs and external interfaces.
+
+    Attributes:
+        error_code: Machine-readable error code.
+        message: Human-readable error message.
+        details: Optional additional error details.
+        metadata: Optional error metadata.
+        timestamp: When the error occurred.
+
+    Examples:
+        >>> response = ErrorResponse(
+        ...     error_code="VAL_001",
+        ...     message="Invalid email format",
+        ...     details={"field": "email", "value": "not-an-email"}
+        ... )
+    """
+
+    error_code: str
+    message: str
+    details: dict[str, Any] | None = None
+    metadata: ErrorMetadata | None = None
+    timestamp: str = field(factory=lambda: datetime.now().isoformat())
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization.
+
+        Returns:
+            Dictionary representation of error response.
+        """
+        result: dict[str, Any] = {
+            "error_code": self.error_code,
+            "message": self.message,
+            "timestamp": self.timestamp,
+        }
+
+        if self.details:
+            result["details"] = self.details
+
+        if self.metadata:
+            result["metadata"] = self.metadata.to_dict()
+
+        return result
+
+    def to_json(self) -> str:
+        """Convert to JSON string.
+
+        Returns:
+            JSON representation of error response.
+        """
+        import json
+
+        return json.dumps(self.to_dict(), indent=2)
+
+
+# Import datetime at module level for the factory
+from datetime import datetime