backon 3.0.0__py3-none-any.whl

backon/__init__.py

@@ -0,0 +1,23 @@
+from backon._common import disable, enable
+from backon._decorator import on_exception, on_predicate
+from backon._jitter import full_jitter, random_jitter
+from backon._retry import Retrying, retry
+from backon._wait_gen import constant, decay, expo, fibo, runtime
+
+__all__ = [
+    "on_predicate",
+    "on_exception",
+    "retry",
+    "Retrying",
+    "constant",
+    "expo",
+    "decay",
+    "fibo",
+    "runtime",
+    "full_jitter",
+    "random_jitter",
+    "disable",
+    "enable",
+]
+
+__version__ = "3.0.0"

backon/_async.py

@@ -0,0 +1,208 @@
+import asyncio
+import functools
+
+from backon._common import (
+    _elapsed,
+    _init_wait_gen,
+    _maybe_call,
+    _next_wait,
+    _now,
+    is_enabled,
+)
+
+
+def _unwrap(target):
+    if isinstance(target, staticmethod):
+        return target.__func__
+    return target
+
+
+def _ensure_coroutine(coro_or_func):
+    if asyncio.iscoroutinefunction(coro_or_func):
+        return coro_or_func
+    else:
+
+        @functools.wraps(coro_or_func)
+        async def f(*args, **kwargs):
+            return coro_or_func(*args, **kwargs)
+
+        return f
+
+
+def _ensure_coroutines(coros_or_funcs):
+    return [_ensure_coroutine(f) for f in coros_or_funcs]
+
+
+async def _call_handlers(handlers, *, target, args, kwargs, tries, elapsed, **extra):
+    details = {
+        "target": target,
+        "args": args,
+        "kwargs": kwargs,
+        "tries": tries,
+        "elapsed": elapsed,
+    }
+    details.update(extra)
+    for handler in handlers:
+        await handler(details)
+
+
+def retry_predicate(
+    target,
+    wait_gen,
+    predicate,
+    *,
+    max_tries,
+    max_time,
+    jitter,
+    on_success,
+    on_backoff,
+    on_giveup,
+    on_attempt,
+    sleep,
+    wait_gen_kwargs,
+):
+    target = _unwrap(target)
+    on_success = _ensure_coroutines(on_success)
+    on_backoff = _ensure_coroutines(on_backoff)
+    on_giveup = _ensure_coroutines(on_giveup)
+    on_attempt = _ensure_coroutines(on_attempt)
+
+    assert not asyncio.iscoroutinefunction(max_tries)
+    assert not asyncio.iscoroutinefunction(jitter)
+
+    assert asyncio.iscoroutinefunction(target)
+
+    @functools.wraps(target)
+    async def retry(*args, **kwargs):
+        if not is_enabled():
+            return await target(*args, **kwargs)
+
+        max_tries_value = _maybe_call(max_tries)
+        max_time_value = _maybe_call(max_time)
+
+        tries = 0
+        start = _now()
+        wait = _init_wait_gen(wait_gen, wait_gen_kwargs)
+        while True:
+            tries += 1
+            elapsed = _elapsed(start)
+            details = {
+                "target": target,
+                "args": args,
+                "kwargs": kwargs,
+                "tries": tries,
+                "elapsed": elapsed,
+            }
+
+            await _call_handlers(on_attempt, **details)
+
+            ret = await target(*args, **kwargs)
+            if predicate(ret):
+                max_tries_exceeded = tries == max_tries_value
+                max_time_exceeded = (
+                    max_time_value is not None and elapsed >= max_time_value
+                )
+
+                if max_tries_exceeded or max_time_exceeded:
+                    await _call_handlers(on_giveup, **details, value=ret)
+                    break
+
+                try:
+                    seconds = _next_wait(wait, ret, jitter, elapsed, max_time_value)
+                except StopIteration:
+                    await _call_handlers(on_giveup, **details, value=ret)
+                    break
+
+                await _call_handlers(on_backoff, **details, value=ret, wait=seconds)
+
+                await sleep(seconds)
+                continue
+            else:
+                await _call_handlers(on_success, **details, value=ret)
+                break
+
+        return ret
+
+    return retry
+
+
+def retry_exception(
+    target,
+    wait_gen,
+    exception,
+    *,
+    max_tries,
+    max_time,
+    jitter,
+    giveup,
+    on_success,
+    on_backoff,
+    on_giveup,
+    on_attempt,
+    raise_on_giveup,
+    sleep,
+    wait_gen_kwargs,
+):
+    target = _unwrap(target)
+    on_success = _ensure_coroutines(on_success)
+    on_backoff = _ensure_coroutines(on_backoff)
+    on_giveup = _ensure_coroutines(on_giveup)
+    on_attempt = _ensure_coroutines(on_attempt)
+    giveup = _ensure_coroutine(giveup)
+
+    assert not asyncio.iscoroutinefunction(max_tries)
+    assert not asyncio.iscoroutinefunction(jitter)
+
+    @functools.wraps(target)
+    async def retry(*args, **kwargs):
+        if not is_enabled():
+            return await target(*args, **kwargs)
+
+        max_tries_value = _maybe_call(max_tries)
+        max_time_value = _maybe_call(max_time)
+
+        tries = 0
+        start = _now()
+        wait = _init_wait_gen(wait_gen, wait_gen_kwargs)
+        while True:
+            tries += 1
+            elapsed = _elapsed(start)
+            details = {
+                "target": target,
+                "args": args,
+                "kwargs": kwargs,
+                "tries": tries,
+                "elapsed": elapsed,
+            }
+
+            await _call_handlers(on_attempt, **details)
+
+            try:
+                ret = await target(*args, **kwargs)
+            except exception as e:
+                giveup_result = await giveup(e)
+                max_tries_exceeded = tries == max_tries_value
+                max_time_exceeded = (
+                    max_time_value is not None and elapsed >= max_time_value
+                )
+
+                if giveup_result or max_tries_exceeded or max_time_exceeded:
+                    await _call_handlers(on_giveup, **details, exception=e)
+                    if raise_on_giveup:
+                        raise
+                    return None
+
+                try:
+                    seconds = _next_wait(wait, e, jitter, elapsed, max_time_value)
+                except StopIteration:
+                    await _call_handlers(on_giveup, **details, exception=e)
+                    raise e
+
+                await _call_handlers(on_backoff, **details, wait=seconds, exception=e)
+
+                await sleep(seconds)
+            else:
+                await _call_handlers(on_success, **details)
+                return ret
+
+    return retry

