provide-foundation 0.0.0.dev1__py3-none-any.whl → 0.0.0.dev3__py3-none-any.whl

provide/foundation/resilience/fallback.py

@@ -0,0 +1,208 @@
+"""
+Fallback implementation for graceful degradation.
+"""
+
+import asyncio
+import functools
+from typing import Callable, TypeVar
+
+from attrs import define, field
+
+from provide.foundation.logger import logger
+
+T = TypeVar("T")
+
+
+@define(kw_only=True, slots=True)
+class FallbackChain:
+    """Chain of fallback strategies for graceful degradation.
+
+    Executes fallback functions in order when primary function fails.
+    """
+
+    fallbacks: list[Callable[..., T]] = field(factory=list)
+    expected_exceptions: tuple[type[Exception], ...] = field(
+        factory=lambda: (Exception,)
+    )
+
+    def add_fallback(self, fallback_func: Callable[..., T]) -> None:
+        """Add a fallback function to the chain."""
+        self.fallbacks.append(fallback_func)
+        logger.debug(
+            "Added fallback to chain",
+            fallback_count=len(self.fallbacks),
+            fallback_name=getattr(fallback_func, "__name__", "anonymous"),
+        )
+
+    def execute(self, primary_func: Callable[..., T], *args, **kwargs) -> T:
+        """Execute primary function with fallback chain (sync)."""
+        # Try primary function first
+        primary_exception = None
+        try:
+            result = primary_func(*args, **kwargs)
+            logger.trace(
+                "Primary function succeeded",
+                func=getattr(primary_func, "__name__", "anonymous"),
+            )
+            return result
+        except Exception as e:
+            primary_exception = e
+            if not isinstance(e, self.expected_exceptions):
+                # Unexpected exception type, don't use fallbacks
+                logger.debug(
+                    "Primary function failed with unexpected exception type",
+                    exception_type=type(e).__name__,
+                    expected_types=[t.__name__ for t in self.expected_exceptions],
+                )
+                raise
+
+            logger.warning(
+                "Primary function failed, trying fallbacks",
+                func=getattr(primary_func, "__name__", "anonymous"),
+                error=str(e),
+                fallback_count=len(self.fallbacks),
+            )
+
+        # Try fallbacks in order
+        last_exception = None
+        for i, fallback_func in enumerate(self.fallbacks):
+            try:
+                result = fallback_func(*args, **kwargs)
+                logger.info(
+                    "Fallback succeeded",
+                    fallback_index=i,
+                    fallback_name=getattr(fallback_func, "__name__", "anonymous"),
+                )
+                return result
+            except Exception as e:
+                last_exception = e
+                logger.warning(
+                    "Fallback failed",
+                    fallback_index=i,
+                    fallback_name=getattr(fallback_func, "__name__", "anonymous"),
+                    error=str(e),
+                )
+                continue
+
+        # All fallbacks failed
+        logger.error(
+            "All fallbacks exhausted",
+            primary_func=getattr(primary_func, "__name__", "anonymous"),
+            fallback_count=len(self.fallbacks),
+        )
+
+        # Raise the last exception from fallbacks, or original if no fallbacks
+        if last_exception is not None:
+            raise last_exception
+        if primary_exception is not None:
+            raise primary_exception
+        # This should never happen but provide fallback
+        raise RuntimeError(
+            "Fallback chain execution failed with no recorded exceptions"
+        )
+
+    async def execute_async(self, primary_func: Callable[..., T], *args, **kwargs) -> T:
+        """Execute primary function with fallback chain (async)."""
+        # Try primary function first
+        primary_exception = None
+        try:
+            if asyncio.iscoroutinefunction(primary_func):
+                result = await primary_func(*args, **kwargs)
+            else:
+                result = primary_func(*args, **kwargs)
+            logger.trace(
+                "Primary function succeeded",
+                func=getattr(primary_func, "__name__", "anonymous"),
+            )
+            return result
+        except Exception as e:
+            primary_exception = e
+            if not isinstance(e, self.expected_exceptions):
+                # Unexpected exception type, don't use fallbacks
+                logger.debug(
+                    "Primary function failed with unexpected exception type",
+                    exception_type=type(e).__name__,
+                    expected_types=[t.__name__ for t in self.expected_exceptions],
+                )
+                raise
+
+            logger.warning(
+                "Primary function failed, trying fallbacks",
+                func=getattr(primary_func, "__name__", "anonymous"),
+                error=str(e),
+                fallback_count=len(self.fallbacks),
+            )
+
+        # Try fallbacks in order
+        last_exception = None
+        for i, fallback_func in enumerate(self.fallbacks):
+            try:
+                if asyncio.iscoroutinefunction(fallback_func):
+                    result = await fallback_func(*args, **kwargs)
+                else:
+                    result = fallback_func(*args, **kwargs)
+                logger.info(
+                    "Fallback succeeded",
+                    fallback_index=i,
+                    fallback_name=getattr(fallback_func, "__name__", "anonymous"),
+                )
+                return result
+            except Exception as e:
+                last_exception = e
+                logger.warning(
+                    "Fallback failed",
+                    fallback_index=i,
+                    fallback_name=getattr(fallback_func, "__name__", "anonymous"),
+                    error=str(e),
+                )
+                continue
+
+        # All fallbacks failed
+        logger.error(
+            "All fallbacks exhausted",
+            primary_func=getattr(primary_func, "__name__", "anonymous"),
+            fallback_count=len(self.fallbacks),
+        )
+
+        # Raise the last exception from fallbacks, or original if no fallbacks
+        if last_exception is not None:
+            raise last_exception
+        if primary_exception is not None:
+            raise primary_exception
+        # This should never happen but provide fallback
+        raise RuntimeError(
+            "Fallback chain execution failed with no recorded exceptions"
+        )
+
+
+def fallback(*fallback_funcs: Callable[..., T]) -> Callable:
+    """Decorator to add fallback functions to a primary function.
+
+    Args:
+        *fallback_funcs: Functions to use as fallbacks, in order of preference
+
+    Returns:
+        Decorated function that uses fallback chain
+    """
+
+    def decorator(primary_func: Callable[..., T]) -> Callable[..., T]:
+        chain = FallbackChain()
+        for fallback_func in fallback_funcs:
+            chain.add_fallback(fallback_func)
+
+        if asyncio.iscoroutinefunction(primary_func):
+
+            @functools.wraps(primary_func)
+            async def async_wrapper(*args, **kwargs):
+                return await chain.execute_async(primary_func, *args, **kwargs)
+
+            return async_wrapper
+        else:
+
+            @functools.wraps(primary_func)
+            def sync_wrapper(*args, **kwargs):
+                return chain.execute(primary_func, *args, **kwargs)
+
+            return sync_wrapper
+
+    return decorator

