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

provide/foundation/resilience/fallback.py

@@ -0,0 +1,193 @@
+"""
+Fallback implementation for graceful degradation.
+"""
+
+import asyncio
+import functools
+from typing import Any, 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,325 @@
+"""
+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
+import random
+import time
+from enum import Enum
+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, value):
+        """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, value):
+        """Validate base_delay is positive."""
+        if value < 0:
+            raise ValueError("base_delay must be positive")
+    
+    @max_delay.validator
+    def _validate_max_delay(self, attribute, value):
+        """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/streams/config.py

@@ -0,0 +1,79 @@
+"""
+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.env import RuntimeConfig
+from provide.foundation.config.base import field
+from provide.foundation.config.converters import parse_bool_extended
+
+
+@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

provide/foundation/streams/console.py

@@ -9,6 +9,7 @@ Handles console-specific stream operations and formatting.
 import sys
 from typing import TextIO
 
+from provide.foundation.streams.config import get_stream_config
 from provide.foundation.streams.core import get_log_stream
 
 
@@ -25,16 +26,14 @@ def is_tty() -> bool:
 
 def supports_color() -> bool:
     """Check if the current stream supports color output."""
-    import os
-
-    # Check NO_COLOR environment variable
-    if os.getenv("NO_COLOR"):
+    config = get_stream_config()
+    
+    if config.no_color:
         return False
-
-    # Check FORCE_COLOR environment variable
-    if os.getenv("FORCE_COLOR"):
+    
+    if config.force_color:
         return True
-
+    
     # Check if we're in a TTY
     return is_tty()
 

provide/foundation/streams/core.py

@@ -10,6 +10,8 @@ import sys
 import threading
 from typing import TextIO
 
+from provide.foundation.streams.config import get_stream_config
+
 _PROVIDE_LOG_STREAM: TextIO = sys.stderr
 _LOG_FILE_HANDLE: TextIO | None = None
 _STREAM_LOCK = threading.Lock()
@@ -18,10 +20,11 @@ _STREAM_LOCK = threading.Lock()
 def _is_in_click_testing() -> bool:
     """Check if we're running inside Click's testing framework."""
     import inspect
-    import os
-
+    
+    config = get_stream_config()
+    
     # Check environment variables for Click testing
-    if os.getenv("CLICK_TESTING"):
+    if config.click_testing:
         return True
 
     # Check the call stack for Click's testing module or CLI integration tests

provide/foundation/streams/file.py

@@ -18,6 +18,16 @@ from provide.foundation.streams.core import (
 from provide.foundation.utils.streams import get_safe_stderr
 
 
+def _safe_error_output(message: str) -> None:
+    """
+    Output error message to stderr using basic print to avoid circular dependencies.
+    
+    This function intentionally uses print() instead of Foundation's perr() to prevent
+    circular import issues during stream initialization and teardown phases.
+    """
+    print(message, file=sys.stderr)
+
+
 def configure_file_logging(log_file_path: str | None) -> None:
     """
     Configure file logging if a path is provided.
@@ -56,7 +66,7 @@ def configure_file_logging(log_file_path: str | None) -> None:
                 _PROVIDE_LOG_STREAM = _LOG_FILE_HANDLE
             except Exception as e:
                 # Log error to stderr and fall back
-                print(f"Failed to open log file {log_file_path}: {e}", file=sys.stderr)
+                _safe_error_output(f"Failed to open log file {log_file_path}: {e}")
                 _PROVIDE_LOG_STREAM = get_safe_stderr()
         elif not is_test_stream:
             _PROVIDE_LOG_STREAM = get_safe_stderr()
@@ -71,7 +81,7 @@ def flush_log_streams() -> None:
             try:
                 _LOG_FILE_HANDLE.flush()
             except Exception as e:
-                print(f"Failed to flush log file handle: {e}", file=sys.stderr)
+                _safe_error_output(f"Failed to flush log file handle: {e}")
 
 
 def close_log_streams() -> None: