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

provide/foundation/errors/base.py

@@ -0,0 +1,81 @@
+"""Base exception class for Foundation."""
+
+from typing import Any
+
+
+class FoundationError(Exception):
+    """Base exception for all Foundation errors.
+
+    Args:
+        message: Human-readable error message.
+        code: Optional error code for programmatic handling.
+        context: Optional context dictionary with diagnostic data.
+        cause: Optional underlying exception that caused this error.
+        **extra_context: Additional key-value pairs added to context.
+
+    Examples:
+        >>> raise FoundationError("Operation failed")
+        >>> raise FoundationError("Operation failed", code="OP_001")
+        >>> raise FoundationError("Operation failed", user_id=123, retry_count=3)
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        context: dict[str, Any] | None = None,
+        cause: Exception | None = None,
+        **extra_context: Any,
+    ) -> None:
+        self.message = message
+        self.code = code or self._default_code()
+        self.context = context or {}
+        self.context.update(extra_context)
+        self.cause = cause
+        if cause:
+            self.__cause__ = cause
+        super().__init__(message)
+
+    def _default_code(self) -> str:
+        """Return default error code for this exception type."""
+        return "PROVIDE_ERROR"
+
+    def add_context(self, key: str, value: Any) -> "FoundationError":
+        """Add context data to the error.
+
+        Args:
+            key: Context key (use dots for namespacing, e.g., 'aws.region').
+            value: Context value.
+
+        Returns:
+            Self for method chaining.
+        """
+        self.context[key] = value
+        return self
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert exception to dictionary for structured logging.
+
+        Returns:
+            Dictionary representation suitable for logging/serialization.
+        """
+        result = {
+            "error.type": self.__class__.__name__,
+            "error.message": self.message,
+            "error.code": self.code,
+        }
+
+        # Add context with error prefix
+        for key, value in self.context.items():
+            # If key already has a prefix, use it; otherwise add error prefix
+            if "." in key:
+                result[key] = value
+            else:
+                result[f"error.{key}"] = value
+
+        if self.cause:
+            result["error.cause"] = str(self.cause)
+            result["error.cause_type"] = type(self.cause).__name__
+
+        return result

provide/foundation/errors/config.py

