python-backoff 2.2.2rc1__py3-none-any.whl

backoff/__init__.py

@@ -0,0 +1,31 @@
+# coding:utf-8
+"""
+Function decoration for backoff and retry
+
+This module provides function decorators which can be used to wrap a
+function such that it will be retried until some condition is met. It
+is meant to be of use when accessing unreliable resources with the
+potential for intermittent failures i.e. network resources and external
+APIs. Somewhat more generally, it may also be of use for dynamically
+polling resources for externally generated content.
+
+For examples and full documentation see the README at
+https://github.com/python-backoff/backoff
+"""
+from backoff._decorator import on_exception, on_predicate
+from backoff._jitter import full_jitter, random_jitter
+from backoff._wait_gen import constant, expo, fibo, runtime, decay
+
+__all__ = [
+    'on_predicate',
+    'on_exception',
+    'constant',
+    'expo',
+    'decay',
+    'fibo',
+    'runtime',
+    'full_jitter',
+    'random_jitter',
+]
+
+__version__ = "2.2.1"

backoff/_async.py

@@ -0,0 +1,189 @@
+# coding:utf-8
+import datetime
+import functools
+import asyncio
+import inspect
+from datetime import timedelta
+
+from backoff._common import (_init_wait_gen, _maybe_call, _next_wait)
+
+
+def _ensure_coroutine(coro_or_func):
+    if inspect.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,
+                    wait_gen_kwargs):
+    on_success = _ensure_coroutines(on_success)
+    on_backoff = _ensure_coroutines(on_backoff)
+    on_giveup = _ensure_coroutines(on_giveup)
+
+    # Easy to implement, please report if you need this.
+    assert not inspect.iscoroutinefunction(max_tries)
+    assert not inspect.iscoroutinefunction(jitter)
+
+    assert inspect.iscoroutinefunction(target)
+
+    @functools.wraps(target)
+    async def retry(*args, **kwargs):
+
+        # update variables from outer function args
+        max_tries_value = _maybe_call(max_tries)
+        max_time_value = _maybe_call(max_time)
+
+        tries = 0
+        start = datetime.datetime.now()
+        wait = _init_wait_gen(wait_gen, wait_gen_kwargs)
+        while True:
+            tries += 1
+            elapsed = timedelta.total_seconds(datetime.datetime.now() - start)
+            details = {
+                "target": target,
+                "args": args,
+                "kwargs": kwargs,
+                "tries": tries,
+                "elapsed": elapsed,
+            }
+
+            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)
+
+                # Note: there is no convenient way to pass explicit event
+                # loop to decorator, so here we assume that either default
+                # thread event loop is set and correct (it mostly is
+                # by default), or Python >= 3.5.3 or Python >= 3.6 is used
+                # where loop.get_event_loop() in coroutine guaranteed to
+                # return correct value.
+                # See for details:
+                #   <https://groups.google.com/forum/#!topic/python-tulip/yF9C-rFpiKk>
+                #   <https://bugs.python.org/issue28613>
+                await asyncio.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, raise_on_giveup,
+                    wait_gen_kwargs):
+    on_success = _ensure_coroutines(on_success)
+    on_backoff = _ensure_coroutines(on_backoff)
+    on_giveup = _ensure_coroutines(on_giveup)
+    giveup = _ensure_coroutine(giveup)
+
+    # Easy to implement, please report if you need this.
+    assert not inspect.iscoroutinefunction(max_tries)
+    assert not inspect.iscoroutinefunction(jitter)
+
+    @functools.wraps(target)
+    async def retry(*args, **kwargs):
+
+        max_tries_value = _maybe_call(max_tries)
+        max_time_value = _maybe_call(max_time)
+
+        tries = 0
+        start = datetime.datetime.now()
+        wait = _init_wait_gen(wait_gen, wait_gen_kwargs)
+        while True:
+            tries += 1
+            elapsed = timedelta.total_seconds(datetime.datetime.now() - start)
+            details = {
+                "target": target,
+                "args": args,
+                "kwargs": kwargs,
+                "tries": tries,
+                "elapsed": elapsed,
+            }
+
+            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)
+
+                # Note: there is no convenient way to pass explicit event
+                # loop to decorator, so here we assume that either default
+                # thread event loop is set and correct (it mostly is
+                # by default), or Python >= 3.5.3 or Python >= 3.6 is used
+                # where loop.get_event_loop() in coroutine guaranteed to
+                # return correct value.
+                # See for details:
+                #   <https://groups.google.com/forum/#!topic/python-tulip/yF9C-rFpiKk>
+                #   <https://bugs.python.org/issue28613>
+                await asyncio.sleep(seconds)
+            else:
+                await _call_handlers(on_success, **details)
+
+                return ret
+    return retry

