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)>)

Call the provided callable with retry logic.

For usage examples, see here.

Parameters

• func (Callable[[...], tubthumper._types.T]) – callable to be called

• exceptions (Union[Type[Exception], Tuple[Type[Exception]]]) – exceptions to be caught, resulting in a retry

• args (Optional[Iterable[Any]]) – positional arguments for the callable

• kwargs (Optional[Mapping[str, Any]]) – 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 (tubthumper._types.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._types.T

@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)>)

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

For usage examples, see here.

Parameters

• exceptions (Union[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 (tubthumper._types.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[[…], tubthumper._types.T]], Callable[[…], tubthumper._types.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)>)

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

For usage examples, see here.

Parameters

• func (Callable[[...], tubthumper._types.T]) – callable to be called

• exceptions (Union[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 (tubthumper._types.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[[…], tubthumper._types.T]

exception tubthumper.RetryError

Exception raised when a retry or time limit is reached

Odds & Ends

class tubthumper._types.Logger(*args, **kwargs)

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, **kwargs)

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 (Any) –

• kwargs (Any) –

Return type

Any