provide/foundation/resilience/retry.py

@@ -0,0 +1,327 @@
+"""
+Unified retry execution engine and policy configuration.
+
+This module provides the core retry functionality used throughout foundation,
+eliminating duplication between decorators and middleware.
+"""
+
+import asyncio
+from enum import Enum
+import random
+import time
+from typing import Any, Callable, TypeVar
+
+from attrs import define, field, validators
+
+from provide.foundation.logger import get_logger
+
+logger = get_logger(__name__)
+
+T = TypeVar("T")
+
+
+class BackoffStrategy(str, Enum):
+    """Backoff strategies for retry delays."""
+
+    FIXED = "fixed"  # Same delay every time
+    LINEAR = "linear"  # Linear increase (delay * attempt)
+    EXPONENTIAL = "exponential"  # Exponential increase (delay * 2^attempt)
+    FIBONACCI = "fibonacci"  # Fibonacci sequence delays
+
+
+@define(frozen=True, kw_only=True)
+class RetryPolicy:
+    """
+    Configuration for retry behavior.
+
+    This policy can be used with both the @retry decorator and transport middleware,
+    providing a unified configuration model for all retry scenarios.
+
+    Attributes:
+        max_attempts: Maximum number of retry attempts (must be >= 1)
+        backoff: Backoff strategy to use for delays
+        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 (±25%)
+        retryable_errors: Tuple of exception types to retry (None = all)
+        retryable_status_codes: Set of HTTP status codes to retry (for middleware)
+    """
+
+    max_attempts: int = field(default=3, validator=validators.instance_of(int))
+    backoff: BackoffStrategy = field(default=BackoffStrategy.EXPONENTIAL)
+    base_delay: float = field(
+        default=1.0, validator=validators.instance_of((int, float))
+    )
+    max_delay: float = field(
+        default=60.0, validator=validators.instance_of((int, float))
+    )
+    jitter: bool = field(default=True)
+    retryable_errors: tuple[type[Exception], ...] | None = field(default=None)
+    retryable_status_codes: set[int] | None = field(default=None)
+
+    @max_attempts.validator
+    def _validate_max_attempts(self, attribute: object, value: int) -> None:
+        """Validate max_attempts is at least 1."""
+        if value < 1:
+            raise ValueError("max_attempts must be at least 1")
+
+    @base_delay.validator
+    def _validate_base_delay(self, attribute: object, value: float) -> None:
+        """Validate base_delay is positive."""
+        if value < 0:
+            raise ValueError("base_delay must be positive")
+
+    @max_delay.validator
+    def _validate_max_delay(self, attribute: object, value: float) -> None:
+        """Validate max_delay is positive and >= base_delay."""
+        if value < 0:
+            raise ValueError("max_delay must be positive")
+        if value < self.base_delay:
+            raise ValueError("max_delay must be >= base_delay")
+
+    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:
+            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
+
+    def should_retry_response(self, response: Any, attempt: int) -> bool:
+        """
+        Check if HTTP response should be retried.
+
+        Args:
+            response: Response object with status attribute
+            attempt: Current attempt number (1-based)
+
+        Returns:
+            True if should retry, False otherwise
+        """
+        # Check attempt limit
+        if attempt >= self.max_attempts:
+            return False
+
+        # Check status code if configured
+        if self.retryable_status_codes is not None:
+            return getattr(response, "status", None) in self.retryable_status_codes
+
+        # Default to no retry for responses
+        return False
+
+    def __str__(self) -> str:
+        """Human-readable string representation."""
+        return (
+            f"RetryPolicy(max_attempts={self.max_attempts}, "
+            f"backoff={self.backoff.value}, base_delay={self.base_delay}s)"
+        )
+
+
+class RetryExecutor:
+    """
+    Unified retry execution engine.
+
+    This executor handles the actual retry loop logic for both sync and async
+    functions, using a RetryPolicy for configuration. It's used internally by
+    both the @retry decorator and RetryMiddleware.
+    """
+
+    def __init__(
+        self,
+        policy: RetryPolicy,
+        on_retry: Callable[[int, Exception], None] | None = None,
+    ):
+        """
+        Initialize retry executor.
+
+        Args:
+            policy: Retry policy configuration
+            on_retry: Optional callback for retry events (attempt, error)
+        """
+        self.policy = policy
+        self.on_retry = on_retry
+
+    def execute_sync(self, func: Callable[..., T], *args, **kwargs) -> T:
+        """
+        Execute synchronous function with retry logic.
+
+        Args:
+            func: Function to execute
+            *args: Positional arguments for func
+            **kwargs: Keyword arguments for func
+
+        Returns:
+            Result from successful execution
+
+        Raises:
+            Last exception if all retries are exhausted
+        """
+        last_exception = None
+
+        for attempt in range(1, self.policy.max_attempts + 1):
+            try:
+                return func(*args, **kwargs)
+            except Exception as e:
+                last_exception = e
+
+                # Don't retry on last attempt - log and raise
+                if attempt >= self.policy.max_attempts:
+                    logger.error(
+                        f"All {self.policy.max_attempts} retry attempts failed",
+                        attempts=self.policy.max_attempts,
+                        error=str(e),
+                        error_type=type(e).__name__,
+                    )
+                    raise
+
+                # Check if we should retry this error
+                if not self.policy.should_retry(e, attempt):
+                    raise
+
+                # Calculate delay
+                delay = self.policy.calculate_delay(attempt)
+
+                # Log retry attempt
+                logger.info(
+                    f"Retry {attempt}/{self.policy.max_attempts} after {delay:.2f}s",
+                    attempt=attempt,
+                    max_attempts=self.policy.max_attempts,
+                    delay=delay,
+                    error=str(e),
+                    error_type=type(e).__name__,
+                )
+
+                # Call retry callback if provided
+                if self.on_retry:
+                    try:
+                        self.on_retry(attempt, e)
+                    except Exception as callback_error:
+                        logger.warning(
+                            "Retry callback failed", error=str(callback_error)
+                        )
+
+                # Wait before retry
+                time.sleep(delay)
+
+        # Should never reach here, but for safety
+        raise last_exception
+
+    async def execute_async(self, func: Callable[..., T], *args, **kwargs) -> T:
+        """
+        Execute asynchronous function with retry logic.
+
+        Args:
+            func: Async function to execute
+            *args: Positional arguments for func
+            **kwargs: Keyword arguments for func
+
+        Returns:
+            Result from successful execution
+
+        Raises:
+            Last exception if all retries are exhausted
+        """
+        last_exception = None
+
+        for attempt in range(1, self.policy.max_attempts + 1):
+            try:
+                return await func(*args, **kwargs)
+            except Exception as e:
+                last_exception = e
+
+                # Don't retry on last attempt - log and raise
+                if attempt >= self.policy.max_attempts:
+                    logger.error(
+                        f"All {self.policy.max_attempts} retry attempts failed",
+                        attempts=self.policy.max_attempts,
+                        error=str(e),
+                        error_type=type(e).__name__,
+                    )
+                    raise
+
+                # Check if we should retry this error
+                if not self.policy.should_retry(e, attempt):
+                    raise
+
+                # Calculate delay
+                delay = self.policy.calculate_delay(attempt)
+
+                # Log retry attempt
+                logger.info(
+                    f"Retry {attempt}/{self.policy.max_attempts} after {delay:.2f}s",
+                    attempt=attempt,
+                    max_attempts=self.policy.max_attempts,
+                    delay=delay,
+                    error=str(e),
+                    error_type=type(e).__name__,
+                )
+
+                # Call retry callback if provided
+                if self.on_retry:
+                    try:
+                        if asyncio.iscoroutinefunction(self.on_retry):
+                            await self.on_retry(attempt, e)
+                        else:
+                            self.on_retry(attempt, e)
+                    except Exception as callback_error:
+                        logger.warning(
+                            "Retry callback failed", error=str(callback_error)
+                        )
+
+                # Wait before retry
+                await asyncio.sleep(delay)
+
+        # Should never reach here, but for safety
+        raise last_exception

