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

provide/foundation/env/core.py

@@ -0,0 +1,218 @@
+"""Core environment variable utilities for Foundation."""
+
+import os
+
+from provide.foundation.errors import ValidationError
+
+
+def get_env(key: str, default: str | None = None) -> str | None:
+    """
+    Get environment variable with Foundation tracking.
+
+    Args:
+        key: Environment variable name
+        default: Default value if variable not found
+
+    Returns:
+        Environment variable value or default
+
+    Example:
+        >>> get_env("HOME")  # doctest: +SKIP
+        '/Users/username'
+        >>> get_env("NONEXISTENT", "fallback")
+        'fallback'
+    """
+    return os.environ.get(key, default)
+
+
+def set_env(key: str, value: str) -> None:
+    """
+    Set environment variable with validation.
+
+    Args:
+        key: Environment variable name
+        value: Value to set
+
+    Raises:
+        ValidationError: If key or value is invalid
+
+    Example:
+        >>> set_env("TEST_VAR", "test_value")
+        >>> get_env("TEST_VAR")
+        'test_value'
+    """
+    if not isinstance(key, str) or not key:
+        raise ValidationError("Environment variable key must be a non-empty string")
+    if not isinstance(value, str):
+        raise ValidationError("Environment variable value must be a string")
+
+    os.environ[key] = value
+
+
+def unset_env(key: str) -> None:
+    """
+    Remove environment variable if it exists.
+
+    Args:
+        key: Environment variable name to remove
+
+    Example:
+        >>> set_env("TEMP_VAR", "value")
+        >>> unset_env("TEMP_VAR")
+        >>> has_env("TEMP_VAR")
+        False
+    """
+    os.environ.pop(key, None)
+
+
+def has_env(key: str) -> bool:
+    """
+    Check if environment variable exists.
+
+    Args:
+        key: Environment variable name
+
+    Returns:
+        True if variable exists, False otherwise
+
+    Example:
+        >>> has_env("PATH")
+        True
+        >>> has_env("DEFINITELY_NOT_SET")
+        False
+    """
+    return key in os.environ
+
+
+def get_env_int(key: str, default: int | None = None) -> int | None:
+    """
+    Get environment variable as integer.
+
+    Args:
+        key: Environment variable name
+        default: Default value if variable not found or invalid
+
+    Returns:
+        Integer value or default
+
+    Raises:
+        ValidationError: If value exists but cannot be converted to int
+
+    Example:
+        >>> set_env("PORT", "8080")
+        >>> get_env_int("PORT")
+        8080
+        >>> get_env_int("MISSING_PORT", 3000)
+        3000
+    """
+    value = os.environ.get(key)
+    if value is None:
+        return default
+
+    try:
+        return int(value)
+    except ValueError as e:
+        raise ValidationError(
+            f"Environment variable {key}='{value}' cannot be converted to int"
+        ) from e
+
+
+def get_env_bool(key: str, default: bool | None = None) -> bool | None:
+    """
+    Get environment variable as boolean.
+
+    Recognizes: true/false, yes/no, 1/0, on/off (case insensitive)
+
+    Args:
+        key: Environment variable name
+        default: Default value if variable not found
+
+    Returns:
+        Boolean value or default
+
+    Raises:
+        ValidationError: If value exists but cannot be converted to bool
+
+    Example:
+        >>> set_env("DEBUG", "true")
+        >>> get_env_bool("DEBUG")
+        True
+        >>> set_env("VERBOSE", "no")
+        >>> get_env_bool("VERBOSE")
+        False
+    """
+    value = os.environ.get(key)
+    if value is None:
+        return default
+
+    value_lower = value.lower().strip()
+    if value_lower in ("true", "yes", "1", "on"):
+        return True
+    elif value_lower in ("false", "no", "0", "off"):
+        return False
+    else:
+        raise ValidationError(
+            f"Environment variable {key}='{value}' cannot be converted to bool"
+        )
+
+
+def get_env_float(key: str, default: float | None = None) -> float | None:
+    """
+    Get environment variable as float.
+
+    Args:
+        key: Environment variable name
+        default: Default value if variable not found or invalid
+
+    Returns:
+        Float value or default
+
+    Raises:
+        ValidationError: If value exists but cannot be converted to float
+
+    Example:
+        >>> set_env("TIMEOUT", "30.5")
+        >>> get_env_float("TIMEOUT")
+        30.5
+    """
+    value = os.environ.get(key)
+    if value is None:
+        return default
+
+    try:
+        return float(value)
+    except ValueError as e:
+        raise ValidationError(
+            f"Environment variable {key}='{value}' cannot be converted to float"
+        ) from e
+
+
+def get_env_list(
+    key: str, separator: str = ",", default: list[str] | None = None
+) -> list[str] | None:
+    """
+    Get environment variable as list of strings.
+
+    Args:
+        key: Environment variable name
+        separator: Character to split on (default: comma)
+        default: Default value if variable not found
+
+    Returns:
+        List of strings or default
+
+    Example:
+        >>> set_env("ALLOWED_HOSTS", "localhost,127.0.0.1,example.com")
+        >>> get_env_list("ALLOWED_HOSTS")
+        ['localhost', '127.0.0.1', 'example.com']
+        >>> get_env_list("MISSING", default=["fallback"])
+        ['fallback']
+    """
+    value = os.environ.get(key)
+    if value is None:
+        return default
+
+    if not value.strip():
+        return []
+
+    return [item.strip() for item in value.split(separator) if item.strip()]

