API Reference#

Summary#

`retry`(func, *, exceptions[, args, kwargs, ...])	Call the provided callable with retry logic.
`retry_decorator`(*, exceptions[, ...])	Construct a decorator function for defining a function with built-in retry logic.
`retry_factory`(func, *, exceptions[, ...])	Construct a function with built-in retry logic given a callable to retry.
`RetryError`	Exception raised when a retry or time limit is reached

Interfaces#

tubthumper.retry(func, *, exceptions, args=None, kwargs=None, retry_limit=inf, time_limit=inf, init_backoff=1, exponential=2, jitter=True, reraise=False, log_level=30, logger=<Logger tubthumper (WARNING)>)[source]#

Call the provided callable with retry logic.

For usage examples, see here.

Parameters:

func (Callable[[~P], T]) – callable to be called
exceptions (Type[Exception] | Tuple[Type[Exception]]) – exceptions to be caught, resulting in a retry
args (Iterable[Any] | None) – positional arguments for the callable
kwargs (Mapping[str, Any] | None) – keyword arguments for the callable
retry_limit (float) – number of retries to perform before raising an exception, e.g. retry_limit=1 results in at most two calls
time_limit (float) – duration in seconds after which a retry attempt will be prevented by raising an exception, i.e. not a timeout stopping long running calls, but rather a mechanism to prevent retry attempts after a certain duration
init_backoff (float) – duration in seconds to sleep before the first retry
exponential (float) – backoff duration between retries grows by this factor with each retry
jitter (bool) – whether or not to “jitter” the backoff duration randomly
reraise (bool) – whether or not to re-raise the caught exception instead of a RetryError when a retry or time limit is reached
log_level (int) – level for logging caught exceptions, defaults to logging.WARNING
logger (Logger) – logger to log caught exceptions with

Raises:

RetryError – Raised when a retry or time limit is reached, unless reraise=True

Returns:

the returned object of the callable

Return type:

@tubthumper.retry_decorator(*, exceptions, retry_limit=inf, time_limit=inf, init_backoff=1, exponential=2, jitter=True, reraise=False, log_level=30, logger=<Logger tubthumper (WARNING)>)[source]#

Construct a decorator function for defining a function with built-in retry logic.

For usage examples, see here.

Parameters:

exceptions (Type[Exception] | Tuple[Type[Exception]]) – exceptions to be caught, resulting in a retry
retry_limit (float) – number of retries to perform before raising an exception, e.g. retry_limit=1 results in at most two calls
time_limit (float) – duration in seconds after which a retry attempt will be prevented by raising an exception, i.e. not a timeout stopping long running calls, but rather a mechanism to prevent retry attempts after a certain duration
init_backoff (float) – duration in seconds to sleep before the first retry
exponential (float) – backoff duration between retries grows by this factor with each retry
jitter (bool) – whether or not to “jitter” the backoff duration randomly
reraise (bool) – whether or not to re-raise the caught exception instead of a RetryError when a retry or time limit is reached
log_level (int) – level for logging caught exceptions, defaults to logging.WARNING
logger (Logger) – logger to log caught exceptions with

Raises:

RetryError – Raised when a retry or time limit is reached, unless reraise=True

Returns:

a decorator function that, when used as such, returns a function that looks like the callable it decorates, but with configured retry logic

Return type:

Callable[[Callable[[~P], T]], Callable[[~P], T]]

tubthumper.retry_factory(func, *, exceptions, retry_limit=inf, time_limit=inf, init_backoff=1, exponential=2, jitter=True, reraise=False, log_level=30, logger=<Logger tubthumper (WARNING)>)[source]#

Construct a function with built-in retry logic given a callable to retry.

For usage examples, see here.

Parameters:

func (Callable[[~P], T]) – callable to be called
exceptions (Type[Exception] | Tuple[Type[Exception]]) – exceptions to be caught, resulting in a retry
retry_limit (float) – number of retries to perform before raising an exception, e.g. retry_limit=1 results in at most two calls
time_limit (float) – duration in seconds after which a retry attempt will be prevented by raising an exception, i.e. not a timeout stopping long running calls, but rather a mechanism to prevent retry attempts after a certain duration
init_backoff (float) – duration in seconds to sleep before the first retry
exponential (float) – backoff duration between retries grows by this factor with each retry
jitter (bool) – whether or not to “jitter” the backoff duration randomly
reraise (bool) – whether or not to re-raise the caught exception instead of a RetryError when a retry or time limit is reached
log_level (int) – level for logging caught exceptions, defaults to logging.WARNING
logger (Logger) – logger to log caught exceptions with

Raises:

RetryError – Raised when a retry or time limit is reached, unless reraise=True

Returns:

a function that looks like the callable provided, but with configured retry logic

Return type:

Callable[[~P], T]

exception tubthumper.RetryError[source]#: Exception raised when a retry or time limit is reached

Odds & Ends#

class tubthumper._types.Logger(*args, **kwargs)[source]#

Generally a logging.Logger, but since we want to support duck-typing, this is a typing.Protocol to enable structural subtyping.

log(level, msg, *args, exc_info)[source]#

We call this method to log at the configured level with exc_info=True

Parameters:

level (int) – the level of the message to be logged
msg (str) – the message to be logged
exc_info (bool) – causes exception information to be added to the logging message
args (object) –

Return type:

None