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

provide/foundation/resilience/retry.py

@@ -6,9 +6,9 @@ eliminating duplication between decorators and middleware.
 """
 
 import asyncio
+from enum import Enum
 import random
 import time
-from enum import Enum
 from typing import Any, Callable, TypeVar
 
 from attrs import define, field, validators
@@ -22,7 +22,7 @@ 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)
@@ -33,10 +33,10 @@ class BackoffStrategy(str, Enum):
 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
@@ -46,48 +46,52 @@ class RetryPolicy:
         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)))
+    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):
+    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, value):
+    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, value):
+    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:
@@ -102,61 +106,61 @@ class RetryPolicy:
             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
-        
+            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 (
@@ -168,50 +172,50 @@ class RetryPolicy:
 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
+        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(
@@ -221,14 +225,14 @@ class RetryExecutor:
                         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",
@@ -238,46 +242,45 @@ class RetryExecutor:
                     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)
+                            "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(
@@ -287,14 +290,14 @@ class RetryExecutor:
                         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",
@@ -304,7 +307,7 @@ class RetryExecutor:
                     error=str(e),
                     error_type=type(e).__name__,
                 )
-                
+
                 # Call retry callback if provided
                 if self.on_retry:
                     try:
@@ -314,12 +317,11 @@ class RetryExecutor:
                             self.on_retry(attempt, e)
                     except Exception as callback_error:
                         logger.warning(
-                            "Retry callback failed",
-                            error=str(callback_error)
+                            "Retry callback failed", error=str(callback_error)
                         )
-                
+
                 # Wait before retry
                 await asyncio.sleep(delay)
-        
+
         # Should never reach here, but for safety
-        raise last_exception
+        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

@@ -7,9 +7,9 @@ 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
+from provide.foundation.config.env import RuntimeConfig
 
 
 @define(slots=True, repr=False)
@@ -22,35 +22,34 @@ class StreamConfig(RuntimeConfig):
         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
@@ -63,7 +62,7 @@ _stream_config: StreamConfig | None = None
 def get_stream_config() -> StreamConfig:
     """
     Get the global stream configuration instance.
-    
+
     Returns:
         StreamConfig instance loaded from environment
     """
@@ -76,4 +75,4 @@ def get_stream_config() -> StreamConfig:
 def reset_stream_config() -> None:
     """Reset the global stream configuration (mainly for testing)."""
     global _stream_config
-    _stream_config = None
+    _stream_config = None

provide/foundation/streams/console.py

@@ -27,13 +27,13 @@ def is_tty() -> bool:
 def supports_color() -> bool:
     """Check if the current stream supports color output."""
     config = get_stream_config()
-    
+
     if config.no_color:
         return False
-    
+
     if config.force_color:
         return True
-    
+
     # Check if we're in a TTY
     return is_tty()
 

provide/foundation/streams/core.py

@@ -20,9 +20,9 @@ _STREAM_LOCK = threading.Lock()
 def _is_in_click_testing() -> bool:
     """Check if we're running inside Click's testing framework."""
     import inspect
-    
+
     config = get_stream_config()
-    
+
     # Check environment variables for Click testing
     if config.click_testing:
         return True

provide/foundation/streams/file.py

@@ -21,7 +21,7 @@ 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.
     """

provide/foundation/testing/__init__.py

@@ -98,12 +98,22 @@ 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"]:
+    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",
@@ -115,8 +125,9 @@ def __getattr__(name: str) -> Any:
         "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",
@@ -131,8 +142,9 @@ def __getattr__(name: str) -> Any:
         "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",
@@ -147,8 +159,9 @@ def __getattr__(name: str) -> Any:
         "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",
@@ -162,8 +175,9 @@ def __getattr__(name: str) -> Any:
         "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",
@@ -174,6 +188,7 @@ def __getattr__(name: str) -> Any:
         "archive_stress_test_files",
     ]:
         import provide.foundation.testing.archive.fixtures as archive_module
+
         return getattr(archive_module, name)
 
     # Crypto fixtures (many fixtures)

provide/foundation/testing/archive/__init__.py

@@ -6,19 +6,19 @@ across any project that depends on provide.foundation.
 """
 
 from provide.foundation.testing.archive.fixtures import (
+    archive_stress_test_files,
     archive_test_content,
-    large_file_for_compression,
-    multi_format_archives,
     archive_with_permissions,
     corrupted_archives,
-    archive_stress_test_files,
+    large_file_for_compression,
+    multi_format_archives,
 )
 
 __all__ = [
+    "archive_stress_test_files",
     "archive_test_content",
-    "large_file_for_compression",
-    "multi_format_archives",
     "archive_with_permissions",
     "corrupted_archives",
-    "archive_stress_test_files",
-]
+    "large_file_for_compression",
+    "multi_format_archives",
+]