Tenacity

Overview of the Retry Pattern In modern software development, your code rarely lives in a vacuum. It communicates with databases, external APIs, and Large Language Models (LLMs). These connections are prone to **transient failures**—brief, temporary issues like network hiccups or rate limits that cause a script to crash even when the logic is perfect. The **Retry Pattern** solves this by wrapping potentially flaky operations in a loop that automatically attempts the action again before giving up. This simple architectural shift transforms fragile scripts into robust, production-grade applications. Prerequisites To follow this guide, you should be comfortable with Python fundamentals, specifically: * **Higher-order functions**: Understanding how to pass functions as arguments. * **Decorators**: Familiarity with the `@` syntax and function wrapping. * **Type Hinting**: Knowledge of `Callable`, `Generics`, and the `typing` module. * **Exception Handling**: Using `try/except` blocks to manage errors. Key Libraries & Tools * Python (v3.10+ recommended for advanced typing). * **functools**: A standard library used for `wraps` to maintain function metadata. * Tenacity: A powerful, specialized library for retrying tasks in production. * SerpApi: A tool for reliable search engine data extraction that handles retries internally. Code Walkthrough: From Simple Loops to Decorators 1. The Basic Retry Loop A manual retry function uses a `range` loop to attempt an operation. If the operation succeeds, it returns immediately; if it fails, it sleeps before the next attempt. ```python from typing import Callable, TypeVar import time T = TypeVar("T") def retry(operation: Callable[[], T], retries: int = 3, delay: float = 1.0) -> T: for attempt in range(1, retries + 1): try: return operation() except Exception as e: if attempt == retries: raise e time.sleep(delay) ``` 2. Exponential Backoff Retrying too quickly can overwhelm a struggling server. **Exponential backoff** increases the wait time after each failure, giving the remote service breathing room to recover. ```python Inside the retry logic sleep_time = delay * (backoff_factor ** (attempt - 1)) time.sleep(sleep_time) ``` 3. The Decorator Implementation To make retry logic reusable across your entire codebase without manual calls, we can implement a decorator. This uses `functools.wraps` to ensure that the decorated function retains its original name and docstring. ```python from functools import wraps def retry_decorator(retries=3, delay=1.0): def decorator(func): @wraps(func) def wrapper(*args, **kwargs): for attempt in range(retries): try: return func(*args, **kwargs) except Exception as e: if attempt == retries - 1: raise e time.sleep(delay) return wrapper return decorator ``` Syntax Notes: Callable and Generics When building these utilities, use **TypeVars** (like `T`) to ensure the `retry` function returns the same type as the original operation. This maintains IDE autocomplete and type safety. Additionally, the `Callable[[], T]` syntax specifies that the function takes no arguments and returns type `T`. For functions with arguments, use `Callable[..., T]` or specific parameter lists. Practical Examples * **LLM JSON Parsing**: LLMs like those from OpenAI occasionally return malformed JSON. A retry pattern allows the code to re-prompt or re-parse the response without crashing the pipeline. * **Web Scraping**: When using tools like SerpApi, retries handle network timeouts or rotating proxy shifts automatically, ensuring data consistency. * **Database Connections**: Brief lockouts or connection resets can be mitigated with a 2-second retry window. Tips & Gotchas * **Avoid Permanent Errors**: Never retry a 404 (Not Found) or 401 (Unauthorized) error. Retrying will not fix a wrong URL or an invalid API key; it only wastes resources. * **Side Effects**: Ensure the operation is **idempotent**. If a function writes to a database before failing, retrying might create duplicate entries. * **Production Use**: For mission-critical code, use Tenacity. It offers advanced features like "jitter" (randomized delays) to prevent "retry storms" where multiple clients hit a server simultaneously.