provide/foundation/errors/__init__.py

@@ -20,7 +20,6 @@ from provide.foundation.errors.context import (
 )
 from provide.foundation.errors.decorators import (
     fallback_on_error,
-    retry_on_error,
     suppress_and_log,
     with_error_handling,
 )
@@ -50,9 +49,11 @@ from provide.foundation.errors.safe_decorators import log_only_error_context
 from provide.foundation.errors.types import (
     ErrorCode,
     ErrorMetadata,
-    RetryPolicy,
 )
 
+# Re-export from resilience module for compatibility
+from provide.foundation.resilience.decorators import retry as retry_on_error
+
 __all__ = [
     "AlreadyExistsError",
     "AuthenticationError",
@@ -77,7 +78,6 @@ __all__ = [
     "ProcessError",
     "ProcessTimeoutError",
     "ResourceError",
-    "RetryPolicy",
     "RuntimeError",
     "StateError",
     "TimeoutError",

provide/foundation/errors/decorators.py

@@ -7,13 +7,9 @@ fallback, and error suppression.
 from collections.abc import Callable
 import functools
 import inspect
-import time
 from typing import Any, TypeVar
 
-from attrs import define, field
-
 from provide.foundation.errors.base import FoundationError
-from provide.foundation.errors.types import RetryPolicy
 
 F = TypeVar("F", bound=Callable[..., Any])
 
@@ -148,126 +144,6 @@ def with_error_handling(
         return decorator(func)
 
 
-def retry_on_error(
-    *exceptions: type[Exception],
-    policy: RetryPolicy | None = None,
-    max_attempts: int | None = None,
-    delay: float | None = None,
-    backoff: float | None = None,
-    on_retry: Callable[[int, Exception], None] | None = None,
-) -> Callable[[F], F]:
-    """Decorator for retrying operations on specific errors.
-
-    Args:
-        *exceptions: Exception types to retry on (all if empty).
-        policy: Complete retry policy (overrides other retry params).
-        max_attempts: Maximum retry attempts (ignored if policy provided).
-        delay: Base delay between retries in seconds.
-        backoff: Backoff multiplier for delays.
-        on_retry: Callback function called before each retry.
-
-    Returns:
-        Decorated function.
-
-    Examples:
-        >>> @retry_on_error(ConnectionError, TimeoutError, max_attempts=3)
-        ... def fetch_data():
-        ...     return api_call()
-
-        >>> @retry_on_error(
-        ...     policy=RetryPolicy(max_attempts=5, backoff="exponential")
-        ... )
-        ... def unreliable_operation():
-        ...     pass
-    """
-    # Use provided policy or create one from parameters
-    if policy is None:
-        from provide.foundation.errors.types import BackoffStrategy
-
-        # Determine backoff strategy
-        if backoff is not None and backoff > 1:
-            backoff_strategy = BackoffStrategy.EXPONENTIAL
-        elif backoff == 1:
-            backoff_strategy = BackoffStrategy.FIXED
-        else:
-            backoff_strategy = BackoffStrategy.EXPONENTIAL
-
-        policy = RetryPolicy(
-            max_attempts=max_attempts or 3,
-            base_delay=delay or 1.0,
-            backoff=backoff_strategy,
-            retryable_errors=exceptions if exceptions else None,
-        )
-
-    def decorator(func: F) -> F:
-        @functools.wraps(func)
-        def wrapper(*args, **kwargs):
-            last_exception = None
-
-            for attempt in range(1, policy.max_attempts + 1):
-                try:
-                    return func(*args, **kwargs)
-                except Exception as e:
-                    last_exception = e
-
-                    # Check if we should retry this error
-                    if not policy.should_retry(e, attempt):
-                        if attempt > 1:  # Only log if we've actually retried
-                            _get_logger().error(
-                                f"All {attempt} retry attempts failed for {func.__name__}",
-                                attempts=attempt,
-                                error=str(e),
-                                error_type=type(e).__name__,
-                            )
-                        raise
-
-                    # Don't retry on last attempt
-                    if attempt >= policy.max_attempts:
-                        _get_logger().error(
-                            f"All {policy.max_attempts} retry attempts failed for {func.__name__}",
-                            attempts=policy.max_attempts,
-                            error=str(e),
-                            error_type=type(e).__name__,
-                        )
-                        raise
-
-                    # Calculate delay
-                    retry_delay = policy.calculate_delay(attempt)
-
-                    # Log retry attempt
-                    _get_logger().warning(
-                        f"Retry {attempt}/{policy.max_attempts} for {func.__name__} after {retry_delay:.2f}s",
-                        function=func.__name__,
-                        attempt=attempt,
-                        max_attempts=policy.max_attempts,
-                        delay=retry_delay,
-                        error=str(e),
-                        error_type=type(e).__name__,
-                    )
-
-                    # Call retry callback if provided
-                    if on_retry:
-                        try:
-                            on_retry(attempt, e)
-                        except Exception as callback_error:
-                            _get_logger().warning(
-                                f"Retry callback failed: {callback_error}",
-                                function=func.__name__,
-                                attempt=attempt,
-                            )
-
-                    # Wait before retry
-                    time.sleep(retry_delay)
-
-            # Should never reach here, but just in case
-            if last_exception:
-                raise last_exception
-
-        return wrapper  # type: ignore
-
-    return decorator
-
-
 def suppress_and_log(
     *exceptions: type[Exception],
     fallback: Any = None,
@@ -372,113 +248,3 @@ def fallback_on_error(
         return wrapper  # type: ignore
 
     return decorator
-
-
-@define(kw_only=True, slots=True)
-class CircuitBreaker:
-    """Circuit breaker pattern for preventing cascading failures.
-
-    Attributes:
-        failure_threshold: Number of failures before opening circuit.
-        recovery_timeout: Seconds to wait before attempting recovery.
-        expected_exception: Exception types that trigger the breaker.
-    """
-
-    failure_threshold: int = 5
-    recovery_timeout: float = 60.0
-    expected_exception: tuple[type[Exception], ...] = field(default=(Exception,))
-
-    # Internal state
-    _failure_count: int = field(init=False, default=0)
-    _last_failure_time: float | None = field(init=False, default=None)
-    _state: str = field(init=False, default="closed")  # closed, open, half_open
-
-    def __call__(self, func: F) -> F:
-        """Decorator to apply circuit breaker to a function."""
-
-        @functools.wraps(func)
-        def wrapper(*args, **kwargs):
-            # Check circuit state
-            if self._state == "open":
-                # Check if we should try half-open
-                if (
-                    self._last_failure_time
-                    and (time.time() - self._last_failure_time) > self.recovery_timeout
-                ):
-                    self._state = "half_open"
-                    _get_logger().info(
-                        f"Circuit breaker for {func.__name__} entering half-open state",
-                        function=func.__name__,
-                    )
-                else:
-                    raise RuntimeError(f"Circuit breaker is open for {func.__name__}")
-
-            try:
-                result = func(*args, **kwargs)
-
-                # Success - reset on half-open or reduce failure count
-                if self._state == "half_open":
-                    self._state = "closed"
-                    self._failure_count = 0
-                    _get_logger().info(
-                        f"Circuit breaker for {func.__name__} closed after successful recovery",
-                        function=func.__name__,
-                    )
-                elif self._failure_count > 0:
-                    self._failure_count = max(0, self._failure_count - 1)
-
-                return result
-
-            except self.expected_exception as e:
-                self._failure_count += 1
-                self._last_failure_time = time.time()
-
-                # Check if we should open the circuit
-                if self._failure_count >= self.failure_threshold:
-                    self._state = "open"
-                    _get_logger().error(
-                        f"Circuit breaker for {func.__name__} opened after {self._failure_count} failures",
-                        function=func.__name__,
-                        failures=self._failure_count,
-                        error=str(e),
-                    )
-                else:
-                    _get_logger().warning(
-                        f"Circuit breaker for {func.__name__} failure {self._failure_count}/{self.failure_threshold}",
-                        function=func.__name__,
-                        failures=self._failure_count,
-                        threshold=self.failure_threshold,
-                        error=str(e),
-                    )
-
-                raise
-
-        return wrapper  # type: ignore
-
-
-def circuit_breaker(
-    failure_threshold: int = 5,
-    recovery_timeout: float = 60.0,
-    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,
-    )
-    return breaker

provide/foundation/errors/types.py

@@ -118,104 +118,6 @@ class ErrorMetadata:
         return result
 
 
-class BackoffStrategy(str, Enum):
-    """Backoff strategies for retry policies."""
-
-    FIXED = "fixed"  # Fixed delay between retries
-    LINEAR = "linear"  # Linear increase (delay * attempt)
-    EXPONENTIAL = "exponential"  # Exponential increase (delay * 2^attempt)
-    FIBONACCI = "fibonacci"  # Fibonacci sequence delays
-
-
-@define(kw_only=True, slots=True)
-class RetryPolicy:
-    """Configuration for retry behavior on errors.
-
-    Attributes:
-        max_attempts: Maximum number of retry attempts.
-        backoff: Backoff strategy to use.
-        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.
-        retryable_errors: Optional tuple of exception types to retry on.
-
-    Examples:
-        >>> policy = RetryPolicy(
-        ...     max_attempts=5,
-        ...     backoff=BackoffStrategy.EXPONENTIAL,
-        ...     base_delay=1.0,
-        ...     max_delay=30.0
-        ... )
-    """
-
-    max_attempts: int = 3
-    backoff: BackoffStrategy = BackoffStrategy.EXPONENTIAL
-    base_delay: float = 1.0
-    max_delay: float = 60.0
-    jitter: bool = True
-    retryable_errors: tuple[type[Exception], ...] | None = None
-
-    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:
-            import random
-
-            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
-
-
 @define(kw_only=True, slots=True)
 class ErrorResponse:
     """Structured error response for APIs and external interfaces.

provide/foundation/eventsets/display.py

@@ -2,10 +2,9 @@
 Event set display utilities for Foundation.
 """
 
-from provide.foundation.logger import get_logger
-
-from provide.foundation.eventsets.registry import get_registry, discover_event_sets
+from provide.foundation.eventsets.registry import discover_event_sets, get_registry
 from provide.foundation.eventsets.resolver import get_resolver
+from provide.foundation.logger import get_logger
 
 logger = get_logger(__name__)
 
@@ -17,16 +16,16 @@ def show_event_matrix() -> None:
     """
     # Ensure event sets are discovered
     discover_event_sets()
-    
+
     registry = get_registry()
     resolver = get_resolver()
-    
+
     # Force resolution to ensure everything is loaded
     resolver.resolve()
-    
+
     lines: list[str] = ["Foundation Event Sets: Active Configuration"]
     lines.append("=" * 70)
-    
+
     # Show registered event sets
     event_sets = registry.list_event_sets()
     if event_sets:
@@ -35,7 +34,7 @@ def show_event_matrix() -> None:
             lines.append(f"\n  {config.name} (priority: {config.priority})")
             if config.description:
                 lines.append(f"    {config.description}")
-            
+
             # Show field mappings
             if config.field_mappings:
                 lines.append(f"    Field Mappings ({len(config.field_mappings)}):")
@@ -43,7 +42,7 @@ def show_event_matrix() -> None:
                     lines.append(f"      - {mapping.log_key}")
                 if len(config.field_mappings) > 5:
                     lines.append(f"      ... and {len(config.field_mappings) - 5} more")
-            
+
             # Show event sets
             if config.event_sets:
                 lines.append(f"    Event Sets ({len(config.event_sets)}):")
@@ -59,15 +58,15 @@ def show_event_matrix() -> None:
                     )
     else:
         lines.append("\n  (No event sets registered)")
-    
+
     lines.append("\n" + "=" * 70)
-    
+
     # Show resolved state
     if resolver._resolved:
         lines.append("\nResolver State:")
         lines.append(f"  Total Field Mappings: {len(resolver._field_mappings)}")
         lines.append(f"  Total Event Sets: {len(resolver._event_sets)}")
-        
+
         # Show sample visual markers
         if resolver._event_sets:
             lines.append("\n  Sample Visual Markers:")
@@ -79,6 +78,6 @@ def show_event_matrix() -> None:
                         lines.append(f"      {marker} -> {key}")
     else:
         lines.append("\n  (Resolver not yet initialized)")
-    
+
     # Log the complete display
-    logger.info("\n".join(lines))
+    logger.info("\n".join(lines))