Tenacity Python

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

Read the retry state model before composing predicates, retrying results, or using block iteration.

Ordered workflow

1. Name the exact attempted operation and its side effect. Establish whether repetition is safe, conditionally safe through an idempotency key, or unsafe.
2. Classify failures from the real client/library: retry only enumerated transient exceptions or results. Exclude cancellation, invalid input, permission/auth failures, and deterministic defects.
3. Establish the outer deadline/budget. Choose a finite stop condition that cannot outlive it; attempts include the first call.
4. 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.
5. Decide terminal failure: normally reraise=True so callers see the final domain exception. Use RetryError only when callers intentionally consume retry-controller state.
6. Attach structured before_sleep telemetry without secrets. Log only an attempt that will actually retry, not every call as an error.
7. Test with zero wait/fake sleep and deterministic outcomes. Assert attempt count, retry classification, final exception/result, and side effects.

Policy decision table

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