retry_on_err

privex.helpers.decorators.retry_on_err(max_retries: int = 3, delay: Union[int, float] = 3, **retry_conf)[source]

Decorates a function or class method, wraps the function/method with a try/catch block, and will automatically re-run the function with the same arguments up to max_retries time after any exception is raised, with a delay second delay between re-tries.

If it still throws an exception after max_retries retries, it will log the exception details with fail_msg, and then re-raise it.

Usage (retry up to 5 times, 1 second between retries, stop immediately if IOError is detected):

>>> @retry_on_err(5, 1, fail_on=[IOError])
... def my_func(self, some=None, args=None):
...     if some == 'io': raise IOError()
...      raise FileExistsError()

This will be re-ran 5 times, 1 second apart after each exception is raised, before giving up:

>>> my_func()

Where-as this one will immediately re-raise the caught IOError on the first attempt, as it’s passed in fail_on:

>>> my_func('io')

Attention

For safety reasons, by default max_ignore is set to 100. This means after 100 retries where an exception was ignored, the decorator will give up and raise the last exception.

This is to prevent the risk of infinite loops hanging your application. If you are 100% certain that the function you’ve wrapped, and/or the exceptions passed in ignore cannot cause an infinite retry loop, then you can pass max_ignore=False to the decorator to disable failure after max_ignore ignored exceptions.

Parameters

  • max_retries (int) – Maximum total retry attempts before giving up

  • delay (float) – Amount of time in seconds to sleep before re-trying the wrapped function

  • retry_conf – Less frequently used arguments, pass in as keyword args (see below)

Key list fail_on

A list() of Exception types that should result in immediate failure (don’t retry, raise)

Key list ignore

A list() of Exception types that should be ignored (will retry, but without incrementing the failure counter)

Key int|bool max_ignore

(Default: 100) If an exception is raised while retrying, and more than this many exceptions (listed in ignore) have been ignored during retry attempts, then give up and raise the last exception.

This feature is designed to prevent “ignored” exceptions causing an infinite retry loop. By default max_ignore is set to 100, but you can increase/decrease this as needed.

You can also set it to False to disable raising when too many exceptions are ignored - however, it’s strongly not recommended to disable max_ignore, especially if you have instance_match=True, as it could cause an infinite retry loop which hangs your application.

Key bool instance_match

(Default: False) If this is set to True, then the exception type comparisons for fail_on and ignore will compare using isinstance(e, x) instead of type(e) is x.

If this is enabled, then exceptions listed in fail_on and ignore will also match sub-classes of the listed exceptions, instead of exact matches.

Key str retry_msg

Override the log message used for retry attempts. First message param %s is func name, second message param %d is retry attempts remaining

Key str fail_msg

Override the log message used after all retry attempts are exhausted. First message param %s is func name, and second param %d is amount of times retried.