backoff/_common.py

@@ -0,0 +1,120 @@
+# coding:utf-8
+
+import functools
+import logging
+import sys
+import traceback
+import warnings
+
+
+# Use module-specific logger with a default null handler.
+_logger = logging.getLogger('backoff')
+_logger.addHandler(logging.NullHandler())  # pragma: no cover
+_logger.setLevel(logging.INFO)
+
+
+# Evaluate arg that can be either a fixed value or a callable.
+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)  # Initialize with an empty send
+    return initialized
+
+
+def _next_wait(wait, send_value, jitter, elapsed, max_time):
+    value = wait.send(send_value)
+    try:
+        if jitter is not None:
+            seconds = jitter(value)
+        else:
+            seconds = value
+    except TypeError:
+        warnings.warn(
+            "Nullary jitter function signature is deprecated. Use "
+            "unary signature accepting a wait value in seconds and "
+            "returning a jittered version of it.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+        seconds = value + jitter()
+
+    # don't sleep longer than remaining allotted max_time
+    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
+
+
+# Configure handler list with user specified handler and optionally
+# with a default handler bound to the specified 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 level is not specified"
+        # bind the specified logger to the default log handler
+        log_handler = functools.partial(
+            default_handler, logger=logger, log_level=log_level
+        )
+        handlers.append(log_handler)
+
+    if user_handlers is None:
+        return handlers
+
+    # user specified handlers can either be an iterable of handlers
+    # or a single handler. either way append them to the list.
+    if hasattr(user_handlers, '__iter__'):
+        # add all handlers in the iterable
+        handlers += list(user_handlers)
+    else:
+        # append a single handler
+        handlers.append(user_handlers)
+
+    return handlers
+
+
+# Default backoff handler
+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)
+
+
+# Default giveup handler
+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)

backoff/_decorator.py