@@ -0,0 +1,103 @@
+"""Configuration-related exceptions."""
+
+from typing import Any
+
+from provide.foundation.errors.base import FoundationError
+
+
+class ConfigurationError(FoundationError):
+    """Raised when configuration is invalid or cannot be loaded.
+
+    Args:
+        message: Error message describing the configuration issue.
+        config_key: Optional configuration key that caused the error.
+        config_source: Optional source of the configuration (file, env, etc.).
+        **kwargs: Additional context passed to FoundationError.
+
+    Examples:
+        >>> raise ConfigurationError("Missing required config")
+        >>> raise ConfigurationError("Invalid timeout", config_key="timeout")
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        config_key: str | None = None,
+        config_source: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if config_key:
+            kwargs.setdefault("context", {})["config.key"] = config_key
+        if config_source:
+            kwargs.setdefault("context", {})["config.source"] = config_source
+        super().__init__(message, **kwargs)
+
+    def _default_code(self) -> str:
+        return "CONFIG_ERROR"
+
+
+class ValidationError(FoundationError):
+    """Raised when data validation fails.
+
+    Args:
+        message: Validation error message.
+        field: Optional field name that failed validation.
+        value: Optional invalid value.
+        rule: Optional validation rule that failed.
+        **kwargs: Additional context passed to FoundationError.
+
+    Examples:
+        >>> raise ValidationError("Invalid email format")
+        >>> raise ValidationError("Value out of range", field="age", value=-1)
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        field: str | None = None,
+        value: Any = None,
+        rule: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if field:
+            kwargs.setdefault("context", {})["validation.field"] = field
+        if value is not None:
+            kwargs.setdefault("context", {})["validation.value"] = str(value)
+        if rule:
+            kwargs.setdefault("context", {})["validation.rule"] = rule
+        super().__init__(message, **kwargs)
+
+    def _default_code(self) -> str:
+        return "VALIDATION_ERROR"
+
+
+class ConfigValidationError(ValidationError):
+    """Raised when configuration validation fails.
+
+    This is a specialized validation error for configuration-specific validation failures.
+
+    Args:
+        message: Validation error message.
+        config_class: Optional name of the config class.
+        **kwargs: Additional context passed to ValidationError.
+
+    Examples:
+        >>> raise ConfigValidationError("Invalid database configuration")
+        >>> raise ConfigValidationError("Port must be positive", field="port", value=-1)
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        config_class: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if config_class:
+            kwargs.setdefault("context", {})["config.class"] = config_class
+        super().__init__(message, **kwargs)
+
+    def _default_code(self) -> str:
+        return "CONFIG_VALIDATION_ERROR"

provide/foundation/errors/context.py

@@ -0,0 +1,299 @@
+"""Error context management for rich diagnostic information.
+
+Provides structured context for errors that can be used for logging,
+monitoring, and diagnostic purposes.
+"""
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from attrs import define, field
+
+
+class ErrorSeverity(str, Enum):
+    """Error severity levels for prioritization and alerting."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+class ErrorCategory(str, Enum):
+    """Error categorization for routing and handling."""
+
+    USER = "user"  # User error (bad input, etc.)
+    SYSTEM = "system"  # System/infrastructure error
+    EXTERNAL = "external"  # External service error
+
+
+@define(kw_only=True, slots=True)
+class ErrorContext:
+    """Rich error context for diagnostics and monitoring.
+
+    Provides a flexible container for error metadata that can be used
+    by different systems (logging, monitoring, Terraform, etc.).
+
+    Attributes:
+        timestamp: When the error occurred.
+        severity: Error severity level.
+        category: Error category for classification.
+        metadata: Namespace-based metadata storage.
+        tags: Set of tags for categorization and filtering.
+        trace_id: Optional trace ID for distributed tracing.
+        span_id: Optional span ID for distributed tracing.
+
+    Examples:
+        >>> ctx = ErrorContext(severity=ErrorSeverity.HIGH)
+        >>> ctx.add_namespace("aws", {"region": "us-east-1", "account": "123456"})
+        >>> ctx.add_tag("production")
+    """
+
+    timestamp: datetime = field(factory=datetime.now)
+    severity: ErrorSeverity = ErrorSeverity.MEDIUM
+    category: ErrorCategory = ErrorCategory.SYSTEM
+    metadata: dict[str, dict[str, Any]] = field(factory=lambda: {})
+    tags: set[str] = field(factory=set)
+    trace_id: str | None = None
+    span_id: str | None = None
+
+    def add_namespace(self, namespace: str, data: dict[str, Any]) -> "ErrorContext":
+        """Add namespaced metadata.
+
+        Args:
+            namespace: Namespace key (e.g., 'terraform', 'aws', 'http').
+            data: Metadata for this namespace.
+
+        Returns:
+            Self for method chaining.
+
+        Examples:
+            >>> ctx.add_namespace("terraform", {"provider": "aws", "version": "5.0"})
+            >>> ctx.add_namespace("http", {"method": "POST", "status": 500})
+        """
+        self.metadata[namespace] = data
+        return self
+
+    def update_namespace(self, namespace: str, data: dict[str, Any]) -> "ErrorContext":
+        """Update existing namespace metadata.
+
+        Args:
+            namespace: Namespace key to update.
+            data: Metadata to merge into namespace.
+
+        Returns:
+            Self for method chaining.
+        """
+        if namespace not in self.metadata:
+            self.metadata[namespace] = {}
+        self.metadata[namespace].update(data)
+        return self
+
+    def get_namespace(self, namespace: str) -> dict[str, Any] | None:
+        """Get metadata for a specific namespace.
+
+        Args:
+            namespace: Namespace key to retrieve.
+
+        Returns:
+            Namespace metadata or None if not found.
+        """
+        return self.metadata.get(namespace)
+
+    def add_tag(self, tag: str) -> "ErrorContext":
+        """Add a tag for categorization.
+
+        Args:
+            tag: Tag to add.
+
+        Returns:
+            Self for method chaining.
+        """
+        self.tags.add(tag)
+        return self
+
+    def add_tags(self, *tags: str) -> "ErrorContext":
+        """Add multiple tags.
+
+        Args:
+            *tags: Tags to add.
+
+        Returns:
+            Self for method chaining.
+        """
+        self.tags.update(tags)
+        return self
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for logging and serialization.
+
+        Returns:
+            Flattened dictionary with namespaced keys.
+
+        Examples:
+            >>> ctx.to_dict()
+            {'timestamp': '2024-01-01T12:00:00', 'severity': 'high', ...}
+        """
+        result: dict[str, Any] = {
+            "timestamp": self.timestamp.isoformat(),
+            "severity": self.severity.value,
+            "category": self.category.value,
+        }
+
+        # Add tracing if present
+        if self.trace_id:
+            result["trace_id"] = self.trace_id
+        if self.span_id:
+            result["span_id"] = self.span_id
+
+        # Flatten namespaced metadata
+        for namespace, data in self.metadata.items():
+            for key, value in data.items():
+                result[f"{namespace}.{key}"] = value
+
+        # Add tags if present
+        if self.tags:
+            result["tags"] = sorted(list(self.tags))
+
+        return result
+
+    def to_logging_context(self) -> dict[str, Any]:
+        """Convert to context suitable for structured logging.
+
+        Returns:
+            Dictionary formatted for logger context.
+        """
+        return self.to_dict()
+
+    def to_terraform_diagnostic(self) -> dict[str, Any]:
+        """Convert to Terraform diagnostic format.
+
+        Returns:
+            Dictionary formatted for Terraform diagnostics.
+
+        Examples:
+            >>> ctx.to_terraform_diagnostic()
+            {'severity': 'error', 'summary': '...', 'detail': {...}}
+        """
+        # Map our severity to Terraform severity
+        severity_map = {
+            ErrorSeverity.LOW: "warning",
+            ErrorSeverity.MEDIUM: "warning",
+            ErrorSeverity.HIGH: "error",
+            ErrorSeverity.CRITICAL: "error",
+        }
+
+        diagnostic: dict[str, Any] = {
+            "severity": severity_map[self.severity],
+            "detail": {},
+        }
+
+        # Add Terraform-specific metadata if present
+        tf_meta = self.get_namespace("terraform")
+        if tf_meta:
+            diagnostic["detail"].update(tf_meta)
+
+        # Add other relevant metadata
+        for namespace, data in self.metadata.items():
+            if namespace != "terraform":
+                diagnostic["detail"][namespace] = data
+
+        return diagnostic
+
+
+def capture_error_context(
+    error: Exception,
+    severity: ErrorSeverity | None = None,
+    category: ErrorCategory | None = None,
+    **namespaces: dict[str, Any],
+) -> ErrorContext:
+    """Capture error context from an exception.
+
+    Args:
+        error: Exception to capture context from.
+        severity: Optional severity override.
+        category: Optional category override.
+        **namespaces: Namespace data to add to context.
+
+    Returns:
+        ErrorContext with captured information.
+
+    Examples:
+        >>> try:
+        ...     risky_operation()
+        ... except Exception as e:
+        ...     ctx = capture_error_context(
+        ...         e,
+        ...         severity=ErrorSeverity.HIGH,
+        ...         aws={"region": "us-east-1"},
+        ...         http={"status": 500}
+        ...     )
+    """
+    # Determine severity based on error type if not provided
+    if severity is None:
+        if isinstance(error, AssertionError | ValueError | TypeError):
+            severity = ErrorSeverity.MEDIUM
+        elif isinstance(error, KeyError | IndexError | AttributeError):
+            severity = ErrorSeverity.LOW
+        else:
+            severity = ErrorSeverity.HIGH
+
+    # Determine category based on error type if not provided
+    if category is None:
+        # Import here to avoid circular dependency
+        from provide.foundation.errors.auth import (
+            AuthenticationError,
+            AuthorizationError,
+        )
+        from provide.foundation.errors.config import ValidationError
+        from provide.foundation.errors.integration import IntegrationError, NetworkError
+
+        if isinstance(
+            error, ValidationError | AuthenticationError | AuthorizationError
+        ):
+            category = ErrorCategory.USER
+        elif isinstance(error, IntegrationError | NetworkError):
+            category = ErrorCategory.EXTERNAL
+        else:
+            category = ErrorCategory.SYSTEM
+
+    # Create context
+    ctx = ErrorContext(severity=severity, category=category)
+
+    # Add error details
+    ctx.add_namespace(
+        "error",
+        {
+            "type": type(error).__name__,
+            "message": str(error),
+        },
+    )
+
+    # Add any namespaces provided
+    for namespace, data in namespaces.items():
+        ctx.add_namespace(namespace, data)
+
+    # Add context from FoundationError if applicable
+    from provide.foundation.errors.base import FoundationError
+
+    if isinstance(error, FoundationError) and error.context:
+        # Group context items by namespace
+        grouped: dict[str, dict[str, Any]] = {}
+        for key, value in error.context.items():
+            if "." in key:
+                namespace, subkey = key.split(".", 1)
+                if namespace not in grouped:
+                    grouped[namespace] = {}
+                grouped[namespace][subkey] = value
+            else:
+                # Put non-namespaced items in 'context' namespace
+                if "context" not in grouped:
+                    grouped["context"] = {}
+                grouped["context"][key] = value
+
+        # Add grouped context to error context
+        for namespace, data in grouped.items():
+            ctx.update_namespace(namespace, data)
+
+    return ctx