crackerjack 0.18.2__py3-none-any.whl → 0.45.2__py3-none-any.whl

crackerjack/utils/dependency_guard.py

@@ -0,0 +1,230 @@
+"""
+Dependency Guard module to ensure proper dependency injection.
+
+This module provides utilities to ensure that dependencies are properly
+registered in the ACB dependency injection system and to handle cases
+where dependencies might be registered as empty tuples or other invalid
+values.
+"""
+
+import sys
+import typing
+from typing import Any
+
+from acb.depends import depends
+from acb.logger import Logger
+
+
+def _should_log_debug() -> bool:
+    """Check if debug mode is active via CLI flags.
+
+    Uses sys.argv directly for early detection before flag parsing.
+    This is thread-safe as sys.argv is read-only during execution.
+    """
+    return any(
+        arg in ("--debug", "-d", "--ai-debug") or arg.startswith("--debug=")
+        for arg in sys.argv[1:]
+    )
+
+
+def _log_dependency_issue(message: str, level: str = "WARNING") -> None:
+    """Log dependency issues only in debug mode.
+
+    Args:
+        message: The log message to emit
+        level: Log level (INFO, WARNING, ERROR)
+    """
+    if not _should_log_debug():
+        return
+    # Use stderr for diagnostic messages (stdout reserved for user output)
+    print(f"[CRACKERJACK:{level}] {message}", file=sys.stderr)
+
+
+def ensure_logger_dependency() -> None:
+    """
+    Ensure that Logger and LoggerProtocol are properly registered in the DI container.
+    This prevents issues where empty tuples might get registered instead of logger instances.
+    """
+    # Check if Logger is registered and has a valid instance
+    try:
+        logger_instance = depends.get_sync(Logger)
+        # If we get an empty tuple, string, or other invalid value, replace it
+        if isinstance(logger_instance, tuple) and len(logger_instance) == 0:
+            _log_dependency_issue(
+                "Logger dependency was registered as empty tuple, replacing with fresh instance"
+            )
+            # Create a new logger instance to replace the invalid one
+            from acb.logger import Logger as ACBLogger
+
+            fresh_logger = ACBLogger()
+            depends.set(Logger, fresh_logger)
+        elif isinstance(logger_instance, str):
+            _log_dependency_issue(
+                f"Logger dependency was registered as string ({logger_instance!r}), replacing with fresh instance"
+            )
+            # Create a new logger instance to replace the invalid one
+            from acb.logger import Logger as ACBLogger
+
+            fresh_logger = ACBLogger()
+            depends.set(Logger, fresh_logger)
+    except Exception:
+        # If there's no logger registered at all, create one
+        from acb.logger import Logger as ACBLogger
+
+        fresh_logger = ACBLogger()
+        depends.set(Logger, fresh_logger)
+
+    # Do the same check for LoggerProtocol if it exists
+    # Import once to avoid typing issues
+    try:
+        from crackerjack.models.protocols import LoggerProtocol as _LoggerProtocol
+
+        logger_proto_instance = depends.get_sync(_LoggerProtocol)
+        if isinstance(logger_proto_instance, tuple) and len(logger_proto_instance) == 0:
+            _log_dependency_issue(
+                "LoggerProtocol dependency was registered as empty tuple, replacing with fresh instance"
+            )
+            from acb.logger import Logger as ACBLogger
+
+            fresh_logger = ACBLogger()
+            depends.set(_LoggerProtocol, fresh_logger)
+        elif isinstance(logger_proto_instance, str):
+            _log_dependency_issue(
+                f"LoggerProtocol dependency was registered as string ({logger_proto_instance!r}), replacing with fresh instance"
+            )
+            from acb.logger import Logger as ACBLogger
+
+            fresh_logger = ACBLogger()
+            depends.set(_LoggerProtocol, fresh_logger)
+    except ImportError:
+        # LoggerProtocol doesn't exist, that's fine
+        pass
+    except Exception:
+        # If there's no LoggerProtocol registered, create one
+        try:
+            from acb.logger import Logger as ACBLogger
+
+            fresh_logger = ACBLogger()
+            _log_dependency_issue(
+                "Registering LoggerProtocol with fresh logger instance", level="INFO"
+            )
+            # Register the fresh_logger instance with the LoggerProtocol
+            depends.set(_LoggerProtocol, fresh_logger)
+        except NameError:
+            # _LoggerProtocol is not defined if the import failed
+            pass
+        except Exception:
+            pass  # Any other error, just continue
+
+
+def validate_dependency_registration(
+    dep_type: type[Any], fallback_factory: typing.Callable | None = None
+) -> bool:
+    """
+    Validate that a dependency is properly registered and not an empty tuple or string.
+
+    Args:
+        dep_type: The type of dependency to validate
+        fallback_factory: Optional factory function to create a fallback instance if needed
+
+    Returns:
+        True if the dependency is properly registered, False otherwise
+    """
+    try:
+        instance = depends.get_sync(dep_type)
+        # Check if it's an empty tuple (the problematic case)
+        if isinstance(instance, tuple) and len(instance) == 0:
+            _log_dependency_issue(
+                f"Dependency {dep_type} was registered as empty tuple"
+            )
+            # Replace with a fallback if provided
+            if fallback_factory:
+                fallback_instance = fallback_factory()
+                depends.set(dep_type, fallback_instance)
+                _log_dependency_issue(
+                    f"Replaced empty tuple for {dep_type} with new instance",
+                    level="INFO",
+                )
+                return True
+            return False
+        # Check if it's a string (another problematic case)
+        elif isinstance(instance, str):
+            _log_dependency_issue(
+                f"Dependency {dep_type} was registered as string: {instance!r}"
+            )
+            # Replace with a fallback if provided
+            if fallback_factory:
+                fallback_instance = fallback_factory()
+                depends.set(dep_type, fallback_instance)
+                _log_dependency_issue(
+                    f"Replaced string for {dep_type} with new instance", level="INFO"
+                )
+                return True
+            return False
+        return True
+    except Exception:
+        # If dependency doesn't exist at all, return False
+        return False
+
+
+def safe_get_logger() -> Logger:
+    """
+    Safely get a logger instance, ensuring it's not an empty tuple or string.
+
+    Returns:
+        A valid logger instance
+    """
+    try:
+        logger_instance = depends.get_sync(Logger)
+        if isinstance(logger_instance, tuple) and len(logger_instance) == 0:
+            _log_dependency_issue(
+                "Logger dependency was an empty tuple in safe_get_logger, replacing with fresh instance"
+            )
+            # Create and register a fresh logger
+            from acb.logger import Logger as ACBLogger
+
+            fresh_logger = ACBLogger()
+            depends.set(Logger, fresh_logger)
+            return fresh_logger
+        elif isinstance(logger_instance, str):
+            _log_dependency_issue(
+                f"Logger dependency was a string ({logger_instance!r}) in safe_get_logger, replacing with fresh instance"
+            )
+            # Create and register a fresh logger
+            from acb.logger import Logger as ACBLogger
+
+            fresh_logger = ACBLogger()
+            depends.set(Logger, fresh_logger)
+            return fresh_logger
+        return logger_instance
+    except Exception:
+        # If no logger is registered, create one
+        from acb.logger import Logger as ACBLogger
+
+        _log_dependency_issue(
+            "No logger registered, creating and registering a fresh logger instance",
+            level="INFO",
+        )
+        fresh_logger = ACBLogger()
+        depends.set(Logger, fresh_logger)
+        return fresh_logger
+
+
+def check_all_dependencies_for_empty_tuples():
+    """
+    Debug function to check all registered dependencies for empty tuples.
+    This can help identify which dependencies have been incorrectly registered.
+    """
+    # This would require access to the internal state of the ACB DI system
+    # which might not be available, so we'll just print a notice
+    _log_dependency_issue(
+        "Dependency check: To check all dependencies for empty tuples, you would need access to ACB's internal container state.",
+        level="INFO",
+    )
+    _log_dependency_issue(
+        "This is currently not possible without modifying ACB itself.", level="INFO"
+    )
+    _log_dependency_issue(
+        "The best approach is to use the individual validation functions for known problematic dependencies.",
+        level="INFO",
+    )