backon/_common.py

@@ -0,0 +1,117 @@
+import functools
+import logging
+import sys
+import time as time_module
+import traceback
+
+_logger = logging.getLogger("backon")
+_logger.addHandler(logging.NullHandler())
+
+_GLOBAL_ENABLED = True
+
+
+def disable():
+    global _GLOBAL_ENABLED
+    _GLOBAL_ENABLED = False
+
+
+def enable():
+    global _GLOBAL_ENABLED
+    _GLOBAL_ENABLED = True
+
+
+def is_enabled():
+    return _GLOBAL_ENABLED
+
+
+def _maybe_call(f, *args, **kwargs):
+    if callable(f):
+        try:
+            return f(*args, **kwargs)
+        except TypeError:
+            return f
+    else:
+        return f
+
+
+def _init_wait_gen(wait_gen, wait_gen_kwargs):
+    kwargs = {k: _maybe_call(v) for k, v in wait_gen_kwargs.items()}
+    initialized = wait_gen(**kwargs)
+    initialized.send(None)
+    return initialized
+
+
+def _next_wait(wait, send_value, jitter, elapsed, max_time):
+    value = wait.send(send_value)
+    if jitter is not None:
+        seconds = jitter(value)
+    else:
+        seconds = value
+
+    if max_time is not None:
+        seconds = min(seconds, max_time - elapsed)
+
+    return seconds
+
+
+def _prepare_logger(logger):
+    if isinstance(logger, str):
+        logger = logging.getLogger(logger)
+    return logger
+
+
+def _config_handlers(
+    user_handlers, *, default_handler=None, logger=None, log_level=None
+):
+    handlers = []
+    if logger is not None:
+        assert log_level is not None
+        log_handler = functools.partial(
+            default_handler, logger=logger, log_level=log_level
+        )
+        handlers.append(log_handler)
+
+    if user_handlers is None:
+        return handlers
+
+    if hasattr(user_handlers, "__iter__"):
+        handlers += list(user_handlers)
+    else:
+        handlers.append(user_handlers)
+
+    return handlers
+
+
+def _log_backoff(details, logger, log_level):
+    msg = "Backing off %s(...) for %.1fs (%s)"
+    log_args = [details["target"].__name__, details["wait"]]
+
+    exc_typ, exc, _ = sys.exc_info()
+    if exc is not None:
+        exc_fmt = traceback.format_exception_only(exc_typ, exc)[-1]
+        log_args.append(exc_fmt.rstrip("\n"))
+    else:
+        log_args.append(details["value"])
+    logger.log(log_level, msg, *log_args)
+
+
+def _log_giveup(details, logger, log_level):
+    msg = "Giving up %s(...) after %d tries (%s)"
+    log_args = [details["target"].__name__, details["tries"]]
+
+    exc_typ, exc, _ = sys.exc_info()
+    if exc is not None:
+        exc_fmt = traceback.format_exception_only(exc_typ, exc)[-1]
+        log_args.append(exc_fmt.rstrip("\n"))
+    else:
+        log_args.append(details["value"])
+
+    logger.log(log_level, msg, *log_args)
+
+
+def _now():
+    return time_module.monotonic()
+
+
+def _elapsed(start):
+    return _now() - start

backon/_decorator.py

@@ -0,0 +1,150 @@
+import asyncio
+import logging
+import operator
+import time as time_module
+from typing import Any, Callable, Iterable, Optional, Type, Union
+
+from backon import _async, _sync
+from backon._common import (
+    _config_handlers,
+    _log_backoff,
+    _log_giveup,
+    _prepare_logger,
+)
+from backon._jitter import full_jitter
+from backon._typing import (
+    _CallableT,
+    _Handler,
+    _Jitterer,
+    _MaybeCallable,
+    _MaybeLogger,
+    _MaybeSequence,
+    _Predicate,
+    _WaitGenerator,
+)
+
+
+def on_predicate(
+    wait_gen: _WaitGenerator,
+    predicate: _Predicate[Any] = operator.not_,
+    *,
+    max_tries: Optional[_MaybeCallable[int]] = None,
+    max_time: Optional[_MaybeCallable[float]] = None,
+    jitter: Union[_Jitterer, None] = full_jitter,
+    on_success: Union[_Handler, Iterable[_Handler], None] = None,
+    on_backoff: Union[_Handler, Iterable[_Handler], None] = None,
+    on_giveup: Union[_Handler, Iterable[_Handler], None] = None,
+    on_attempt: Union[_Handler, Iterable[_Handler], None] = None,
+    logger: _MaybeLogger = "backon",
+    backoff_log_level: int = logging.INFO,
+    giveup_log_level: int = logging.ERROR,
+    sleep: Optional[Callable[[float], Any]] = None,
+    **wait_gen_kwargs: Any,
+) -> Callable[[_CallableT], _CallableT]:
+    def decorate(target):
+        nonlocal logger, on_success, on_backoff, on_giveup, on_attempt
+
+        logger = _prepare_logger(logger)
+        on_success = _config_handlers(on_success)
+        on_backoff = _config_handlers(
+            on_backoff,
+            default_handler=_log_backoff,
+            logger=logger,
+            log_level=backoff_log_level,
+        )
+        on_giveup = _config_handlers(
+            on_giveup,
+            default_handler=_log_giveup,
+            logger=logger,
+            log_level=giveup_log_level,
+        )
+        on_attempt = _config_handlers(on_attempt)
+
+        if asyncio.iscoroutinefunction(target):
+            retry = _async.retry_predicate
+            _sleep = sleep or asyncio.sleep
+        else:
+            retry = _sync.retry_predicate
+            _sleep = sleep or time_module.sleep
+
+        return retry(
+            target,
+            wait_gen,
+            predicate,
+            max_tries=max_tries,
+            max_time=max_time,
+            jitter=jitter,
+            on_success=on_success,
+            on_backoff=on_backoff,
+            on_giveup=on_giveup,
+            on_attempt=on_attempt,
+            sleep=_sleep,
+            wait_gen_kwargs=wait_gen_kwargs,
+        )
+
+    return decorate
+
+
+def on_exception(
+    wait_gen: _WaitGenerator,
+    exception: _MaybeSequence[Type[Exception]],
+    *,
+    max_tries: Optional[_MaybeCallable[int]] = None,
+    max_time: Optional[_MaybeCallable[float]] = None,
+    jitter: Union[_Jitterer, None] = full_jitter,
+    giveup: _Predicate[Exception] = lambda e: False,
+    on_success: Union[_Handler, Iterable[_Handler], None] = None,
+    on_backoff: Union[_Handler, Iterable[_Handler], None] = None,
+    on_giveup: Union[_Handler, Iterable[_Handler], None] = None,
+    on_attempt: Union[_Handler, Iterable[_Handler], None] = None,
+    raise_on_giveup: bool = True,
+    logger: _MaybeLogger = "backon",
+    backoff_log_level: int = logging.INFO,
+    giveup_log_level: int = logging.ERROR,
+    sleep: Optional[Callable[[float], Any]] = None,
+    **wait_gen_kwargs: Any,
+) -> Callable[[_CallableT], _CallableT]:
+    def decorate(target):
+        nonlocal logger, on_success, on_backoff, on_giveup, on_attempt
+
+        logger = _prepare_logger(logger)
+        on_success = _config_handlers(on_success)
+        on_backoff = _config_handlers(
+            on_backoff,
+            default_handler=_log_backoff,
+            logger=logger,
+            log_level=backoff_log_level,
+        )
+        on_giveup = _config_handlers(
+            on_giveup,
+            default_handler=_log_giveup,
+            logger=logger,
+            log_level=giveup_log_level,
+        )
+        on_attempt = _config_handlers(on_attempt)
+
+        if asyncio.iscoroutinefunction(target):
+            retry = _async.retry_exception
+            _sleep = sleep or asyncio.sleep
+        else:
+            retry = _sync.retry_exception
+            _sleep = sleep or time_module.sleep
+
+        return retry(
+            target,
+            wait_gen,
+            exception,
+            max_tries=max_tries,
+            max_time=max_time,
+            jitter=jitter,
+            giveup=giveup,
+            on_success=on_success,
+            on_backoff=on_backoff,
+            on_giveup=on_giveup,
+            on_attempt=on_attempt,
+            raise_on_giveup=raise_on_giveup,
+            sleep=_sleep,
+            wait_gen_kwargs=wait_gen_kwargs,
+        )
+
+    return decorate

backon/_jitter.py

@@ -0,0 +1,9 @@
+import random
+
+
+def random_jitter(value: float) -> float:
+    return value + random.random()
+
+
+def full_jitter(value: float) -> float:
+    return random.uniform(0, value)