The retry and aioretry decorators

kaioretry.retry()

@kaioretry.retry(exceptions=<class 'Exception'>, tries=-1, *, delay=0, backoff=1, jitter=0, max_delay=None, min_delay=0, logger=<Logger kaioretry.decorator (WARNING)>)

Return a new retry decorator, suitable for regular functions. Functions decorated will transparently retry when a exception is raised.

Parameters:

  • exceptions (tuple[type[BaseException], ...] | type[BaseException]) – exceptions classes that will trigger another try. Other exceptions raised by the decorated function will not trigger a retry. The value of the exceptions parameters can be either an Exception class or a tuple of Exception classes (actually, whatever is suitable for an except clause). The default is the Exception class, which means any error will trigger a new try.

  • tries (int) – the maximum number of iterations (a.k.a.: tries, function calls) to perform before exhaustion. A negative value means infinite. 0 is forbidden, since it would mean “don’t run” at all.

  • delay (int | float) – the initial number of seconds to wait between two iterations. It must be non-negative. Default is 0.

  • backoff (int | float) – a multiplier applied to delay after each iteration. It can be a float, and it can actually be less than one. Default: 1 (no backoff).

  • jitter (int | float | tuple[int | float, int | float]) – extra seconds added to delay between iterations. Default: 0.

  • max_delay (UnionType[int, float, None]) – the maximum value of delay. default: None (no limit).

  • min_delay (int | float) – the minimum value allowed for delay. Cannot be negative. Default is 0.

  • logger (Logger) – the logging.Logger object to which the log messages will be sent to.

Raises:

  • ValueError – if tries, min_delay or max_delay have incorrect values.

  • TypeError – if jitter is neither a Number nor a tuple.

Return type:

Callable[[Callable[[ParamSpec(FuncParam)], TypeVar(FuncRetVal)]], Callable[[ParamSpec(FuncParam)], TypeVar(FuncRetVal)]]

Returns:

a retry decorator for regular (non-coroutine) functions.

kaioretry.aioretry()

@kaioretry.aioretry(exceptions=<class 'Exception'>, tries=-1, *, delay=0, backoff=1, jitter=0, max_delay=None, min_delay=0, logger=<Logger kaioretry.decorator (WARNING)>)

Similar to retry(), this function will produce a new async retry decorator that will produce exact the same results as said retry(), except that the produced decorated functions will be typed as a Coroutine, and that delays induced by the delay constructor parameter and its friends, will be implemented with asyncio functions.

That means the decorated version of given functions will be eligible to asyncio.run() or to an await statement, even if given func parameter is not originally an async function to begin with.

Parameters:

  • exceptions (tuple[type[BaseException], ...] | type[BaseException]) – exceptions classes that will trigger another try. Other exceptions raised by the decorated function will not trigger a retry. The value of the exceptions parameters can be either an Exception class or a tuple of Exception classes (actually, whatever is suitable for an except clause). The default is the Exception class, which means any error will trigger a new try.

  • tries (int) – the maximum number of iterations (a.k.a.: tries, function calls) to perform before exhaustion. A negative value means infinite. 0 is forbidden, since it would mean “don’t run” at all.

  • delay (int | float) – the initial number of seconds to wait between two iterations. It must be non-negative. Default is 0.

  • backoff (int | float) – a multiplier applied to delay after each iteration. It can be a float, and it can actually be less than one. Default: 1 (no backoff).

  • jitter (int | float | tuple[int | float, int | float]) – extra seconds added to delay between iterations. Default: 0.

  • max_delay (UnionType[int, float, None]) – the maximum value of delay. default: None (no limit).

  • min_delay (int | float) – the minimum value allowed for delay. Cannot be negative. Default is 0.

  • logger (Logger) – the logging.Logger object to which the log messages will be sent to.

Raises:

  • ValueError – if tries, min_delay or max_delay have incorrect values.

  • TypeError – if jitter is neither a Number nor a tuple.

Return type:

AioretryProtocol

Returns:

a retry decorator that generates coroutines functions.