errortools 1.2.0__tar.gz → 1.3.0__tar.gz

{errortools-1.2.0/errortools.egg-info → errortools-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: errortools
-Version: 1.2.0
+Version: 1.3.0
 Summary: errortools - a toolset for working with Python exceptions and warnings and logging.
 Home-page: https://github.com/more-abc/errortools
 Author: Evan Yang
@@ -35,7 +35,7 @@ A lightweight Python exception handling utility library.
 
 ## Features
 - **Raise Exceptions**: `raises()`, `raises_all()`, `reraise()` — batch raising and exception conversion
-- **Catch & Suppress**: `ignore()`, `ignore_subclass()`, `ignore_warns()`, `fast_ignore()`, `super_fast_ignore()`, `timeout()` — graceful suppression of exceptions and warnings
+- **Catch & Suppress**: `ignore()`, `ignore_subclass()`, `ignore_warns()`, `fast_ignore()`, `super_fast_ignore()`, `timeout()`, `retry()` — graceful suppression of exceptions and warnings, with automatic retry
 - **Exception Caching**: `error_cache` — cache exceptions raised by functions (similar to `lru_cache`)
 - **Custom Exceptions**: `PureBaseException`, `ContextException`, `BaseErrorCodes`, `BaseWarning` — structured exception classes with error codes, trace IDs, and context
 - **Attribute Error Mixin**: Customize error behavior for attribute access, assignment, and deletion
@@ -54,7 +54,7 @@ pip install errortools
 ```python
 import warnings
 from errortools import (
-    ignore, fast_ignore, ignore_subclass, ignore_warns, timeout,
+    ignore, fast_ignore, ignore_subclass, ignore_warns, timeout, retry,
     reraise, raises, raises_all, assert_raises,
     error_cache,
     PureBaseException, ContextException, BaseErrorCodes, BaseWarning,
@@ -103,14 +103,29 @@ async def fetch_data(url: str) -> bytes:
 
 # asyncio.TimeoutError raised automatically if it exceeds 5 s
 
-# ── 6. reraise ── convert exception types on the fly ─────────────────────────
+# ── 6. retry ── automatically retry on failure ───────────────────────────────
+@retry(times=3, on=ConnectionError, delay=1.0)
+def connect(host: str) -> None:
+    ...                               # retried up to 3 times on ConnectionError
+
+# works with async functions too
+@retry(times=5, on=TimeoutError, delay=0.5)
+async def fetch(url: str) -> bytes:
+    ...
+
+# multiple exception types
+@retry(times=2, on=(ValueError, KeyError))
+def parse(data: dict) -> str:
+    return data["key"]
+
+# ── 7. reraise ── convert exception types on the fly ─────────────────────────
 with reraise(KeyError, ValueError):
     raise KeyError("missing key")      # → ValueError: 'missing key'
 
 with reraise((KeyError, IndexError), RuntimeError):
     _ = [][99]                         # → RuntimeError: list index out of range
 
-# ── 7. raises / raises_all ── batch raise ────────────────────────────────────
+# ── 8. raises / raises_all ── batch raise ────────────────────────────────────
 raises([ValueError], ["bad input"])    # → ValueError: bad input
 
 raises_all(
@@ -118,11 +133,11 @@ raises_all(
     ["bad input"],
 )                                      # → ExceptionGroup (2 sub-exceptions)
 
-# ── 8. assert_raises ── assert a callable raises ─────────────────────────────
+# ── 9. assert_raises ── assert a callable raises ─────────────────────────────
 exc = assert_raises(int, [ValueError], "not-a-number")
 print(exc)   # invalid literal for int() with base 10: 'not-a-number'
 
-# ── 9. error_cache ── cache exceptions by call arguments ─────────────────────
+# ── 10. error_cache ── cache exceptions by call arguments ─────────────────────
 @error_cache(maxsize=64)
 def load(user_id: int) -> dict:
     if user_id < 0:
@@ -135,7 +150,7 @@ with ignore(ValueError):
 print(load.cache_info())  # CacheInfo(hits=0, misses=1, maxsize=64, currsize=1)
 load.clear_cache()
 
-# ── 10. Custom exceptions — three layers ──────────────────────────────────────
+# ── 11. Custom exceptions — three layers ──────────────────────────────────────
 
 # Layer 1: PureBaseException — code + detail only
 class AppError(PureBaseException):
@@ -171,7 +186,7 @@ raise BaseErrorCodes.runtime_failure("crash")             # RuntimeFailure     [
 raise BaseErrorCodes.timeout_failure()                    # TimeoutFailure     [4002]
 raise BaseErrorCodes.configuration_error("missing key")   # ConfigurationError [5001]
 
-# ── 11. BaseWarning ── structured warnings with factory methods ───────────────
+# ── 12. BaseWarning ── structured warnings with factory methods ───────────────
 class ExperimentalWarning(BaseWarning):
     default_detail = "This feature is experimental."
 

{errortools-1.2.0 → errortools-1.3.0}/README.md

@@ -3,7 +3,7 @@ A lightweight Python exception handling utility library.
 
 ## Features
 - **Raise Exceptions**: `raises()`, `raises_all()`, `reraise()` — batch raising and exception conversion
-- **Catch & Suppress**: `ignore()`, `ignore_subclass()`, `ignore_warns()`, `fast_ignore()`, `super_fast_ignore()`, `timeout()` — graceful suppression of exceptions and warnings
+- **Catch & Suppress**: `ignore()`, `ignore_subclass()`, `ignore_warns()`, `fast_ignore()`, `super_fast_ignore()`, `timeout()`, `retry()` — graceful suppression of exceptions and warnings, with automatic retry
 - **Exception Caching**: `error_cache` — cache exceptions raised by functions (similar to `lru_cache`)
 - **Custom Exceptions**: `PureBaseException`, `ContextException`, `BaseErrorCodes`, `BaseWarning` — structured exception classes with error codes, trace IDs, and context
 - **Attribute Error Mixin**: Customize error behavior for attribute access, assignment, and deletion
@@ -22,7 +22,7 @@ pip install errortools
 ```python
 import warnings
 from errortools import (
-    ignore, fast_ignore, ignore_subclass, ignore_warns, timeout,
+    ignore, fast_ignore, ignore_subclass, ignore_warns, timeout, retry,
     reraise, raises, raises_all, assert_raises,
     error_cache,
     PureBaseException, ContextException, BaseErrorCodes, BaseWarning,
@@ -71,14 +71,29 @@ async def fetch_data(url: str) -> bytes:
 
 # asyncio.TimeoutError raised automatically if it exceeds 5 s
 
-# ── 6. reraise ── convert exception types on the fly ─────────────────────────
+# ── 6. retry ── automatically retry on failure ───────────────────────────────
+@retry(times=3, on=ConnectionError, delay=1.0)
+def connect(host: str) -> None:
+    ...                               # retried up to 3 times on ConnectionError
+
+# works with async functions too
+@retry(times=5, on=TimeoutError, delay=0.5)
+async def fetch(url: str) -> bytes:
+    ...
+
+# multiple exception types
+@retry(times=2, on=(ValueError, KeyError))
+def parse(data: dict) -> str:
+    return data["key"]
+
+# ── 7. reraise ── convert exception types on the fly ─────────────────────────
 with reraise(KeyError, ValueError):
     raise KeyError("missing key")      # → ValueError: 'missing key'
 
 with reraise((KeyError, IndexError), RuntimeError):
     _ = [][99]                         # → RuntimeError: list index out of range
 
-# ── 7. raises / raises_all ── batch raise ────────────────────────────────────
+# ── 8. raises / raises_all ── batch raise ────────────────────────────────────
 raises([ValueError], ["bad input"])    # → ValueError: bad input
 
 raises_all(
@@ -86,11 +101,11 @@ raises_all(
     ["bad input"],
 )                                      # → ExceptionGroup (2 sub-exceptions)
 
-# ── 8. assert_raises ── assert a callable raises ─────────────────────────────
+# ── 9. assert_raises ── assert a callable raises ─────────────────────────────
 exc = assert_raises(int, [ValueError], "not-a-number")
 print(exc)   # invalid literal for int() with base 10: 'not-a-number'
 
-# ── 9. error_cache ── cache exceptions by call arguments ─────────────────────
+# ── 10. error_cache ── cache exceptions by call arguments ─────────────────────
 @error_cache(maxsize=64)
 def load(user_id: int) -> dict:
     if user_id < 0:
@@ -103,7 +118,7 @@ with ignore(ValueError):
 print(load.cache_info())  # CacheInfo(hits=0, misses=1, maxsize=64, currsize=1)
 load.clear_cache()
 
-# ── 10. Custom exceptions — three layers ──────────────────────────────────────
+# ── 11. Custom exceptions — three layers ──────────────────────────────────────
 
 # Layer 1: PureBaseException — code + detail only
 class AppError(PureBaseException):
@@ -139,7 +154,7 @@ raise BaseErrorCodes.runtime_failure("crash")             # RuntimeFailure     [
 raise BaseErrorCodes.timeout_failure()                    # TimeoutFailure     [4002]
 raise BaseErrorCodes.configuration_error("missing key")   # ConfigurationError [5001]
 
-# ── 11. BaseWarning ── structured warnings with factory methods ───────────────
+# ── 12. BaseWarning ── structured warnings with factory methods ───────────────
 class ExperimentalWarning(BaseWarning):
     default_detail = "This feature is experimental."
 

{errortools-1.2.0 → errortools-1.3.0}/_errortools/cache.py

@@ -1,81 +1,82 @@
-"""A helper tool for caching exceptions raised by functions."""
-
-import functools
-from typing import (
-    Callable,
-    Any,
-    Optional,
-    TypeVar,
-    overload,
-)
-
-from .wrappers.cache import ErrorCacheWrapper
-
-_T = TypeVar("_T", bound=Callable[..., Any])
-
-# fmt: off
-
-
-@overload
-def error_cache(func: _T) -> ErrorCacheWrapper[_T]:
-    ...
-
-
-@overload
-def error_cache(maxsize: Optional[int] = 128) -> Callable[[_T], ErrorCacheWrapper[_T]]:
-    ...
-# fmt: on
-
-
-def error_cache(  # type: ignore
-    func: Optional[_T] = None, maxsize: Optional[int] = 128
-) -> Any:
-    """
-    Decorator to cache exceptions raised by a function.
-
-    Usage:
-
-        @error_cache  # Default maxsize=128
-        def risky_func(x: int) -> int: ...
-
-        @error_cache(maxsize=32)  # Custom maxsize
-        def risky_func(x: int) -> int: ...
-
-        @error_cache(maxsize=None)  # Unlimited cache
-        def risky_func(x: int) -> int: ...
-
-        @error_cache()  # Explicit empty args (maxsize=128)
-        def risky_func(x: int) -> int: ...
-
-    Args:
-        func: The function to wrap (auto-passed when using @error_cache without args).
-        maxsize: Maximum number of cached errors (None = unlimited, default=128).
-
-    Returns:
-        Wrapped function with error caching functionality.
-
-    Raises:
-        TypeError: If non-hashable arguments are passed.
-    """
-
-    # NOTE: This decorator automatically caches exceptions thrown by the wrapped function,
-    # keyed by the function's arguments. If the function succeeds, the cached exception
-    # (if any) for those arguments is removed.
-
-    # Key features:
-    # - maxsize: Maximum number of cached errors (None = unlimited, default=128)
-    # - LRU eviction: Evicts least recently used entries when maxsize is reached
-    # - cache_info(): Returns hits/misses/maxsize/currsize stats
-    # - clear_cache(): Clears cache and resets statistics
-    def decorator(f: _T) -> ErrorCacheWrapper[_T]:
-        if not callable(f):
-            raise TypeError(f"Expected a callable, got {type(f).__name__} instead")
-
-        wrapper = ErrorCacheWrapper(f, maxsize=maxsize)
-        functools.update_wrapper(wrapper, f)
-        return wrapper
-
-    # Handle both @error_cache and @error_cache(...) usage
-    if func is None:
-        return decorator
-    return decorator(func)
+"""A helper tool for caching exceptions raised by functions."""
+
+import functools
+from typing import (
+    Callable,
+    Any,
+    Optional,
+    TypeVar,
+    overload,
+)
+
+from .const import DEFAULT_ERROR_CACHE_SIZE
+from .wrappers.cache import ErrorCacheWrapper
+
+_T = TypeVar("_T", bound=Callable[..., Any])
+
+# fmt: off
+
+
+@overload
+def error_cache(func: _T) -> ErrorCacheWrapper[_T]:
+    ...
+
+
+@overload
+def error_cache(maxsize: Optional[int] = 128) -> Callable[[_T], ErrorCacheWrapper[_T]]:
+    ...
+# fmt: on
+
+
+def error_cache(  # type: ignore
+    func: Optional[_T] = None, maxsize: Optional[int] = DEFAULT_ERROR_CACHE_SIZE
+) -> Any:
+    """
+    Decorator to cache exceptions raised by a function.
+
+    Usage:
+
+        @error_cache  # Default maxsize=128
+        def risky_func(x: int) -> int: ...
+
+        @error_cache(maxsize=32)  # Custom maxsize
+        def risky_func(x: int) -> int: ...
+
+        @error_cache(maxsize=None)  # Unlimited cache
+        def risky_func(x: int) -> int: ...
+
+        @error_cache()  # Explicit empty args (maxsize=128)
+        def risky_func(x: int) -> int: ...
+
+    Args:
+        func: The function to wrap (auto-passed when using @error_cache without args).
+        maxsize: Maximum number of cached errors (None = unlimited, default=128).
+
+    Returns:
+        Wrapped function with error caching functionality.
+
+    Raises:
+        TypeError: If non-hashable arguments are passed.
+    """
+
+    # NOTE: This decorator automatically caches exceptions thrown by the wrapped function,
+    # keyed by the function's arguments. If the function succeeds, the cached exception
+    # (if any) for those arguments is removed.
+
+    # Key features:
+    # - maxsize: Maximum number of cached errors (None = unlimited, default=128)
+    # - LRU eviction: Evicts least recently used entries when maxsize is reached
+    # - cache_info(): Returns hits/misses/maxsize/currsize stats
+    # - clear_cache(): Clears cache and resets statistics
+    def decorator(f: _T) -> ErrorCacheWrapper[_T]:
+        if not callable(f):
+            raise TypeError(f"Expected a callable, got {type(f).__name__} instead")
+
+        wrapper = ErrorCacheWrapper(f, maxsize=maxsize)
+        functools.update_wrapper(wrapper, f)
+        return wrapper
+
+    # Handle both @error_cache and @error_cache(...) usage
+    if func is None:
+        return decorator
+    return decorator(func)