@@ -0,0 +1,222 @@
+# coding:utf-8
+import inspect
+import logging
+import operator
+from typing import Any, Callable, Iterable, Optional, Type, Union
+
+from backoff._common import (
+    _prepare_logger,
+    _config_handlers,
+    _log_backoff,
+    _log_giveup
+)
+from backoff._jitter import full_jitter
+from backoff import _async, _sync
+from backoff._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,
+                 logger: _MaybeLogger = 'backoff',
+                 backoff_log_level: int = logging.INFO,
+                 giveup_log_level: int = logging.ERROR,
+                 **wait_gen_kwargs: Any) -> Callable[[_CallableT], _CallableT]:
+    """Returns decorator for backoff and retry triggered by predicate.
+
+    Args:
+        wait_gen: A generator yielding successive wait times in
+            seconds.
+        predicate: A function which when called on the return value of
+            the target function will trigger backoff when considered
+            truthily. If not specified, the default behavior is to
+            backoff on falsey return values.
+        max_tries: The maximum number of attempts to make before giving
+            up. In the case of failure, the result of the last attempt
+            will be returned. The default value of None means there
+            is no limit to the number of tries. If a callable is passed,
+            it will be evaluated at runtime and its return value used.
+        max_time: The maximum total amount of time in seconds to try for before
+            giving up. If this time expires, the result of the last
+            attempt will be returned. If a callable is passed, it will
+            be evaluated at runtime and its return value used.
+        jitter: A function of the value yielded by wait_gen returning
+            the actual time to wait. This distributes wait times
+            stochastically in order to avoid timing collisions across
+            concurrent clients. Wait times are jittered by default
+            using the full_jitter function. Jittering may be disabled
+            altogether by passing jitter=None.
+        on_success: Callable (or iterable of callables) with a unary
+            signature to be called in the event of success. The
+            parameter is a dict containing details about the invocation.
+        on_backoff: Callable (or iterable of callables) with a unary
+            signature to be called in the event of a backoff. The
+            parameter is a dict containing details about the invocation.
+        on_giveup: Callable (or iterable of callables) with a unary
+            signature to be called in the event that max_tries
+            is exceeded.  The parameter is a dict containing details
+            about the invocation.
+        logger: Name of logger or Logger object to log to. Defaults to
+            'backoff'.
+        backoff_log_level: log level for the backoff event. Defaults to "INFO"
+        giveup_log_level: log level for the give up event. Defaults to "ERROR"
+        **wait_gen_kwargs: Any additional keyword args specified will be
+            passed to wait_gen when it is initialized.  Any callable
+            args will first be evaluated and their return values passed.
+            This is useful for runtime configuration.
+    """
+    def decorate(target):
+        nonlocal logger, on_success, on_backoff, on_giveup
+
+        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
+        )
+
+        if inspect.iscoroutinefunction(target):
+            retry = _async.retry_predicate
+        else:
+            retry = _sync.retry_predicate
+
+        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,
+            wait_gen_kwargs=wait_gen_kwargs
+        )
+
+    # Return a function which decorates a target with a retry loop.
+    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,
+                 raise_on_giveup: bool = True,
+                 logger: _MaybeLogger = 'backoff',
+                 backoff_log_level: int = logging.INFO,
+                 giveup_log_level: int = logging.ERROR,
+                 **wait_gen_kwargs: Any) -> Callable[[_CallableT], _CallableT]:
+    """Returns decorator for backoff and retry triggered by exception.
+
+    Args:
+        wait_gen: A generator yielding successive wait times in
+            seconds.
+        exception: An exception type (or tuple of types) which triggers
+            backoff.
+        max_tries: The maximum number of attempts to make before giving
+            up. Once exhausted, the exception will be allowed to escape.
+            The default value of None means there is no limit to the
+            number of tries. If a callable is passed, it will be
+            evaluated at runtime and its return value used.
+        max_time: The maximum total amount of time to try for before
+            giving up. Once expired, the exception will be allowed to
+            escape. If a callable is passed, it will be
+            evaluated at runtime and its return value used.
+        jitter: A function of the value yielded by wait_gen returning
+            the actual time to wait. This distributes wait times
+            stochastically in order to avoid timing collisions across
+            concurrent clients. Wait times are jittered by default
+            using the full_jitter function. Jittering may be disabled
+            altogether by passing jitter=None.
+        giveup: Function accepting an exception instance and
+            returning whether or not to give up. Optional. The default
+            is to always continue.
+        on_success: Callable (or iterable of callables) with a unary
+            signature to be called in the event of success. The
+            parameter is a dict containing details about the invocation.
+        on_backoff: Callable (or iterable of callables) with a unary
+            signature to be called in the event of a backoff. The
+            parameter is a dict containing details about the invocation.
+        on_giveup: Callable (or iterable of callables) with a unary
+            signature to be called in the event that max_tries
+            is exceeded.  The parameter is a dict containing details
+            about the invocation.
+        raise_on_giveup: Boolean indicating whether the registered exceptions
+            should be raised on giveup. Defaults to `True`
+        logger: Name or Logger object to log to. Defaults to 'backoff'.
+        backoff_log_level: log level for the backoff event. Defaults to "INFO"
+        giveup_log_level: log level for the give up event. Defaults to "ERROR"
+        **wait_gen_kwargs: Any additional keyword args specified will be
+            passed to wait_gen when it is initialized.  Any callable
+            args will first be evaluated and their return values passed.
+            This is useful for runtime configuration.
+    """
+    def decorate(target):
+        nonlocal logger, on_success, on_backoff, on_giveup
+
+        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,
+        )
+
+        if inspect.iscoroutinefunction(target):
+            retry = _async.retry_exception
+        else:
+            retry = _sync.retry_exception
+
+        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,
+            raise_on_giveup=raise_on_giveup,
+            wait_gen_kwargs=wait_gen_kwargs
+        )
+
+    # Return a function which decorates a target with a retry loop.
+    return decorate

backoff/_jitter.py

@@ -0,0 +1,28 @@
+# coding:utf-8
+
+import random
+
+
+def random_jitter(value: float) -> float:
+    """Jitter the value a random number of milliseconds.
+
+    This adds up to 1 second of additional time to the original value.
+    Prior to backoff version 1.2 this was the default jitter behavior.
+
+    Args:
+        value: The unadulterated backoff value.
+    """
+    return value + random.random()
+
+
+def full_jitter(value: float) -> float:
+    """Jitter the value across the full range (0 to value).
+
+    This corresponds to the "Full Jitter" algorithm specified in the
+    AWS blog's post on the performance of various jitter algorithms.
+    (http://www.awsarchitectureblog.com/2015/03/backoff.html)
+
+    Args:
+        value: The unadulterated backoff value.
+    """
+    return random.uniform(0, value)

backoff/_sync.py

