API Reference#

stamina.retry(*, on, attempts=10, timeout=45.0, wait_initial=0.1, wait_max=5.0, wait_jitter=1.0, wait_exp_base=2.0)[source]#

Retry if one of configured exceptions are raised.

The backoff delays between retries grow exponentially plus a random jitter.

The backoff for retry attempt number attempt is computed as:

\[wait\_initial * wait\_exp\_base^{attempt - 1} + random(0, wait\_jitter)\]

Since \(x^0\) is always 1, the first backoff is within the interval \([wait\_initial,wait\_initial+wait\_jitter]\). Thus, with default values between 0.1 and 1.1 seconds.

If all retries fail, the last exception is let through.

All float-based time parameters are in seconds.

  • on (type[Exception] | tuple[type[Exception], ...]) – An Exception or a tuple of Exceptions on which the decorated callable will be retried. There is no default – you must pass this explicitly.

  • attempts (int | None) – Maximum total number of attempts. Can be combined with timeout.

  • timeout (float | timedelta | None) – Maximum total time for all retries. Can be combined with attempts.

  • wait_initial (float | timedelta) – Minimum backoff before the first retry.

  • wait_max (float | timedelta) – Maximum backoff time between retries at any time.

  • wait_jitter (float | timedelta) – Maximum jitter that is added to retry back-off delays (the actual jitter added is a random number between 0 and wait_jitter)

  • wait_exp_base (float) – The exponential base used to compute the retry backoff.

Changed in version 23.1.0: All time-related parameters can now be specified as a datetime.timedelta.

stamina.retry_context(on, attempts=10, timeout=45.0, wait_initial=0.1, wait_max=5.0, wait_jitter=1.0, wait_exp_base=2.0)[source]#

Iterator that yields context managers that can be used to retry code blocks.

Arguments have the same meaning as for stamina.retry().

New in version 23.1.0.



Activate or deactivate retrying.

Is idempotent and can be called repeatedly with the same value.


Check whether retrying is active.


Whether retrying is active.

Return type: