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

provide/foundation/resilience/decorators.py

@@ -0,0 +1,220 @@
+"""
+Resilience decorators for retry, circuit breaker, and fallback patterns.
+"""
+
+import asyncio
+import functools
+import time
+from typing import Any, Callable, TypeVar
+
+from attrs import define, field
+
+from provide.foundation.config.defaults import DEFAULT_CIRCUIT_BREAKER_RECOVERY_TIMEOUT
+from provide.foundation.resilience.retry import BackoffStrategy, RetryExecutor, RetryPolicy
+
+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 retry(
+    *exceptions: type[Exception],
+    policy: RetryPolicy | None = None,
+    max_attempts: int | None = None,
+    base_delay: float | None = None,
+    backoff: BackoffStrategy | None = None,
+    max_delay: float | None = None,
+    jitter: bool | None = None,
+    on_retry: Callable[[int, Exception], None] | None = None,
+) -> Callable[[F], F]:
+    """
+    Decorator for retrying operations on errors.
+    
+    Can be used in multiple ways:
+    
+    1. With a policy object:
+        @retry(policy=RetryPolicy(max_attempts=5))
+        
+    2. With individual parameters:
+        @retry(max_attempts=3, base_delay=1.0)
+        
+    3. With specific exceptions:
+        @retry(ConnectionError, TimeoutError, max_attempts=3)
+        
+    4. Without parentheses (uses defaults):
+        @retry
+        def my_func(): ...
+    
+    Args:
+        *exceptions: Exception types to retry (all if empty)
+        policy: Complete retry policy (overrides other params)
+        max_attempts: Maximum retry attempts
+        base_delay: Base delay between retries
+        backoff: Backoff strategy
+        max_delay: Maximum delay cap
+        jitter: Whether to add jitter
+        on_retry: Callback for retry events
+    
+    Returns:
+        Decorated function with retry logic
+        
+    Examples:
+        >>> @retry(max_attempts=3)
+        ... def flaky_operation():
+        ...     # May fail occasionally
+        ...     pass
+        
+        >>> @retry(ConnectionError, max_attempts=5, base_delay=2.0)
+        ... async def connect_to_service():
+        ...     # Async function with specific error handling
+        ...     pass
+    """
+    # Handle decorator without parentheses
+    if len(exceptions) == 1 and callable(exceptions[0]) and not isinstance(exceptions[0], type):
+        # Called as @retry without parentheses
+        func = exceptions[0]
+        executor = RetryExecutor(RetryPolicy())
+        
+        if asyncio.iscoroutinefunction(func):
+            @functools.wraps(func)
+            async def async_wrapper(*args, **kwargs):
+                return await executor.execute_async(func, *args, **kwargs)
+            return async_wrapper
+        else:
+            @functools.wraps(func)
+            def sync_wrapper(*args, **kwargs):
+                return executor.execute_sync(func, *args, **kwargs)
+            return sync_wrapper
+    
+    # Build policy if not provided
+    if policy is not None and any(
+        p is not None for p in [max_attempts, base_delay, backoff, max_delay, jitter]
+    ):
+        raise ValueError(
+            "Cannot specify both policy and individual retry parameters"
+        )
+    
+    if policy is None:
+        # Build policy from parameters
+        policy_kwargs = {}
+        
+        if max_attempts is not None:
+            policy_kwargs['max_attempts'] = max_attempts
+        if base_delay is not None:
+            policy_kwargs['base_delay'] = base_delay
+        if backoff is not None:
+            policy_kwargs['backoff'] = backoff
+        if max_delay is not None:
+            policy_kwargs['max_delay'] = max_delay
+        if jitter is not None:
+            policy_kwargs['jitter'] = jitter
+        if exceptions:
+            policy_kwargs['retryable_errors'] = exceptions
+        
+        policy = RetryPolicy(**policy_kwargs)
+    
+    def decorator(func: F) -> F:
+        executor = RetryExecutor(policy, on_retry=on_retry)
+        
+        if asyncio.iscoroutinefunction(func):
+            @functools.wraps(func)
+            async def async_wrapper(*args, **kwargs):
+                return await executor.execute_async(func, *args, **kwargs)
+            return async_wrapper
+        else:
+            @functools.wraps(func)
+            def sync_wrapper(*args, **kwargs):
+                return executor.execute_sync(func, *args, **kwargs)
+            return sync_wrapper
+    
+    return decorator
+
+
+# Import CircuitBreaker from circuit module
+from provide.foundation.resilience.circuit import CircuitBreaker
+
+
+def circuit_breaker(
+    failure_threshold: int = 5,
+    recovery_timeout: float = DEFAULT_CIRCUIT_BREAKER_RECOVERY_TIMEOUT,
+    expected_exception: tuple[type[Exception], ...] = (Exception,),
+) -> Callable[[F], F]:
+    """Create a circuit breaker decorator.
+
+    Args:
+        failure_threshold: Number of failures before opening circuit.
+        recovery_timeout: Seconds to wait before attempting recovery.
+        expected_exception: Exception types that trigger the breaker.
+
+    Returns:
+        Circuit breaker decorator.
+
+    Examples:
+        >>> @circuit_breaker(failure_threshold=3, recovery_timeout=30)
+        ... def unreliable_service():
+        ...     return external_api_call()
+    """
+    breaker = CircuitBreaker(
+        failure_threshold=failure_threshold,
+        recovery_timeout=recovery_timeout,
+        expected_exception=expected_exception,
+    )
+    
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            return breaker.call(func, *args, **kwargs)
+        
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            return await breaker.call_async(func, *args, **kwargs)
+        
+        if asyncio.iscoroutinefunction(func):
+            return async_wrapper  # type: ignore
+        else:
+            return sync_wrapper  # type: ignore
+    
+    return decorator
+
+
+def fallback(*fallback_funcs: Callable[..., Any]) -> Callable[[F], F]:
+    """
+    Fallback decorator using FallbackChain.
+    
+    Args:
+        *fallback_funcs: Functions to use as fallbacks, in order of preference
+    
+    Returns:
+        Decorated function with fallback chain
+        
+    Examples:
+        >>> def backup_api():
+        ...     return "backup result"
+        ...
+        >>> @fallback(backup_api)
+        ... def primary_api():
+        ...     return external_api_call()
+    """
+    from provide.foundation.resilience.fallback import FallbackChain
+    
+    def decorator(func: F) -> F:
+        chain = FallbackChain()
+        for fallback_func in fallback_funcs:
+            chain.add_fallback(fallback_func)
+        
+        if asyncio.iscoroutinefunction(func):
+            @functools.wraps(func)
+            async def async_wrapper(*args, **kwargs):
+                return await chain.execute_async(func, *args, **kwargs)
+            return async_wrapper  # type: ignore
+        else:
+            @functools.wraps(func)
+            def sync_wrapper(*args, **kwargs):
+                return chain.execute(func, *args, **kwargs)
+            return sync_wrapper  # type: ignore
+    
+    return decorator

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