@@ -0,0 +1,132 @@
+# coding:utf-8
+import datetime
+import functools
+import time
+from datetime import timedelta
+
+from backoff._common import (_init_wait_gen, _maybe_call, _next_wait)
+
+
+def _call_handlers(hdlrs, target, args, kwargs, tries, elapsed, **extra):
+    details = {
+        'target': target,
+        'args': args,
+        'kwargs': kwargs,
+        'tries': tries,
+        'elapsed': elapsed,
+    }
+    details.update(extra)
+    for hdlr in hdlrs:
+        hdlr(details)
+
+
+def retry_predicate(target, wait_gen, predicate,
+                    *,
+                    max_tries, max_time, jitter,
+                    on_success, on_backoff, on_giveup,
+                    wait_gen_kwargs):
+
+    @functools.wraps(target)
+    def retry(*args, **kwargs):
+        max_tries_value = _maybe_call(max_tries)
+        max_time_value = _maybe_call(max_time)
+
+        tries = 0
+        start = datetime.datetime.now()
+        wait = _init_wait_gen(wait_gen, wait_gen_kwargs)
+        while True:
+            tries += 1
+            elapsed = timedelta.total_seconds(datetime.datetime.now() - start)
+            details = {
+                "target": target,
+                "args": args,
+                "kwargs": kwargs,
+                "tries": tries,
+                "elapsed": elapsed,
+            }
+
+            ret = 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:
+                    _call_handlers(on_giveup, **details, value=ret)
+                    break
+
+                try:
+                    seconds = _next_wait(wait, ret, jitter, elapsed,
+                                         max_time_value)
+                except StopIteration:
+                    _call_handlers(on_giveup, **details)
+                    break
+
+                _call_handlers(on_backoff, **details,
+                               value=ret, wait=seconds)
+
+                time.sleep(seconds)
+                continue
+            else:
+                _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, raise_on_giveup,
+                    wait_gen_kwargs):
+
+    @functools.wraps(target)
+    def retry(*args, **kwargs):
+        max_tries_value = _maybe_call(max_tries)
+        max_time_value = _maybe_call(max_time)
+
+        tries = 0
+        start = datetime.datetime.now()
+        wait = _init_wait_gen(wait_gen, wait_gen_kwargs)
+        while True:
+            tries += 1
+            elapsed = timedelta.total_seconds(datetime.datetime.now() - start)
+            details = {
+                "target": target,
+                "args": args,
+                "kwargs": kwargs,
+                "tries": tries,
+                "elapsed": elapsed,
+            }
+
+            try:
+                ret = target(*args, **kwargs)
+            except exception as e:
+                max_tries_exceeded = (tries == max_tries_value)
+                max_time_exceeded = (max_time_value is not None and
+                                     elapsed >= max_time_value)
+
+                if giveup(e) or max_tries_exceeded or max_time_exceeded:
+                    _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:
+                    _call_handlers(on_giveup, **details, exception=e)
+                    raise e
+
+                _call_handlers(on_backoff, **details, wait=seconds,
+                               exception=e)
+
+                time.sleep(seconds)
+            else:
+                _call_handlers(on_success, **details)
+
+                return ret
+    return retry

backoff/_typing.py

@@ -0,0 +1,45 @@
+# coding:utf-8
+import logging
+import sys
+from typing import (Any, Callable, Coroutine, Dict, Generator, Sequence, Tuple,
+                    TypeVar, Union)
+
+if sys.version_info >= (3, 8):  # pragma: no cover
+    from typing import TypedDict
+else:  # pragma: no cover
+    # use typing_extensions if installed but don't require it
+    try:
+        from typing_extensions import TypedDict
+    except ImportError:
+        class TypedDict(dict):
+            def __init_subclass__(cls, **kwargs: Any) -> None:
+                return super().__init_subclass__()
+
+
+class _Details(TypedDict):
+    target: Callable[..., Any]
+    args: Tuple[Any, ...]
+    kwargs: Dict[str, Any]
+    tries: int
+    elapsed: float
+
+
+class Details(_Details, total=False):
+    wait: float  # present in the on_backoff handler case for either decorator
+    value: Any  # present in the on_predicate decorator case
+    exception: Exception  # present in the on_exception decorator case
+
+
+T = TypeVar("T")
+
+_CallableT = TypeVar('_CallableT', bound=Callable[..., Any])
+_Handler = Union[
+    Callable[[Details], None],
+    Callable[[Details], Coroutine[Any, Any, None]],
+]
+_Jitterer = Callable[[float], float]
+_MaybeCallable = Union[T, Callable[[], T]]
+_MaybeLogger = Union[str, logging.Logger, logging.LoggerAdapter, None]
+_MaybeSequence = Union[T, Sequence[T]]
+_Predicate = Callable[[T], bool]
+_WaitGenerator = Callable[..., Generator[float, None, None]]

backoff/_wait_gen.py

@@ -0,0 +1,119 @@
+# coding:utf-8
+
+import itertools
+import math
+from typing import Any, Callable, Generator, Iterable, Optional, Union
+
+
+def expo(
+    base: float = 2,
+    factor: float = 1,
+    max_value: Optional[float] = None
+) -> Generator[float, Any, None]:
+
+    """Generator for exponential decay.
+
+    Args:
+        base: The mathematical base of the exponentiation operation
+        factor: Factor to multiply the exponentiation by.
+        max_value: The maximum value to yield. Once the value in the
+             true exponential sequence exceeds this, the value
+             of max_value will forever after be yielded.
+    """
+    # Advance past initial .send() call
+    yield  # type: ignore[misc]
+    n = 0
+    while True:
+        a = factor * base ** n
+        if max_value is None or a < max_value:
+            yield a
+            n += 1
+        else:
+            yield max_value
+
+
+def decay(
+    initial_value: float = 1,
+    decay_factor: float = 1,
+    min_value: Optional[float] = None
+) -> Generator[float, Any, None]:
+
+    """Generator for exponential decay[1]:
+
+    Args:
+        initial_value: initial quantity
+        decay_factor: exponential decay constant.
+        min_value: The minimum value to yield. Once the value in the
+             true exponential sequence is lower than this, the value
+             of min_value will forever after be yielded.
+
+    [1] https://en.wikipedia.org/wiki/Exponential_decay
+    """
+    # Advance past initial .send() call
+    yield  # type: ignore[misc]
+    t = 0
+    while True:
+        a = initial_value * math.e ** (-t * decay_factor)
+        if min_value is None or a > min_value:
+            yield a
+            t += 1
+        else:
+            yield min_value
+
+
+def fibo(max_value: Optional[int] = None) -> Generator[int, None, None]:
+    """Generator for fibonaccial decay.
+
+    Args:
+        max_value: The maximum value to yield. Once the value in the
+             true fibonacci sequence exceeds this, the value
+             of max_value will forever after be yielded.
+    """
+    # Advance past initial .send() call
+    yield  # type: ignore[misc]
+
+    a = 1
+    b = 1
+    while True:
+        if max_value is None or a < max_value:
+            yield a
+            a, b = b, a + b
+        else:
+            yield max_value
+
+
+def constant(
+    interval: Union[int, Iterable[float]] = 1
+) -> Generator[float, None, None]:
+    """Generator for constant intervals.
+
+    Args:
+        interval: A constant value to yield or an iterable of such values.
+    """
+    # Advance past initial .send() call
+    yield  # type: ignore[misc]
+
+    try:
+        itr = iter(interval)  # type: ignore
+    except TypeError:
+        itr = itertools.repeat(interval)  # type: ignore
+
+    for val in itr:
+        yield val
+
+
+def runtime(
+    *,
+    value: Callable[[Any], float]
+) -> Generator[float, None, None]:
+    """Generator that is based on parsing the return value or thrown
+        exception of the decorated method
+
+    Args:
+        value: a callable which takes as input the decorated
+            function's return value or thrown exception and
+            determines how long to wait
+    """
+    ret_or_exc = yield  # type: ignore[misc]
+    while True:
+        ret_or_exc = yield value(ret_or_exc)

backoff/types.py

@@ -0,0 +1,6 @@
+# coding:utf-8
+from ._typing import Details
+
+__all__ = [
+    'Details'
+]

python_backoff-2.2.2rc1.dist-info/METADATA

