Typing stubs for retry

Warnings

• gotcha The `types-retry` package only provides type hints. You must separately install the actual `retry` runtime library (`pip install retry`) for your code to function. Forgetting the runtime library is a common oversight.
  Fix: Ensure both `pip install retry` and `pip install types-retry` are executed in your environment.
• gotcha There are multiple Python libraries offering retry functionality (e.g., `retry`, `retrying`, `tenacity`). `types-retry` specifically provides stubs for the `retry` library (often associated with `github.com/invl/retry`). Ensure you are using the correct runtime library if you are relying on these type stubs.
  Fix: Verify that your `import` statements and usage align with the `retry` library, not `retrying` or `tenacity`.
• gotcha By default, the `@retry` decorator retries indefinitely if no `tries` parameter is specified. This can lead to infinite loops in case of persistent errors, consuming resources or hanging applications.
  Fix: Always set a `tries` limit (e.g., `tries=3`) or a `stop` condition (e.g., `stop_max_delay`) to prevent infinite retries.
• breaking As part of `typeshed`, `types-retry` aims to provide accurate annotations for specific versions of the `retry` library (e.g., `retry==0.9.*` for `types-retry==0.9.*`). Major updates to the `retry` library's API might cause type-checking failures if your `types-retry` version is not compatible with your installed `retry` version.
  Fix: Pin your `types-retry` version to match the expected `retry` library version, or explicitly manage compatibility. For example, if you use `retry==0.9.x`, use `types-retry>=0.9.0,<1.0.0` or `types-retry==0.9.9.20260408` (specific release of stubs).
• gotcha Type changes in stub packages can sometimes cause type checkers to fail even if the runtime code remains unchanged. `typeshed` strives to minimize this, but it can occur. Older `mypy` versions might also misinterpret newer `typeshed` features, silently losing type precision.
  Fix: Consider pinning specific versions of `types-retry` and your type checker (e.g., `mypy`) in your development environment to ensure consistent type checking results.

Install

• pip install retry Install the runtime library
• pip install types-retry Install the typing stubs

Imports

• retry

  from retry import retry

  This is the primary decorator for adding retry logic to functions.
• retry_call

  from retry import retry_call

  Used to call a function with retry logic directly, without a decorator.

Quickstart

This quickstart demonstrates how to apply the `@retry` decorator to an unreliable function. It configures the decorator to retry specifically on `ConnectionError` exceptions, up to 3 times, with a 2-second delay between attempts. Without `types-retry`, type checkers would have limited understanding of the decorator's effects on the function signature; with it, they can provide more accurate analysis.

import random
from retry import retry
import os

# Example function that might fail
def unreliable_service_call() -> str:
    if random.random() < 0.7:  # 70% chance of failure
        raise ConnectionError("Failed to connect to service!")
    return "Service data retrieved successfully!"

# Decorate the function with retry logic
@retry(exceptions=ConnectionError, tries=3, delay=2000) # Retry 3 times, with 2-second delay
def call_with_retry() -> str:
    print("Attempting service call...")
    return unreliable_service_call()

if __name__ == "__main__":
    try:
        result = call_with_retry()
        print(result)
    except Exception as e:
        print(f"All retry attempts failed: {e}")