crackerjack/utils/retry_utils.py

@@ -0,0 +1,275 @@
+"""Retry utilities for handling API connection errors and other transient failures.
+
+This module provides a general-purpose retry decorator that can be used across
+the Crackerjack codebase to handle API connection errors and other transient failures.
+"""
+
+import asyncio
+import functools
+import random
+import time
+from collections.abc import Callable
+from typing import Any, TypeVar, cast
+
+from loguru import logger
+
+T = TypeVar("T")
+
+
+def _calculate_delay(current_delay: float, jitter: bool, backoff: float) -> float:
+    """Calculate the delay for the next retry attempt."""
+    if jitter:
+        return current_delay * (0.5 + random.random() * 0.5)  # nosec B311 # Not used for cryptographic purposes
+    return current_delay * backoff
+
+
+def _prepare_next_attempt(
+    current_delay: float,
+    max_delay: float | None,
+    backoff: float,
+    jitter: bool,
+    attempt: int,
+    max_attempts: int,
+    e: BaseException,
+    logger_func: Callable[[str], None] | None,
+) -> float:
+    """Prepare for the next retry attempt by calculating delay and logging."""
+    current_delay = _calculate_delay(current_delay, jitter, backoff)
+
+    if max_delay:
+        current_delay = min(current_delay, max_delay)
+
+    log_msg = (
+        f"Attempt {attempt + 1}/{max_attempts} failed: {type(e).__name__}: {e}. "
+        f"Retrying in {current_delay:.2f}s..."
+    )
+
+    if logger_func:
+        logger_func(log_msg)
+    else:
+        logger.warning(log_msg)
+
+    return current_delay
+
+
+def _should_retry(attempt: int, max_attempts: int) -> bool:
+    """Determine if we should make another retry attempt."""
+    return attempt != max_attempts - 1  # Continue unless it's the last attempt
+
+
+def retry(
+    max_attempts: int = 3,
+    delay: float = 1.0,
+    backoff: float = 2.0,
+    max_delay: float | None = None,
+    jitter: bool = True,
+    exceptions: tuple[type[BaseException], ...] = (Exception,),
+    logger_func: Callable[[str], None] | None = None,
+) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """Decorator to retry a function when specific exceptions are raised.
+
+    Args:
+        max_attempts: Maximum number of attempts (including initial call)
+        delay: Initial delay between retries in seconds
+        backoff: Multiplier for delay between attempts (exponential backoff)
+        max_delay: Maximum delay between retries (caps exponential growth)
+        jitter: Add random jitter to delay to prevent thundering herd
+        exceptions: Tuple of exception types to catch and retry on
+        logger_func: Optional logger function to use for retry messages
+
+    Returns:
+        Decorator function
+    """
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        @functools.wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> T:
+            return await _retry_async(
+                func,
+                args,
+                kwargs,
+                max_attempts,
+                delay,
+                backoff,
+                max_delay,
+                jitter,
+                exceptions,
+                logger_func,
+            )
+
+        @functools.wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> T:
+            return _retry_sync(
+                func,
+                args,
+                kwargs,
+                max_attempts,
+                delay,
+                backoff,
+                max_delay,
+                jitter,
+                exceptions,
+                logger_func,
+            )
+
+        if asyncio.iscoroutinefunction(func):
+            return cast(Callable[..., T], async_wrapper)
+        return cast(Callable[..., T], sync_wrapper)
+
+    return decorator
+
+
+async def _retry_async[T](
+    func: Callable[..., T],
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+    max_attempts: int,
+    delay: float,
+    backoff: float,
+    max_delay: float | None,
+    jitter: bool,
+    exceptions: tuple[type[BaseException], ...],
+    logger_func: Callable[[str], None] | None,
+) -> T:
+    """Execute async function with retry logic."""
+    last_exception: BaseException | None = None
+    current_delay = delay
+
+    for attempt in range(max_attempts):
+        try:
+            result = await func(*args, **kwargs)  # type: ignore[misc]
+            return result  # type: ignore[no-any-return]
+
+        except exceptions as e:
+            last_exception = e
+
+            if not _should_retry(attempt, max_attempts):
+                break
+
+            current_delay = _prepare_next_attempt(
+                current_delay,
+                max_delay,
+                backoff,
+                jitter,
+                attempt,
+                max_attempts,
+                e,
+                logger_func,
+            )
+
+            await asyncio.sleep(current_delay)
+
+    if last_exception is not None:
+        raise last_exception
+    raise RuntimeError("Retry failed but no exception was captured")
+
+
+def _retry_sync[T](
+    func: Callable[..., T],
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+    max_attempts: int,
+    delay: float,
+    backoff: float,
+    max_delay: float | None,
+    jitter: bool,
+    exceptions: tuple[type[BaseException], ...],
+    logger_func: Callable[[str], None] | None,
+) -> T:
+    """Execute sync function with retry logic."""
+    last_exception: BaseException | None = None
+    current_delay = delay
+
+    for attempt in range(max_attempts):
+        try:
+            result = func(*args, **kwargs)
+            return result  # type: ignore[no-any-return]
+
+        except exceptions as e:
+            last_exception = e
+
+            if not _should_retry(attempt, max_attempts):
+                break
+
+            current_delay = _prepare_next_attempt(
+                current_delay,
+                max_delay,
+                backoff,
+                jitter,
+                attempt,
+                max_attempts,
+                e,
+                logger_func,
+            )
+
+            time.sleep(current_delay)
+
+    if last_exception is not None:
+        raise last_exception
+    raise RuntimeError("Retry failed but no exception was captured")
+
+
+# Common exception types for API connection retries
+API_CONNECTION_EXCEPTIONS = (
+    ConnectionError,
+    TimeoutError,
+    ConnectionResetError,
+    ConnectionAbortedError,
+    BrokenPipeError,
+    OSError,  # Network-related OS errors
+)
+
+
+# Convenience decorator for API calls with common settings
+def retry_api_call(
+    max_attempts: int = 3,
+    delay: float = 1.0,
+    backoff: float = 2.0,
+    max_delay: float | None = 30.0,  # Cap at 30 seconds
+    jitter: bool = True,
+) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """Convenience decorator for API calls with sensible defaults.
+
+    Args:
+        max_attempts: Maximum number of attempts (default: 3)
+        delay: Initial delay in seconds (default: 1.0)
+        backoff: Exponential backoff multiplier (default: 2.0)
+        max_delay: Maximum delay between retries (default: 30.0)
+        jitter: Add jitter to prevent thundering herd (default: True)
+
+    Returns:
+        Decorator function configured for API calls
+    """
+    return retry(
+        max_attempts=max_attempts,
+        delay=delay,
+        backoff=backoff,
+        max_delay=max_delay,
+        jitter=jitter,
+        exceptions=API_CONNECTION_EXCEPTIONS,
+    )
+
+
+# Example usage functions for testing purposes
+@retry_api_call(max_attempts=3, delay=0.5)
+async def example_api_call_async(url: str) -> str:
+    """Example async API call that might fail with network issues."""
+    # Simulate an API call that might fail
+    # import random  # Already imported at the top of the file
+
+    if random.random() < 0.7:  # 70% chance of failure for testing # nosec B311
+        raise ConnectionError("Simulated network error")
+
+    return f"Success: {url}"
+
+
+@retry_api_call(max_attempts=3, delay=0.5)
+def example_api_call_sync(url: str) -> str:
+    """Example sync API call that might fail with network issues."""
+    # Simulate an API call that might fail
+    # import random  # Already imported at the top of file
+
+    if random.random() < 0.7:  # 70% chance of failure for testing # nosec B311
+        raise ConnectionError("Simulated network error")
+
+    return f"Success: {url}"