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

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:

provide/foundation/testing/__init__.py

@@ -66,15 +66,20 @@ def __getattr__(name: str) -> Any:
         "isolated_cli_runner",
         "temp_config_file",
         "create_test_cli",
-        "mock_logger",
         "CliTestCase",
+        "click_testing_mode",
     ]:
         import provide.foundation.testing.cli as cli_module
 
         return getattr(cli_module, name)
 
     # Logger testing utilities
-    elif name in ["reset_foundation_setup_for_testing", "reset_foundation_state"]:
+    elif name in [
+        "reset_foundation_setup_for_testing",
+        "reset_foundation_state",
+        "mock_logger",
+        "mock_logger_factory",
+    ]:
         import provide.foundation.testing.logger as logger_module
 
         return getattr(logger_module, name)
@@ -93,6 +98,83 @@ def __getattr__(name: str) -> Any:
         import provide.foundation.testing.fixtures as fixtures_module
 
         return getattr(fixtures_module, name)
+    
+    # Import submodules directly
+    elif name in ["archive", "common", "file", "process", "transport", "mocking", "time", "threading"]:
+        import importlib
+        return importlib.import_module(f"provide.foundation.testing.{name}")
+    
+    # File testing utilities (backward compatibility)
+    elif name in [
+        "temp_directory",
+        "test_files_structure",
+        "temp_file",
+        "binary_file",
+        "nested_directory_structure",
+        "empty_directory",
+        "readonly_file",
+    ]:
+        import provide.foundation.testing.file.fixtures as file_module
+        return getattr(file_module, name)
+    
+    # Process/async testing utilities (backward compatibility)
+    elif name in [
+        "clean_event_loop",
+        "async_timeout",
+        "mock_async_process",
+        "async_stream_reader",
+        "event_loop_policy",
+        "async_context_manager",
+        "async_iterator",
+        "async_queue",
+        "async_lock",
+        "mock_async_sleep",
+    ]:
+        import provide.foundation.testing.process.fixtures as process_module
+        return getattr(process_module, name)
+    
+    # Common mock utilities (backward compatibility)
+    elif name in [
+        "mock_http_config",
+        "mock_telemetry_config",
+        "mock_config_source",
+        "mock_event_emitter",
+        "mock_transport",
+        "mock_metrics_collector",
+        "mock_cache",
+        "mock_database",
+        "mock_file_system",
+        "mock_subprocess",
+    ]:
+        import provide.foundation.testing.common.fixtures as common_module
+        return getattr(common_module, name)
+    
+    # Transport/network testing utilities (backward compatibility)
+    elif name in [
+        "free_port",
+        "mock_server",
+        "httpx_mock_responses",
+        "mock_websocket",
+        "mock_dns_resolver",
+        "tcp_client_server",
+        "mock_ssl_context",
+        "network_timeout",
+        "mock_http_headers",
+    ]:
+        import provide.foundation.testing.transport.fixtures as transport_module
+        return getattr(transport_module, name)
+    
+    # Archive testing utilities
+    elif name in [
+        "archive_test_content",
+        "large_file_for_compression",
+        "multi_format_archives",
+        "archive_with_permissions",
+        "corrupted_archives",
+        "archive_stress_test_files",
+    ]:
+        import provide.foundation.testing.archive.fixtures as archive_module
+        return getattr(archive_module, name)
 
     # Crypto fixtures (many fixtures)
     elif name in [

provide/foundation/testing/archive/__init__.py

@@ -0,0 +1,24 @@
+"""
+Archive testing fixtures for the provide-io ecosystem.
+
+Standard fixtures for testing archive operations (tar, zip, gzip, bzip2)
+across any project that depends on provide.foundation.
+"""
+
+from provide.foundation.testing.archive.fixtures import (
+    archive_test_content,
+    large_file_for_compression,
+    multi_format_archives,
+    archive_with_permissions,
+    corrupted_archives,
+    archive_stress_test_files,
+)
+
+__all__ = [
+    "archive_test_content",
+    "large_file_for_compression",
+    "multi_format_archives",
+    "archive_with_permissions",
+    "corrupted_archives",
+    "archive_stress_test_files",
+]