provide/foundation/serialization/__init__.py

@@ -0,0 +1,16 @@
+"""
+Serialization utilities for Foundation.
+
+Provides consistent serialization handling with validation,
+testing support, and integration with Foundation's configuration system.
+"""
+
+from provide.foundation.serialization.core import (
+    provide_dumps,
+    provide_loads,
+)
+
+__all__ = [
+    "provide_dumps",
+    "provide_loads",
+]

provide/foundation/serialization/core.py

@@ -0,0 +1,70 @@
+"""Core serialization utilities for Foundation."""
+
+import json
+from typing import Any
+
+from provide.foundation.errors import ValidationError
+
+
+def provide_dumps(
+    obj: Any,
+    *,
+    ensure_ascii: bool = False,
+    indent: int | None = None,
+    sort_keys: bool = False,
+) -> str:
+    """
+    Serialize object to JSON string with Foundation tracking.
+
+    Args:
+        obj: Object to serialize
+        ensure_ascii: If True, non-ASCII characters are escaped
+        indent: Number of spaces for indentation (None for compact)
+        sort_keys: Whether to sort dictionary keys
+
+    Returns:
+        JSON string representation
+
+    Raises:
+        ValidationError: If object cannot be serialized
+
+    Example:
+        >>> provide_dumps({"key": "value"})
+        '{"key": "value"}'
+        >>> provide_dumps({"b": 1, "a": 2}, sort_keys=True, indent=2)
+        '{\\n  "a": 2,\\n  "b": 1\\n}'
+    """
+    try:
+        return json.dumps(
+            obj, ensure_ascii=ensure_ascii, indent=indent, sort_keys=sort_keys
+        )
+    except (TypeError, ValueError) as e:
+        raise ValidationError(f"Cannot serialize object to JSON: {e}") from e
+
+
+def provide_loads(s: str) -> Any:
+    """
+    Deserialize JSON string to Python object with Foundation tracking.
+
+    Args:
+        s: JSON string to deserialize
+
+    Returns:
+        Deserialized Python object
+
+    Raises:
+        ValidationError: If string is not valid JSON
+
+    Example:
+        >>> provide_loads('{"key": "value"}')
+        {'key': 'value'}
+        >>> provide_loads('[1, 2, 3]')
+        [1, 2, 3]
+    """
+    if not isinstance(s, str):
+        raise ValidationError("Input must be a string")
+
+    try:
+        return json.loads(s)
+    except json.JSONDecodeError as e:
+        raise ValidationError(f"Invalid JSON string: {e}") from e