@@ -0,0 +1,417 @@
+Metadata-Version: 2.4
+Name: python-backoff
+Version: 2.2.2rc1
+Summary: Function decoration for backoff and retry
+Project-URL: Documentation, https://python-backoff.github.io/backoff
+Project-URL: Repository, https://github.com/python-backoff/backoff
+Author-email: Bob Green <rgreen@aquent.com>
+Maintainer-email: Edgar Ramírez-Mondragón <edgarrm358@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: backoff,decorators,retry
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.7
+Description-Content-Type: text/x-rst
+
+backoff
+=======
+
+.. image:: https://github.com/python-backoff/backoff/actions/workflows/ci.yaml/badge.svg
+    :target: https://github.com/python-backoff/backoff/actions/workflows/ci.yaml
+.. image:: https://github.com/python-backoff/backoff/workflows/CodeQL/badge.svg
+    :target: https://github.com/python-backoff/backoff/actions/workflows/codeql-analysis.yml
+.. image:: https://img.shields.io/pypi/v/backoff.svg
+    :target: https://pypi.python.org/pypi/backoff
+.. image:: https://img.shields.io/github/license/python-backoff/backoff
+    :target: https://github.com/python-backoff/backoff/blob/main/LICENSE
+
+**Function decoration for backoff and retry**
+
+This module provides function decorators which can be used to wrap a
+function such that it will be retried until some condition is met. It
+is meant to be of use when accessing unreliable resources with the
+potential for intermittent failures i.e. network resources and external
+APIs. Somewhat more generally, it may also be of use for dynamically
+polling resources for externally generated content.
+
+Decorators support both regular functions for synchronous code and
+`asyncio <https://docs.python.org/3/library/asyncio.html>`__'s coroutines
+for asynchronous code.
+
+Examples
+========
+
+Since Kenneth Reitz's `requests <http://python-requests.org>`_ module
+has become a defacto standard for synchronous HTTP clients in Python,
+networking examples below are written using it, but it is in no way required
+by the backoff module.
+
+@backoff.on_exception
+---------------------
+
+The ``on_exception`` decorator is used to retry when a specified exception
+is raised. Here's an example using exponential backoff when any
+``requests`` exception is raised:
+
+.. code-block:: python
+
+    @backoff.on_exception(backoff.expo,
+                          requests.exceptions.RequestException)
+    def get_url(url):
+        return requests.get(url)
+
+The decorator will also accept a tuple of exceptions for cases where
+the same backoff behavior is desired for more than one exception type:
+
+.. code-block:: python
+
+    @backoff.on_exception(backoff.expo,
+                          (requests.exceptions.Timeout,
+                           requests.exceptions.ConnectionError))
+    def get_url(url):
+        return requests.get(url)
+
+**Give Up Conditions**
+
+Optional keyword arguments can specify conditions under which to give
+up.
+
+The keyword argument ``max_time`` specifies the maximum amount
+of total time in seconds that can elapse before giving up.
+
+.. code-block:: python
+
+    @backoff.on_exception(backoff.expo,
+                          requests.exceptions.RequestException,
+                          max_time=60)
+    def get_url(url):
+        return requests.get(url)
+
+
+Keyword argument ``max_tries`` specifies the maximum number of calls
+to make to the target function before giving up.
+
+.. code-block:: python
+
+    @backoff.on_exception(backoff.expo,
+                          requests.exceptions.RequestException,
+                          max_tries=8,
+                          jitter=None)
+    def get_url(url):
+        return requests.get(url)
+
+
+In some cases the raised exception instance itself may need to be
+inspected in order to determine if it is a retryable condition. The
+``giveup`` keyword arg can be used to specify a function which accepts
+the exception and returns a truthy value if the exception should not
+be retried:
+
+.. code-block:: python
+
+    def fatal_code(e):
+        return 400 <= e.response.status_code < 500
+
+    @backoff.on_exception(backoff.expo,
+                          requests.exceptions.RequestException,
+                          max_time=300,
+                          giveup=fatal_code)
+    def get_url(url):
+        return requests.get(url)
+
+By default, when a give up event occurs, the exception in question is reraised
+and so code calling an `on_exception`-decorated function may still
+need to do exception handling. This behavior can optionally be disabled
+using the `raise_on_giveup` keyword argument.
+
+In the code below, `requests.exceptions.RequestException` will not be raised
+when giveup occurs. Note that the decorated function will return `None` in this
+case, regardless of the logic in the `on_exception` handler.
+
+.. code-block:: python
+
+    def fatal_code(e):
+        return 400 <= e.response.status_code < 500
+
+    @backoff.on_exception(backoff.expo,
+                          requests.exceptions.RequestException,
+                          max_time=300,
+                          raise_on_giveup=False,
+                          giveup=fatal_code)
+    def get_url(url):
+        return requests.get(url)
+
+This is useful for non-mission critical code where you still wish to retry
+the code inside of `backoff.on_exception` but wish to proceed with execution
+even if all retries fail.
+
+@backoff.on_predicate
+---------------------
+
+The ``on_predicate`` decorator is used to retry when a particular
+condition is true of the return value of the target function.  This may
+be useful when polling a resource for externally generated content.
+
+Here's an example which uses a fibonacci sequence backoff when the
+return value of the target function is the empty list:
+
+.. code-block:: python
+
+    @backoff.on_predicate(backoff.fibo, lambda x: x == [], max_value=13)
+    def poll_for_messages(queue):
+        return queue.get()
+
+Extra keyword arguments are passed when initializing the
+wait generator, so the ``max_value`` param above is passed as a keyword
+arg when initializing the fibo generator.
+
+When not specified, the predicate param defaults to the falsey test,
+so the above can more concisely be written:
+
+.. code-block:: python
+
+    @backoff.on_predicate(backoff.fibo, max_value=13)
+    def poll_for_message(queue):
+        return queue.get()
+
+More simply, a function which continues polling every second until it
+gets a non-falsey result could be defined like like this:
+
+.. code-block:: python
+
+    @backoff.on_predicate(backoff.constant, jitter=None, interval=1)
+    def poll_for_message(queue):
+        return queue.get()
+
+The jitter is disabled in order to keep the polling frequency fixed.  
+
+@backoff.runtime
+----------------
+
+You can also use the ``backoff.runtime`` generator to make use of the
+return value or thrown exception of the decorated method.
+
+For example, to use the value in the ``Retry-After`` header of the response:
+
+.. code-block:: python
+
+    @backoff.on_predicate(
+        backoff.runtime,
+        predicate=lambda r: r.status_code == 429,
+        value=lambda r: int(r.headers.get("Retry-After")),
+        jitter=None,
+    )
+    def get_url():
+        return requests.get(url)
+
+Jitter
+------
+
+A jitter algorithm can be supplied with the ``jitter`` keyword arg to
+either of the backoff decorators. This argument should be a function
+accepting the original unadulterated backoff value and returning it's
+jittered counterpart.
+
+As of version 1.2, the default jitter function ``backoff.full_jitter``
+implements the 'Full Jitter' algorithm as defined in the AWS
+Architecture Blog's `Exponential Backoff And Jitter
+<https://www.awsarchitectureblog.com/2015/03/backoff.html>`_ post.
+Note that with this algorithm, the time yielded by the wait generator
+is actually the *maximum* amount of time to wait.
+
+Previous versions of backoff defaulted to adding some random number of
+milliseconds (up to 1s) to the raw sleep value. If desired, this
+behavior is now available as ``backoff.random_jitter``.
+
+Using multiple decorators
+-------------------------
+
+The backoff decorators may also be combined to specify different
+backoff behavior for different cases:
+
+.. code-block:: python
+
+    @backoff.on_predicate(backoff.fibo, max_value=13)
+    @backoff.on_exception(backoff.expo,
+                          requests.exceptions.HTTPError,
+                          max_time=60)
+    @backoff.on_exception(backoff.expo,
+                          requests.exceptions.Timeout,
+                          max_time=300)
+    def poll_for_message(queue):
+        return queue.get()
+
+
+Runtime Configuration
+---------------------
+
+The decorator functions ``on_exception`` and ``on_predicate`` are
+generally evaluated at import time. This is fine when the keyword args
+are passed as constant values, but suppose we want to consult a
+dictionary with configuration options that only become available at
+runtime. The relevant values are not available at import time. Instead,
+decorator functions can be passed callables which are evaluated at
+runtime to obtain the value:
+
+.. code-block:: python
+
+    def lookup_max_time():
+        # pretend we have a global reference to 'app' here
+        # and that it has a dictionary-like 'config' property
+        return app.config["BACKOFF_MAX_TIME"]
+
+    @backoff.on_exception(backoff.expo,
+                          ValueError,
+                          max_time=lookup_max_time)
+
+Event handlers
+--------------
+
+Both backoff decorators optionally accept event handler functions
+using the keyword arguments ``on_success``, ``on_backoff``, and ``on_giveup``.
+This may be useful in reporting statistics or performing other custom
+logging.
+
+Handlers must be callables with a unary signature accepting a dict
+argument. This dict contains the details of the invocation. Valid keys
+include:
+
+* *target*: reference to the function or method being invoked
+* *args*: positional arguments to func
+* *kwargs*: keyword arguments to func
+* *tries*: number of invocation tries so far
+* *elapsed*: elapsed time in seconds so far
+* *wait*: seconds to wait (``on_backoff`` handler only)
+* *value*: value triggering backoff (``on_predicate`` decorator only)
+
+A handler which prints the details of the backoff event could be
+implemented like so:
+
+.. code-block:: python
+
+    def backoff_hdlr(details):
+        print ("Backing off {wait:0.1f} seconds after {tries} tries "
+               "calling function {target} with args {args} and kwargs "
+               "{kwargs}".format(**details))
+
+    @backoff.on_exception(backoff.expo,
+                          requests.exceptions.RequestException,
+                          on_backoff=backoff_hdlr)
+    def get_url(url):
+        return requests.get(url)
+
+**Multiple handlers per event type**
+
+In all cases, iterables of handler functions are also accepted, which
+are called in turn. For example, you might provide a simple list of
+handler functions as the value of the ``on_backoff`` keyword arg:
+
+.. code-block:: python
+
+    @backoff.on_exception(backoff.expo,
+                          requests.exceptions.RequestException,
+                          on_backoff=[backoff_hdlr1, backoff_hdlr2])
+    def get_url(url):
+        return requests.get(url)
+
+**Getting exception info**
+
+In the case of the ``on_exception`` decorator, all ``on_backoff`` and
+``on_giveup`` handlers are called from within the except block for the
+exception being handled. Therefore exception info is available to the
+handler functions via the python standard library, specifically
+``sys.exc_info()`` or the ``traceback`` module. The exception is also
+available at the *exception* key in the `details` dict passed to the
+handlers.
+
+Asynchronous code
+-----------------
+
+Backoff supports asynchronous execution in Python 3.5 and above.
+
+To use backoff in asynchronous code based on
+`asyncio <https://docs.python.org/3/library/asyncio.html>`__
+you simply need to apply ``backoff.on_exception`` or ``backoff.on_predicate``
+to coroutines.
+You can also use coroutines for the ``on_success``, ``on_backoff``, and
+``on_giveup`` event handlers, with the interface otherwise being identical.
+
+The following examples use `aiohttp <https://aiohttp.readthedocs.io/>`__
+asynchronous HTTP client/server library.
+
+.. code-block:: python
+
+    @backoff.on_exception(backoff.expo, aiohttp.ClientError, max_time=60)
+    async def get_url(url):
+        async with aiohttp.ClientSession(raise_for_status=True) as session:
+            async with session.get(url) as response:
+                return await response.text()
+
+Logging configuration
+---------------------
+
+By default, backoff and retry attempts are logged to the 'backoff'
+logger. By default, this logger is configured with a NullHandler, so
+there will be nothing output unless you configure a handler.
+Programmatically, this might be accomplished with something as simple
+as:
+
+.. code-block:: python
+
+    logging.getLogger('backoff').addHandler(logging.StreamHandler())
+
+The default logging level is INFO, which corresponds to logging
+anytime a retry event occurs. If you would instead like to log
+only when a giveup event occurs, set the logger level to ERROR.
+
+.. code-block:: python
+
+    logging.getLogger('backoff').setLevel(logging.ERROR)
+
+It is also possible to specify an alternate logger with the ``logger``
+keyword argument.  If a string value is specified the logger will be
+looked up by name.
+
+.. code-block:: python
+
+   @backoff.on_exception(backoff.expo,
+                         requests.exceptions.RequestException,
+			 logger='my_logger')
+   # ...
+
+It is also supported to specify a Logger (or LoggerAdapter) object
+directly.
+
+.. code-block:: python
+
+    my_logger = logging.getLogger('my_logger')
+    my_handler = logging.StreamHandler()
+    my_logger.addHandler(my_handler)
+    my_logger.setLevel(logging.ERROR)
+
+    @backoff.on_exception(backoff.expo,
+                          requests.exceptions.RequestException,
+			  logger=my_logger)
+    # ...
+
+Default logging can be disabled all together by specifying
+``logger=None``. In this case, if desired alternative logging behavior
+could be defined by using custom event handlers.

