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

provide/foundation/resilience/decorators.py

@@ -4,13 +4,14 @@ 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
+from provide.foundation.resilience.retry import (
+    BackoffStrategy,
+    RetryExecutor,
+    RetryPolicy,
+)
 
 F = TypeVar("F", bound=Callable[..., Any])
 
@@ -18,6 +19,7 @@ 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
 
 
@@ -33,22 +35,22 @@ def retry(
 ) -> 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)
@@ -58,79 +60,89 @@ def retry(
         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):
+    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"
-        )
-    
+        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
+            policy_kwargs["max_attempts"] = max_attempts
         if base_delay is not None:
-            policy_kwargs['base_delay'] = base_delay
+            policy_kwargs["base_delay"] = base_delay
         if backoff is not None:
-            policy_kwargs['backoff'] = backoff
+            policy_kwargs["backoff"] = backoff
         if max_delay is not None:
-            policy_kwargs['max_delay'] = max_delay
+            policy_kwargs["max_delay"] = max_delay
         if jitter is not None:
-            policy_kwargs['jitter'] = jitter
+            policy_kwargs["jitter"] = jitter
         if exceptions:
-            policy_kwargs['retryable_errors'] = 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
 
 
@@ -163,34 +175,34 @@ def circuit_breaker(
         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"
@@ -200,21 +212,25 @@ def fallback(*fallback_funcs: Callable[..., Any]) -> Callable[[F], F]:
         ...     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
+
+    return decorator

provide/foundation/resilience/fallback.py

@@ -4,7 +4,7 @@ Fallback implementation for graceful degradation.
 
 import asyncio
 import functools
-from typing import Any, Callable, TypeVar
+from typing import Callable, TypeVar
 
 from attrs import define, field
 
@@ -16,31 +16,34 @@ 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')
+            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'))
+            logger.trace(
+                "Primary function succeeded",
+                func=getattr(primary_func, "__name__", "anonymous"),
+            )
             return result
         except Exception as e:
             primary_exception = e
@@ -49,17 +52,17 @@ class FallbackChain:
                 logger.debug(
                     "Primary function failed with unexpected exception type",
                     exception_type=type(e).__name__,
-                    expected_types=[t.__name__ for t in self.expected_exceptions]
+                    expected_types=[t.__name__ for t in self.expected_exceptions],
                 )
                 raise
-            
+
             logger.warning(
                 "Primary function failed, trying fallbacks",
-                func=getattr(primary_func, '__name__', 'anonymous'),
+                func=getattr(primary_func, "__name__", "anonymous"),
                 error=str(e),
-                fallback_count=len(self.fallbacks)
+                fallback_count=len(self.fallbacks),
             )
-        
+
         # Try fallbacks in order
         last_exception = None
         for i, fallback_func in enumerate(self.fallbacks):
@@ -68,7 +71,7 @@ class FallbackChain:
                 logger.info(
                     "Fallback succeeded",
                     fallback_index=i,
-                    fallback_name=getattr(fallback_func, '__name__', 'anonymous')
+                    fallback_name=getattr(fallback_func, "__name__", "anonymous"),
                 )
                 return result
             except Exception as e:
@@ -76,26 +79,28 @@ class FallbackChain:
                 logger.warning(
                     "Fallback failed",
                     fallback_index=i,
-                    fallback_name=getattr(fallback_func, '__name__', 'anonymous'),
-                    error=str(e)
+                    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)
+            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")
-    
+        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
@@ -105,7 +110,10 @@ class FallbackChain:
                 result = await primary_func(*args, **kwargs)
             else:
                 result = primary_func(*args, **kwargs)
-            logger.trace("Primary function succeeded", func=getattr(primary_func, '__name__', 'anonymous'))
+            logger.trace(
+                "Primary function succeeded",
+                func=getattr(primary_func, "__name__", "anonymous"),
+            )
             return result
         except Exception as e:
             primary_exception = e
@@ -114,17 +122,17 @@ class FallbackChain:
                 logger.debug(
                     "Primary function failed with unexpected exception type",
                     exception_type=type(e).__name__,
-                    expected_types=[t.__name__ for t in self.expected_exceptions]
+                    expected_types=[t.__name__ for t in self.expected_exceptions],
                 )
                 raise
-            
+
             logger.warning(
                 "Primary function failed, trying fallbacks",
-                func=getattr(primary_func, '__name__', 'anonymous'),
+                func=getattr(primary_func, "__name__", "anonymous"),
                 error=str(e),
-                fallback_count=len(self.fallbacks)
+                fallback_count=len(self.fallbacks),
             )
-        
+
         # Try fallbacks in order
         last_exception = None
         for i, fallback_func in enumerate(self.fallbacks):
@@ -136,7 +144,7 @@ class FallbackChain:
                 logger.info(
                     "Fallback succeeded",
                     fallback_index=i,
-                    fallback_name=getattr(fallback_func, '__name__', 'anonymous')
+                    fallback_name=getattr(fallback_func, "__name__", "anonymous"),
                 )
                 return result
             except Exception as e:
@@ -144,50 +152,57 @@ class FallbackChain:
                 logger.warning(
                     "Fallback failed",
                     fallback_index=i,
-                    fallback_name=getattr(fallback_func, '__name__', 'anonymous'),
-                    error=str(e)
+                    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)
+            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")
+        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
+
+    return decorator