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

crackerjack/decorators/error_handling_decorators.py

@@ -0,0 +1,334 @@
+"""Reusable decorators for consistent error handling across the codebase."""
+
+import functools
+import json
+import subprocess
+from collections.abc import Callable
+from typing import Any
+
+from loguru import logger
+
+
+def handle_file_errors(
+    exceptions: tuple[type[Exception], ...] = (
+        OSError,
+        FileNotFoundError,
+        PermissionError,
+    ),
+    default_return: Any = None,
+    log_error: bool = True,
+    reraise: bool
+    | None = None,  # If None, reraise is False when default_return is provided
+):
+    """
+    Decorator to handle common file operation errors consistently.
+
+    Args:
+        exceptions: Tuple of exception types to catch
+        default_return: Value to return when an exception occurs
+        log_error: Whether to log the error
+        reraise: Whether to reraise the exception after handling (None means False if default_return is provided)
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            try:
+                return func(*args, **kwargs)
+            except exceptions as e:
+                if log_error:
+                    logger.error(f"File operation failed in {func.__name__}: {e}")
+                # Determine if we should reraise:
+                # - if reraise is explicitly set to True/False, respect that
+                # - if reraise is None (default):
+                #   - reraise if no default_return is provided (when default_return is None)
+                #   - don't reraise if default_return is provided
+                should_reraise = (
+                    reraise if reraise is not None else (default_return is None)
+                )
+                if should_reraise:
+                    raise
+                return default_return
+
+        return wrapper
+
+    return decorator
+
+
+def handle_json_errors(
+    exceptions: tuple[type[Exception], ...] = (
+        json.JSONDecodeError,
+        TypeError,
+        ValueError,
+    ),
+    default_return: Any = None,
+    log_error: bool = True,
+    reraise: bool
+    | None = None,  # If None, reraise is False when default_return is provided
+):
+    """
+    Decorator to handle JSON parsing errors consistently.
+
+    Args:
+        exceptions: Tuple of exception types to catch
+        default_return: Value to return when an exception occurs
+        log_error: Whether to log the error
+        reraise: Whether to reraise the exception after handling (None means False if default_return is provided)
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            try:
+                result = func(*args, **kwargs)
+                return result
+            except exceptions as e:
+                if log_error:
+                    logger.error(f"JSON operation failed in {func.__name__}: {e}")
+                # Determine if we should reraise:
+                # - if reraise is explicitly set to True/False, respect that
+                # - if reraise is None (default):
+                #   - reraise if no default_return is provided (when default_return is None)
+                #   - don't reraise if default_return is provided
+                should_reraise = (
+                    reraise if reraise is not None else (default_return is None)
+                )
+                if should_reraise:
+                    raise
+                return default_return
+
+        return wrapper
+
+    return decorator
+
+
+def handle_subprocess_errors(
+    exceptions: tuple[type[Exception], ...] = (
+        subprocess.CalledProcessError,
+        subprocess.TimeoutExpired,
+    ),
+    default_return: Any = None,
+    log_error: bool = True,
+    reraise: bool
+    | None = None,  # If None, reraise is False when default_return is provided
+):
+    """
+    Decorator to handle subprocess execution errors consistently.
+
+    Args:
+        exceptions: Tuple of exception types to catch
+        default_return: Value to return when an exception occurs
+        log_error: Whether to log the error
+        reraise: Whether to reraise the exception after handling (None means False if default_return is provided)
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            try:
+                result = func(*args, **kwargs)
+                return result
+            except exceptions as e:
+                if log_error:
+                    logger.error(f"Subprocess operation failed in {func.__name__}: {e}")
+                # Determine if we should reraise:
+                # - if reraise is explicitly set to True/False, respect that
+                # - if reraise is None (default):
+                #   - reraise if no default_return is provided (when default_return is None)
+                #   - don't reraise if default_return is provided
+                should_reraise = (
+                    reraise if reraise is not None else (default_return is None)
+                )
+                if should_reraise:
+                    raise
+                return default_return
+
+        return wrapper
+
+    return decorator
+
+
+def handle_validation_errors(
+    exceptions: tuple[type[Exception], ...] = (ValueError, TypeError, AttributeError),
+    default_return: Any = None,
+    log_error: bool = True,
+    reraise: bool
+    | None = None,  # If None, reraise is False when default_return is provided
+):
+    """
+    Decorator to handle data validation errors consistently.
+
+    Args:
+        exceptions: Tuple of exception types to catch
+        default_return: Value to return when an exception occurs
+        log_error: Whether to log the error
+        reraise: Whether to reraise the exception after handling (None means False if default_return is provided)
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            try:
+                result = func(*args, **kwargs)
+                return result
+            except exceptions as e:
+                if log_error:
+                    logger.error(f"Validation failed in {func.__name__}: {e}")
+                # Determine if we should reraise:
+                # - if reraise is explicitly set to True/False, respect that
+                # - if reraise is None (default):
+                #   - reraise if no default_return is provided (when default_return is None)
+                #   - don't reraise if default_return is provided
+                should_reraise = (
+                    reraise if reraise is not None else (default_return is None)
+                )
+                if should_reraise:
+                    raise
+                return default_return
+
+        return wrapper
+
+    return decorator
+
+
+def handle_network_errors(
+    exceptions: tuple[type[Exception], ...] = (
+        ConnectionError,
+        ConnectionRefusedError,
+        TimeoutError,
+        # Add more common network errors as needed
+    ),
+    default_return: Any = None,
+    log_error: bool = True,
+    reraise: bool
+    | None = None,  # If None, reraise is False when default_return is provided
+):
+    """
+    Decorator to handle network-related errors consistently.
+
+    Args:
+        exceptions: Tuple of exception types to catch
+        default_return: Value to return when an exception occurs
+        log_error: Whether to log the error
+        reraise: Whether to reraise the exception after handling (None means False if default_return is provided)
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            try:
+                result = func(*args, **kwargs)
+                return result
+            except exceptions as e:
+                if log_error:
+                    logger.error(f"Network operation failed in {func.__name__}: {e}")
+                # Determine if we should reraise:
+                # - if reraise is explicitly set to True/False, respect that
+                # - if reraise is None (default):
+                #   - reraise if no default_return is provided (when default_return is None)
+                #   - don't reraise if default_return is provided
+                should_reraise = (
+                    reraise if reraise is not None else (default_return is None)
+                )
+                if should_reraise:
+                    raise
+                return default_return
+
+        return wrapper
+
+    return decorator
+
+
+def handle_all_errors(
+    log_error: bool = True,
+    reraise: bool
+    | None = None,  # If None, reraise is False when default_return is provided
+    default_return: Any = None,
+    exclude: tuple[type[BaseException], ...] = (KeyboardInterrupt, SystemExit),
+):
+    """
+    Decorator to handle all errors except for specific system exceptions.
+
+    Args:
+        log_error: Whether to log the error
+        reraise: Whether to reraise the exception after handling (None means False if default_return is provided)
+        default_return: Value to return when an exception occurs
+        exclude: Tuple of exception types to exclude from handling
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            try:
+                return func(*args, **kwargs)
+            except exclude:
+                # Don't handle system exceptions like KeyboardInterrupt
+                raise
+            except Exception as e:
+                if log_error:
+                    logger.error(f"Unexpected error in {func.__name__}: {e}")
+                # Determine if we should reraise:
+                # - if reraise is explicitly set to True/False, respect that
+                # - if reraise is None (default):
+                #   - reraise if no default_return is provided (when default_return is None)
+                #   - don't reraise if default_return is provided
+                should_reraise = (
+                    reraise if reraise is not None else (default_return is None)
+                )
+                if should_reraise:
+                    raise
+                return default_return
+
+        return wrapper
+
+    return decorator
+
+
+def retry_on_error(
+    max_attempts: int = 3,
+    delay: float = 1.0,
+    backoff: float = 2.0,
+    exceptions: tuple[type[Exception], ...] = (Exception,),
+    log_retry: bool = True,
+):
+    """
+    Decorator to retry a function on specific exceptions.
+
+    Args:
+        max_attempts: Maximum number of attempts
+        delay: Initial delay between attempts (in seconds)
+        backoff: Multiplier for delay after each attempt
+        exceptions: Tuple of exception types to retry on
+        log_retry: Whether to log retry attempts
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            current_delay = delay
+            last_exception = None
+
+            for attempt in range(max_attempts):
+                try:
+                    return func(*args, **kwargs)
+                except exceptions as e:
+                    last_exception = e
+                    if log_retry:
+                        logger.warning(
+                            f"Attempt {attempt + 1}/{max_attempts} failed in {func.__name__}: {e}. "
+                            f"Retrying in {current_delay}s..."
+                        )
+                    if attempt < max_attempts - 1:  # Don't sleep after the last attempt
+                        import time
+
+                        time.sleep(current_delay)
+                        current_delay *= backoff
+
+            logger.error(
+                f"All {max_attempts} attempts failed in {func.__name__}: {last_exception}"
+            )
+            raise last_exception
+
+        return wrapper
+
+    return decorator

crackerjack/decorators/helpers.py

@@ -0,0 +1,58 @@
+"""Shared utilities for error handling decorators."""
+
+import asyncio
+import inspect
+import typing as t
+from functools import wraps
+
+F = t.TypeVar("F", bound=t.Callable[..., t.Any])
+
+
+def is_async_function(func: t.Callable[..., t.Any]) -> bool:
+    """Check if a function is async."""
+    return asyncio.iscoroutinefunction(func)
+
+
+def preserve_signature[F: t.Callable[..., t.Any]](
+    wrapper: F,
+) -> t.Callable[[t.Callable[..., t.Any]], F]:
+    """Preserve function signature in decorators."""
+
+    def decorator(func: t.Callable[..., t.Any]) -> F:
+        wrapped = wraps(func)(wrapper)
+        # Preserve signature metadata
+        wrapped.__wrapped__ = func  # type: ignore[attr-defined]
+        return t.cast(F, wrapped)
+
+    return decorator
+
+
+def get_function_context(func: t.Callable[..., t.Any]) -> dict[str, t.Any]:
+    """Extract context information from a function for error reporting."""
+    return {
+        "function_name": func.__name__,
+        "module": func.__module__,
+        "qualname": func.__qualname__,
+        "is_async": is_async_function(func),
+    }
+
+
+def format_exception_chain(exc: BaseException) -> list[str]:
+    """Format exception chain for logging."""
+    chain: list[str] = []
+    current: BaseException | None = exc
+
+    while current is not None:
+        chain.append(f"{type(current).__name__}: {current}")
+        current = current.__cause__ or current.__context__
+
+    return chain
+
+
+def get_callable_params(func: t.Callable[..., t.Any]) -> list[inspect.Parameter]:
+    """Get function parameters using inspect."""
+    try:
+        sig = inspect.signature(func)
+        return list(sig.parameters.values())
+    except (ValueError, TypeError):
+        return []

crackerjack/decorators/patterns.py

@@ -0,0 +1,281 @@
+"""Error pattern detection and caching decorator."""
+
+import typing as t
+from functools import wraps
+from pathlib import Path
+
+from ..errors import CrackerjackError
+from ..mcp.cache import ErrorCache, ErrorPattern
+from .helpers import get_function_context, is_async_function
+
+
+def cache_errors(
+    cache_dir: Path | None = None,
+    error_type: str | None = None,
+    auto_analyze: bool = True,
+) -> t.Callable[[t.Callable[..., t.Any]], t.Callable[..., t.Any]]:
+    """
+    Detect and cache error patterns for analysis and auto-fixing.
+
+    Args:
+        cache_dir: Directory for error cache (default: ~/.cache/crackerjack-mcp)
+        error_type: Override error type classification (default: auto-detect)
+        auto_analyze: Automatically analyze errors for patterns (default: True)
+
+    Returns:
+        Decorated function with error pattern caching
+
+    Example:
+        >>> from pathlib import Path
+        >>>
+        >>> @cache_errors(error_type="lint", auto_analyze=True)
+        >>> async def run_linter(files: list[Path]) -> bool:
+        ...     # Errors are automatically cached and analyzed
+        ...     return await linter.run(files)
+
+        >>> @cache_errors()
+        >>> def execute_command(cmd: list[str]) -> bool:
+        ...     # Error patterns tracked for future auto-fix
+        ...     return subprocess.run(cmd).returncode == 0
+
+    Notes:
+        - Integrates with Crackerjack's ErrorCache system
+        - Tracks error frequency and common fixes
+        - Enables intelligent auto-fix suggestions
+        - Works with AI agents for pattern recognition
+    """
+    error_cache = ErrorCache(cache_dir=cache_dir)
+
+    def decorator(func: t.Callable[..., t.Any]) -> t.Callable[..., t.Any]:
+        if is_async_function(func):
+            return _create_async_wrapper(func, error_cache, error_type, auto_analyze)
+        return _create_sync_wrapper(func, error_cache, error_type, auto_analyze)
+
+    return decorator
+
+
+def _create_async_wrapper(
+    func: t.Callable[..., t.Any],
+    error_cache: ErrorCache,
+    error_type: str | None,
+    auto_analyze: bool,
+) -> t.Callable[..., t.Any]:
+    """Create async wrapper with error caching."""
+
+    @wraps(func)
+    async def async_wrapper(*args: t.Any, **kwargs: t.Any) -> t.Any:
+        try:
+            result = await func(*args, **kwargs)
+            await _handle_result_analysis(
+                result, error_cache, func, error_type, auto_analyze
+            )
+            return result
+        except CrackerjackError as e:
+            await _cache_crackerjack_error(error_cache, e, func, error_type)
+            raise
+        except Exception as e:
+            await _handle_generic_exception(
+                e, error_cache, func, error_type, auto_analyze
+            )
+            raise
+
+    return async_wrapper
+
+
+def _create_sync_wrapper(
+    func: t.Callable[..., t.Any],
+    error_cache: ErrorCache,
+    error_type: str | None,
+    auto_analyze: bool,
+) -> t.Callable[..., t.Any]:
+    """Create sync wrapper with error caching."""
+
+    @wraps(func)
+    def sync_wrapper(*args: t.Any, **kwargs: t.Any) -> t.Any:
+        try:
+            result = func(*args, **kwargs)
+            _handle_result_analysis_sync(
+                result, error_cache, func, error_type, auto_analyze
+            )
+            return result
+        except CrackerjackError as e:
+            _cache_crackerjack_error_sync(error_cache, e, func, error_type)
+            raise
+        except Exception as e:
+            _handle_generic_exception_sync(
+                e, error_cache, func, error_type, auto_analyze
+            )
+            raise
+
+    return sync_wrapper
+
+
+async def _handle_result_analysis(
+    result: t.Any,
+    cache: ErrorCache,
+    func: t.Callable[..., t.Any],
+    error_type: str | None,
+    auto_analyze: bool,
+) -> None:
+    """Handle result error analysis for async functions."""
+    if not auto_analyze or not isinstance(result, dict):
+        return
+    if "error" in result or "errors" in result:
+        await _analyze_result_errors(cache, result, func, error_type)
+
+
+def _handle_result_analysis_sync(
+    result: t.Any,
+    cache: ErrorCache,
+    func: t.Callable[..., t.Any],
+    error_type: str | None,
+    auto_analyze: bool,
+) -> None:
+    """Handle result error analysis for sync functions."""
+    if not auto_analyze or not isinstance(result, dict):
+        return
+    if "error" in result or "errors" in result:
+        _analyze_result_errors_sync(cache, result, func, error_type)
+
+
+async def _handle_generic_exception(
+    error: Exception,
+    cache: ErrorCache,
+    func: t.Callable[..., t.Any],
+    error_type: str | None,
+    auto_analyze: bool,
+) -> None:
+    """Handle generic exception caching for async functions."""
+    if auto_analyze:
+        await _cache_exception(cache, error, func, error_type)
+
+
+def _handle_generic_exception_sync(
+    error: Exception,
+    cache: ErrorCache,
+    func: t.Callable[..., t.Any],
+    error_type: str | None,
+    auto_analyze: bool,
+) -> None:
+    """Handle generic exception caching for sync functions."""
+    if auto_analyze:
+        _cache_exception_sync(cache, error, func, error_type)
+
+
+async def _analyze_result_errors(
+    cache: ErrorCache,
+    result: dict[str, t.Any],
+    func: t.Callable[..., t.Any],
+    error_type_override: str | None,
+) -> None:
+    """Analyze errors from result dictionary (async)."""
+    error_data = result.get("error") or result.get("errors", "")
+    if isinstance(error_data, str) and error_data:
+        context = get_function_context(func)
+        detected_type = error_type_override or context["function_name"]
+
+        pattern = cache.create_pattern_from_error(error_data, detected_type)
+        if pattern:
+            await cache.add_pattern(pattern)
+
+
+def _analyze_result_errors_sync(
+    cache: ErrorCache,
+    result: dict[str, t.Any],
+    func: t.Callable[..., t.Any],
+    error_type_override: str | None,
+) -> None:
+    """Analyze errors from result dictionary (sync)."""
+    import asyncio
+
+    error_data = result.get("error") or result.get("errors", "")
+    if isinstance(error_data, str) and error_data:
+        context = get_function_context(func)
+        detected_type = error_type_override or context["function_name"]
+
+        pattern = cache.create_pattern_from_error(error_data, detected_type)
+        if pattern:
+            # Run async method in sync context
+            asyncio.run(cache.add_pattern(pattern))
+
+
+async def _cache_crackerjack_error(
+    cache: ErrorCache,
+    error: CrackerjackError,
+    func: t.Callable[..., t.Any],
+    error_type_override: str | None,
+) -> None:
+    """Cache a CrackerjackError (async)."""
+    get_function_context(func)
+    detected_type = error_type_override or error.error_code.name
+
+    pattern = ErrorPattern(
+        pattern_id=f"{detected_type}_{error.error_code.value}_{hash(error.message) % 10000}",
+        error_type=detected_type,
+        error_code=str(error.error_code.value),
+        message_pattern=error.message,
+        common_fixes=[error.recovery] if error.recovery else None,
+        auto_fixable=False,
+    )
+
+    await cache.add_pattern(pattern)
+
+
+def _cache_crackerjack_error_sync(
+    cache: ErrorCache,
+    error: CrackerjackError,
+    func: t.Callable[..., t.Any],
+    error_type_override: str | None,
+) -> None:
+    """Cache a CrackerjackError (sync)."""
+    import asyncio
+
+    get_function_context(func)
+    detected_type = error_type_override or error.error_code.name
+
+    pattern = ErrorPattern(
+        pattern_id=f"{detected_type}_{error.error_code.value}_{hash(error.message) % 10000}",
+        error_type=detected_type,
+        error_code=str(error.error_code.value),
+        message_pattern=error.message,
+        common_fixes=[error.recovery] if error.recovery else None,
+        auto_fixable=False,
+    )
+
+    asyncio.run(cache.add_pattern(pattern))
+
+
+async def _cache_exception(
+    cache: ErrorCache,
+    error: Exception,
+    func: t.Callable[..., t.Any],
+    error_type_override: str | None,
+) -> None:
+    """Cache a generic exception (async)."""
+    get_function_context(func)
+    detected_type = error_type_override or type(error).__name__
+
+    error_message = str(error)
+    pattern = cache.create_pattern_from_error(error_message, detected_type)
+
+    if pattern:
+        await cache.add_pattern(pattern)
+
+
+def _cache_exception_sync(
+    cache: ErrorCache,
+    error: Exception,
+    func: t.Callable[..., t.Any],
+    error_type_override: str | None,
+) -> None:
+    """Cache a generic exception (sync)."""
+    import asyncio
+
+    get_function_context(func)
+    detected_type = error_type_override or type(error).__name__
+
+    error_message = str(error)
+    pattern = cache.create_pattern_from_error(error_message, detected_type)
+
+    if pattern:
+        asyncio.run(cache.add_pattern(pattern))