python_backoff-2.2.2rc1.dist-info/RECORD

@@ -0,0 +1,14 @@
+backoff/__init__.py,sha256=cxmsrw6PUsF2VsUnaX-gyKsJ5If3iKVIKoVU5Fg2njc,928
+backoff/_async.py,sha256=gX-MFZWs1-6dyUsohHtJxAP_Zg0if5n8MSmHyNFTB5I,6790
+backoff/_common.py,sha256=8s3_5AJH8hiHd9GR2PdKqiaeE2sdEUoyf6cW9OCo1F8,3478
+backoff/_decorator.py,sha256=Vx9IlrmA22tjNgo-YN4FHqcC0W54wL-4Ug4dTdjUHZ8,9815
+backoff/_jitter.py,sha256=LjJShpjryk9sWBCWiz-3UX1DJCx6rebNJ5Bf3nPMlYQ,782
+backoff/_sync.py,sha256=DT_ktufPPb0nut9WCAKe5UE7sTYRl9f93PRPX6jP8ro,4214
+backoff/_typing.py,sha256=K4xjbkoQUuKt5E1cEAUgIPrhrV2lWD3BXmgu8_Mv7rQ,1422
+backoff/_wait_gen.py,sha256=hObFPeXDXdzcvMhkknya3nlSKYoCAMT5LFoto25emuI,3241
+backoff/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+backoff/types.py,sha256=4DGG6Ltcz0wVfXrk0YBOnp_oPpcki4c0BOnodRhgoqg,73
+python_backoff-2.2.2rc1.dist-info/METADATA,sha256=NxbuUUJetGK9vIbuDh1dLf3N-yD08J8fxxvtpwOEkRk,14951
+python_backoff-2.2.2rc1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+python_backoff-2.2.2rc1.dist-info/licenses/LICENSE,sha256=KmtNX4hNTXob8E6n3xlEzxKzLjWnmobQoHWi0_QPuaw,1077
+python_backoff-2.2.2rc1.dist-info/RECORD,,

python_backoff-2.2.2rc1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

python_backoff-2.2.2rc1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 litl, LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.