Tenacity Python
Treat a retry as a policy around repeated attempts, not as an error-handling
decorator added after a failure. Preserve the operation's idempotency, deadline,
failure taxonomy, and observability.
Boundary
Use this skill when a project uses Tenacity or explicitly requests it for a
transient operation. Do not retry permanent validation/authentication errors,
unknown broad exceptions, local programmer defects, or irreversible operations
without an idempotency mechanism. Do not add Tenacity around a client that
already owns an adequate retry policy until duplicate retry multiplication is
resolved.
Know the policy objects
| Object |
Meaning |
Required decision |
retry(...) |
Decorator creating a retry controller per call |
Predicate, stop, wait, propagation, hooks. |
Retrying |
Synchronous controller/call/block iterator |
Use when policy is dynamic or a block, not a whole function, is retried. |
AsyncRetrying |
Await-aware controller |
Awaited operation and sleep remain nonblocking. |
| Retry predicate |
Decides whether the last exception/result is retryable |
Must be narrow and domain-grounded. |
| Stop strategy |
Bounds attempts or elapsed retry time |
Always finite in application code. |
| Wait strategy |
Delay before another attempt |
Respect service pressure and add jitter for contention. |
RetryCallState |
Attempt number, outcome, timing, next action |
Source for callbacks and tests, not mutable business state. |
Read the retry state model before composing
predicates, retrying results, or using block iteration.
Ordered workflow
- Name the exact attempted operation and its side effect. Establish whether
repetition is safe, conditionally safe through an idempotency key, or unsafe.
- Classify failures from the real client/library: retry only enumerated
transient exceptions or results. Exclude cancellation, invalid input,
permission/auth failures, and deterministic defects.
- Establish the outer deadline/budget. Choose a finite stop condition that
cannot outlive it; attempts include the first call.
- Choose wait behavior from the dependency contract. For shared remote
services, use capped exponential random wait or honor a supported server
retry delay. Do not busy-loop.
- Decide terminal failure: normally
reraise=True so callers see the final
domain exception. Use RetryError only when callers intentionally consume
retry-controller state.
- Attach structured
before_sleep telemetry without secrets. Log only an
attempt that will actually retry, not every call as an error.
- Test with zero wait/fake sleep and deterministic outcomes. Assert attempt
count, retry classification, final exception/result, and side effects.
Policy decision table
| Condition |
Action |
| Operation is not repeat-safe |
Do not retry; add idempotency/transaction semantics first. |
| Failure is permanent or unknown |
Propagate immediately. |
| Client already retries |
Configure one owner; prevent multiplicative nested attempts. |
| Attempts are cheap and local |
Small attempt bound; wait_none/fixed wait only if pressure is irrelevant. |
| Remote service is contended |
Bounded exponential random wait with cap. |
| Caller has a hard deadline |
Stop by elapsed time/attempts beneath that deadline; retain transport timeout per attempt. |
| Async operation |
Use async-decorated function or AsyncRetrying; never block the loop with time.sleep. |
| Return value signals transient incompleteness |
Use retry_if_result only when the result has an unambiguous retry state. |
Canonical bounded policy
from tenacity import (
retry,
retry_if_exception_type,
stop_after_attempt,
wait_random_exponential,
)
class TemporaryStoreError(Exception):
pass
@retry(
retry=retry_if_exception_type(TemporaryStoreError),
stop=stop_after_attempt(4),
wait=wait_random_exponential(multiplier=0.25, max=4),
reraise=True,
)
def load_record(store, record_id: str):
return store.load(record_id)
The operation still needs a per-attempt timeout. Tenacity bounds retrying, not
an individual call stuck forever. Do not decorate an entire workflow when only
one read is retryable; repeat the narrowest safe unit.
Side effects and nested budgets
- Reads are not automatically safe if they consume messages or advance cursors.
- Writes require a stable idempotency key, transactional upsert, or explicit
proof that a repeated request cannot duplicate effects.
- A timeout does not prove the server did nothing. Treat an ambiguous write
outcome separately from a known pre-commit failure.
- Multiply configured layers to find the real worst-case attempts. Prefer one
retry owner and one outer deadline.
- Do not retry
BaseException, cancellation, keyboard interrupts, or a blanket
Exception just because examples do.
Read policy and testing for budgets, deterministic
tests, and non-idempotent operations.
Async and observability
Tenacity supports coroutines and AsyncRetrying. Ensure the awaited client
call, sleep function, cancellation behavior, and caller deadline all remain
async. In before_sleep, record operation name, attempt, elapsed time, next
delay, and exception class; exclude credentials, payloads, and full response
bodies. A counter should distinguish attempts from completed calls and terminal
failures. Read async and observability.
Version grounding and completion
Inspect the installed version of Tenacity and its signatures before
using a copied helper or callback field. This foundry did not have Tenacity
installed during authoring, so examples are source-grounded but not locally
executed. Do not turn that into a runtime-version claim.
Completion requires: repetition safety is proven; retry and non-retry failures
are enumerated; per-attempt timeout and overall stop are finite; wait avoids a
hot loop; terminal exceptions match the caller contract; async code does not
block; telemetry reveals attempts without leaking data; and deterministic tests
prove attempt counts, terminal behavior, and exactly-once visible effects.
References
- Retry state model
- Policy and deterministic testing
- Async and observability
1---2name: tenacity-python3description: Use for writing, reviewing, debugging, or testing bounded retry policies in Python with Tenacity, including retry predicates, stop and wait strategies, jitter, exception propagation, callbacks, Retrying, and AsyncRetrying. Do not use for generic loops, scheduled jobs, domain polling without a retryable operation, or operations whose side effects are not safe to repeat.4argument-hint: "[Tenacity retry task, policy, code, failure, or test]"5metadata:6 source: https://skillmd.com/skills/schattenspiegel/tenacity-python7---89# Tenacity Python1011Treat a retry as a policy around repeated attempts, not as an error-handling12decorator added after a failure. Preserve the operation's idempotency, deadline,13failure taxonomy, and observability.1415## Boundary1617Use this skill when a project uses Tenacity or explicitly requests it for a18transient operation. Do not retry permanent validation/authentication errors,19unknown broad exceptions, local programmer defects, or irreversible operations20without an idempotency mechanism. Do not add Tenacity around a client that21already owns an adequate retry policy until duplicate retry multiplication is22resolved.2324## Know the policy objects2526| Object | Meaning | Required decision |27|---|---|---|28| `retry(...)` | Decorator creating a retry controller per call | Predicate, stop, wait, propagation, hooks. |29| `Retrying` | Synchronous controller/call/block iterator | Use when policy is dynamic or a block, not a whole function, is retried. |30| `AsyncRetrying` | Await-aware controller | Awaited operation and sleep remain nonblocking. |31| Retry predicate | Decides whether the last exception/result is retryable | Must be narrow and domain-grounded. |32| Stop strategy | Bounds attempts or elapsed retry time | Always finite in application code. |33| Wait strategy | Delay before another attempt | Respect service pressure and add jitter for contention. |34| `RetryCallState` | Attempt number, outcome, timing, next action | Source for callbacks and tests, not mutable business state. |3536Read [the retry state model](references/retry-model.md) before composing37predicates, retrying results, or using block iteration.3839## Ordered workflow40411. Name the exact attempted operation and its side effect. Establish whether42 repetition is safe, conditionally safe through an idempotency key, or unsafe.432. Classify failures from the real client/library: retry only enumerated44 transient exceptions or results. Exclude cancellation, invalid input,45 permission/auth failures, and deterministic defects.463. Establish the outer deadline/budget. Choose a finite stop condition that47 cannot outlive it; attempts include the first call.484. Choose wait behavior from the dependency contract. For shared remote49 services, use capped exponential random wait or honor a supported server50 retry delay. Do not busy-loop.515. Decide terminal failure: normally `reraise=True` so callers see the final52 domain exception. Use `RetryError` only when callers intentionally consume53 retry-controller state.546. Attach structured `before_sleep` telemetry without secrets. Log only an55 attempt that will actually retry, not every call as an error.567. Test with zero wait/fake sleep and deterministic outcomes. Assert attempt57 count, retry classification, final exception/result, and side effects.5859## Policy decision table6061| Condition | Action |62|---|---|63| Operation is not repeat-safe | Do not retry; add idempotency/transaction semantics first. |64| Failure is permanent or unknown | Propagate immediately. |65| Client already retries | Configure one owner; prevent multiplicative nested attempts. |66| Attempts are cheap and local | Small attempt bound; `wait_none`/fixed wait only if pressure is irrelevant. |67| Remote service is contended | Bounded exponential random wait with cap. |68| Caller has a hard deadline | Stop by elapsed time/attempts beneath that deadline; retain transport timeout per attempt. |69| Async operation | Use async-decorated function or `AsyncRetrying`; never block the loop with `time.sleep`. |70| Return value signals transient incompleteness | Use `retry_if_result` only when the result has an unambiguous retry state. |7172## Canonical bounded policy7374```python75from tenacity import (76 retry,77 retry_if_exception_type,78 stop_after_attempt,79 wait_random_exponential,80)818283class TemporaryStoreError(Exception):84 pass858687@retry(88 retry=retry_if_exception_type(TemporaryStoreError),89 stop=stop_after_attempt(4),90 wait=wait_random_exponential(multiplier=0.25, max=4),91 reraise=True,92)93def load_record(store, record_id: str):94 return store.load(record_id)95```9697The operation still needs a per-attempt timeout. Tenacity bounds retrying, not98an individual call stuck forever. Do not decorate an entire workflow when only99one read is retryable; repeat the narrowest safe unit.100101## Side effects and nested budgets102103- Reads are not automatically safe if they consume messages or advance cursors.104- Writes require a stable idempotency key, transactional upsert, or explicit105 proof that a repeated request cannot duplicate effects.106- A timeout does not prove the server did nothing. Treat an ambiguous write107 outcome separately from a known pre-commit failure.108- Multiply configured layers to find the real worst-case attempts. Prefer one109 retry owner and one outer deadline.110- Do not retry `BaseException`, cancellation, keyboard interrupts, or a blanket111 `Exception` just because examples do.112113Read [policy and testing](references/policy-testing.md) for budgets, deterministic114tests, and non-idempotent operations.115116## Async and observability117118Tenacity supports coroutines and `AsyncRetrying`. Ensure the awaited client119call, sleep function, cancellation behavior, and caller deadline all remain120async. In `before_sleep`, record operation name, attempt, elapsed time, next121delay, and exception class; exclude credentials, payloads, and full response122bodies. A counter should distinguish attempts from completed calls and terminal123failures. Read [async and observability](references/async-observability.md).124125## Version grounding and completion126127Inspect the installed version of Tenacity and its signatures before128using a copied helper or callback field. This foundry did not have Tenacity129installed during authoring, so examples are source-grounded but not locally130executed. Do not turn that into a runtime-version claim.131132Completion requires: repetition safety is proven; retry and non-retry failures133are enumerated; per-attempt timeout and overall stop are finite; wait avoids a134hot loop; terminal exceptions match the caller contract; async code does not135block; telemetry reveals attempts without leaking data; and deterministic tests136prove attempt counts, terminal behavior, and exactly-once visible effects.137138## References139140- [Retry state model](references/retry-model.md)141- [Policy and deterministic testing](references/policy-testing.md)142- [Async and observability](references/async-observability.md)