tubthumper

Initialization code for tubthumper package

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
Logger(*args, **kwargs)	Generally a logging.Logger, but since we want to support duck-typing, this is a typing.Protocol to enable structural subtyping.

Classes

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

Bases: Protocol

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)

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

Functions

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[[~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:

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

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]

Exceptions

exception tubthumper.RetryError

Exception raised when a retry or time limit is reached