provide/foundation/streams/config.py

@@ -0,0 +1,78 @@
+"""
+Stream configuration for console output settings.
+
+This module provides configuration for console stream behavior,
+including color support and testing mode detection.
+"""
+
+from attrs import define
+
+from provide.foundation.config.base import field
+from provide.foundation.config.converters import parse_bool_extended
+from provide.foundation.config.env import RuntimeConfig
+
+
+@define(slots=True, repr=False)
+class StreamConfig(RuntimeConfig):
+    """Configuration for console stream output behavior."""
+
+    no_color: bool = field(
+        default=False,
+        env_var="NO_COLOR",
+        converter=parse_bool_extended,
+        description="Disable color output in console",
+    )
+
+    force_color: bool = field(
+        default=False,
+        env_var="FORCE_COLOR",
+        converter=parse_bool_extended,
+        description="Force color output even when not in TTY",
+    )
+
+    click_testing: bool = field(
+        default=False,
+        env_var="CLICK_TESTING",
+        converter=parse_bool_extended,
+        description="Indicates if running inside Click testing framework",
+    )
+
+    def supports_color(self) -> bool:
+        """
+        Determine if the console supports color output.
+
+        Returns:
+            True if color is supported, False otherwise
+        """
+        if self.no_color:
+            return False
+
+        if self.force_color:
+            return True
+
+        # Additional logic for TTY detection would go here
+        # For now, just return based on the flags
+        return not self.no_color
+
+
+# Global instance for easy access
+_stream_config: StreamConfig | None = None
+
+
+def get_stream_config() -> StreamConfig:
+    """
+    Get the global stream configuration instance.
+
+    Returns:
+        StreamConfig instance loaded from environment
+    """
+    global _stream_config
+    if _stream_config is None:
+        _stream_config = StreamConfig.from_env()
+    return _stream_config
+
+
+def reset_stream_config() -> None:
+    """Reset the global stream configuration (mainly for testing)."""
+    global _stream_config
+    _stream_config = None