retryflow 1.0.0__tar.gz

retryflow-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 prabhay759
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

retryflow-1.0.0/PKG-INFO

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: retryflow
+Version: 1.0.0
+Summary: Smart retry engine with exponential backoff, jitter, per-exception rules, timeout, and async support
+Author: prabhay759
+License: MIT
+Project-URL: Homepage, https://github.com/prabhay759/retryflow
+Project-URL: Repository, https://github.com/prabhay759/retryflow
+Project-URL: Issues, https://github.com/prabhay759/retryflow/issues
+Keywords: retry,backoff,resilience,async,timeout,decorator
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Dynamic: license-file
+
+# retryflow
+
+> Smart retry engine for Python — exponential backoff, jitter, per-exception rules, per-attempt timeout, hooks, and full async support.
+
+[![PyPI version](https://img.shields.io/pypi/v/retryflow.svg)](https://pypi.org/project/retryflow/)
+[![Python](https://img.shields.io/pypi/pyversions/retryflow.svg)](https://pypi.org/project/retryflow/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)]()
+
+---
+
+## Why retryflow?
+
+Every app that talks to a network, a database, or an external API will eventually hit a transient failure. `retryflow` gives you a battle-tested, zero-dependency retry engine that handles the hard parts:
+
+- **Exponential backoff** so you don't hammer a struggling service
+- **Jitter** to avoid thundering-herd problems across multiple clients
+- **Per-attempt timeouts** so a single hung call can't block forever
+- **Per-exception rules** so you only retry errors that make sense to retry
+- **Lifecycle hooks** (`on_retry`, `on_success`, `on_failure`) for logging, alerting, metrics
+- **Native async support** — works seamlessly with `async def` functions
+- **Context manager API** for one-off retry blocks without decorating a function
+
+---
+
+## Installation
+
+```bash
+pip install retryflow
+```
+
+No dependencies. Requires Python 3.8+.
+
+---
+
+## Quick Start
+
+```python
+from retryflow import retry
+
+@retry(max_attempts=3, delay=1.0, backoff=2.0)
+def fetch_data(url):
+    response = requests.get(url, timeout=5)
+    response.raise_for_status()
+    return response.json()
+```
+
+That's it. On failure, retryflow waits 1s, then 2s, then raises `RetryError`.
+
+---
+
+## Usage
+
+### 1. Basic Decorator
+
+```python
+from retryflow import retry
+
+@retry(max_attempts=5, delay=0.5, backoff=2.0, jitter=0.1)
+def call_api():
+    ...
+```
+
+Also works with no arguments (uses defaults):
+
+```python
+@retry
+def call_api():
+    ...
+```
+
+### 2. Per-Attempt Timeout
+
+Stop a single attempt if it hangs beyond a time limit:
+
+```python
+@retry(max_attempts=3, delay=1.0, timeout=5.0)
+def slow_query():
+    # If this takes more than 5s, a TimeoutError is raised
+    # and retryflow retries it
+    return db.execute(heavy_query)
+```
+
+### 3. Retry Only Specific Exceptions
+
+```python
+@retry(
+    max_attempts=5,
+    delay=1.0,
+    exceptions=(ConnectionError, TimeoutError)  # Only retry these
+)
+def connect():
+    ...
+```
+
+Non-matching exceptions (e.g., `ValueError`) propagate immediately without retrying.
+
+### 4. Lifecycle Hooks
+
+```python
+from retryflow import retry, RetryContext
+
+def on_retry(ctx: RetryContext):
+    print(f"Attempt {ctx.attempt}/{ctx.max_attempts} failed: {ctx.exception}")
+    print(f"Retrying in {ctx.next_wait:.2f}s...")
+
+def on_failure(ctx: RetryContext):
+    alert_team(f"{ctx.func_name} failed after {ctx.attempts} attempts")
+
+def on_success(ctx: RetryContext):
+    metrics.record("api.success", tags={"attempt": ctx.attempt})
+
+@retry(
+    max_attempts=5,
+    delay=1.0,
+    on_retry=on_retry,
+    on_failure=on_failure,
+    on_success=on_success,
+)
+def critical_call():
+    ...
+```
+
+### 5. Async Functions
+
+Works exactly the same — retryflow detects `async def` automatically:
+
+```python
+@retry(max_attempts=4, delay=0.5, timeout=3.0)
+async def async_fetch(url):
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url) as resp:
+            return await resp.json()
+```
+
+### 6. Reusable Config Object
+
+```python
+from retryflow import retry, RetryConfig
+
+# Define once, apply everywhere
+production_retry = RetryConfig(
+    max_attempts=5,
+    delay=1.0,
+    backoff=2.0,
+    jitter=0.3,
+    timeout=10.0,
+    exceptions=(ConnectionError, TimeoutError),
+    log_retries=True,
+)
+
+@retry(config=production_retry)
+def service_a(): ...
+
+@retry(config=production_retry)
+def service_b(): ...
+```
+
+### 7. Context Manager
+
+For one-off retries without decorating a function:
+
+```python
+from retryflow import attempt
+
+with attempt(max_attempts=3, delay=1.0, timeout=5.0) as r:
+    data = r.run(fetch, "https://api.example.com/data")
+
+print(f"Completed in {r.elapsed:.2f}s")
+```
+
+---
+
+## API Reference
+
+### `@retry` decorator
+
+```python
+retry(
+    func=None,              # The function to wrap (when used without parentheses)
+    *,
+    max_attempts=3,         # Total attempts including the first call
+    delay=1.0,              # Base delay in seconds between attempts
+    backoff=2.0,            # Delay multiplier (1.0=constant, 2.0=exponential)
+    jitter=0.0,             # Random seconds added to each wait (0 to jitter)
+    timeout=None,           # Max seconds per attempt (None = no limit)
+    exceptions=(Exception,),# Only retry on these exception types
+    on_retry=None,          # Callable(RetryContext) called before each retry
+    on_failure=None,        # Callable(RetryContext) called when all attempts fail
+    on_success=None,        # Callable(RetryContext) called on success
+    log_retries=True,       # Emit warning logs on each retry
+    config=None,            # RetryConfig object (overrides all other params)
+)
+```
+
+### `RetryConfig`
+
+All the same parameters as `@retry`, packaged into a reusable object.
+
+```python
+cfg = RetryConfig(max_attempts=5, delay=1.0, backoff=2.0, timeout=10.0)
+```
+
+### `RetryContext`
+
+Passed to hook callbacks with information about the current state.
+
+| Attribute | Type | Description |
+|---|---|---|
+| `attempt` | `int` | Current attempt number (1-indexed) |
+| `max_attempts` | `int` | Total configured attempts |
+| `exception` | `Exception` | The exception that just occurred |
+| `elapsed` | `float` | Total elapsed seconds since first attempt |
+| `next_wait` | `float \| None` | Seconds until next retry (None on final attempt) |
+| `func_name` | `str` | Name of the decorated function |
+
+### `RetryError`
+
+Raised when all attempts are exhausted.
+
+| Attribute | Type | Description |
+|---|---|---|
+| `last_exception` | `Exception` | The final exception raised |
+| `attempts` | `int` | Total number of attempts made |
+
+### `attempt` context manager
+
+```python
+with attempt(max_attempts=3, delay=1.0, ...) as r:
+    result = r.run(func, *args, **kwargs)
+```
+
+After the `with` block, `r.result`, `r.elapsed`, `r.last_error`, and `r.total_attempts` are available.
+
+---
+
+## Backoff Formula
+
+```
+wait = delay * (backoff ^ (attempt - 1)) + random(0, jitter)
+```
+
+| attempt | delay=1, backoff=2 | delay=0.5, backoff=3 |
+|---|---|---|
+| 1st retry | 1.0s | 0.5s |
+| 2nd retry | 2.0s | 1.5s |
+| 3rd retry | 4.0s | 4.5s |
+
+---
+
+## Running Tests
+
+```bash
+pip install pytest pytest-asyncio
+pytest tests/ -v
+```
+
+---
+
+## License
+
+MIT © prabhay759

retryflow-1.0.0/README.md

@@ -0,0 +1,262 @@
+# retryflow
+
+> Smart retry engine for Python — exponential backoff, jitter, per-exception rules, per-attempt timeout, hooks, and full async support.
+
+[![PyPI version](https://img.shields.io/pypi/v/retryflow.svg)](https://pypi.org/project/retryflow/)
+[![Python](https://img.shields.io/pypi/pyversions/retryflow.svg)](https://pypi.org/project/retryflow/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)]()
+
+---
+
+## Why retryflow?
+
+Every app that talks to a network, a database, or an external API will eventually hit a transient failure. `retryflow` gives you a battle-tested, zero-dependency retry engine that handles the hard parts:
+
+- **Exponential backoff** so you don't hammer a struggling service
+- **Jitter** to avoid thundering-herd problems across multiple clients
+- **Per-attempt timeouts** so a single hung call can't block forever
+- **Per-exception rules** so you only retry errors that make sense to retry
+- **Lifecycle hooks** (`on_retry`, `on_success`, `on_failure`) for logging, alerting, metrics
+- **Native async support** — works seamlessly with `async def` functions
+- **Context manager API** for one-off retry blocks without decorating a function
+
+---
+
+## Installation
+
+```bash
+pip install retryflow
+```
+
+No dependencies. Requires Python 3.8+.
+
+---
+
+## Quick Start
+
+```python
+from retryflow import retry
+
+@retry(max_attempts=3, delay=1.0, backoff=2.0)
+def fetch_data(url):
+    response = requests.get(url, timeout=5)
+    response.raise_for_status()
+    return response.json()
+```
+
+That's it. On failure, retryflow waits 1s, then 2s, then raises `RetryError`.
+
+---
+
+## Usage
+
+### 1. Basic Decorator
+
+```python
+from retryflow import retry
+
+@retry(max_attempts=5, delay=0.5, backoff=2.0, jitter=0.1)
+def call_api():
+    ...
+```
+
+Also works with no arguments (uses defaults):
+
+```python
+@retry
+def call_api():
+    ...
+```
+
+### 2. Per-Attempt Timeout
+
+Stop a single attempt if it hangs beyond a time limit:
+
+```python
+@retry(max_attempts=3, delay=1.0, timeout=5.0)
+def slow_query():
+    # If this takes more than 5s, a TimeoutError is raised
+    # and retryflow retries it
+    return db.execute(heavy_query)
+```
+
+### 3. Retry Only Specific Exceptions
+
+```python
+@retry(
+    max_attempts=5,
+    delay=1.0,
+    exceptions=(ConnectionError, TimeoutError)  # Only retry these
+)
+def connect():
+    ...
+```
+
+Non-matching exceptions (e.g., `ValueError`) propagate immediately without retrying.
+
+### 4. Lifecycle Hooks
+
+```python
+from retryflow import retry, RetryContext
+
+def on_retry(ctx: RetryContext):
+    print(f"Attempt {ctx.attempt}/{ctx.max_attempts} failed: {ctx.exception}")
+    print(f"Retrying in {ctx.next_wait:.2f}s...")
+
+def on_failure(ctx: RetryContext):
+    alert_team(f"{ctx.func_name} failed after {ctx.attempts} attempts")
+
+def on_success(ctx: RetryContext):
+    metrics.record("api.success", tags={"attempt": ctx.attempt})
+
+@retry(
+    max_attempts=5,
+    delay=1.0,
+    on_retry=on_retry,
+    on_failure=on_failure,
+    on_success=on_success,
+)
+def critical_call():
+    ...
+```
+
+### 5. Async Functions
+
+Works exactly the same — retryflow detects `async def` automatically:
+
+```python
+@retry(max_attempts=4, delay=0.5, timeout=3.0)
+async def async_fetch(url):
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url) as resp:
+            return await resp.json()
+```
+
+### 6. Reusable Config Object
+
+```python
+from retryflow import retry, RetryConfig
+
+# Define once, apply everywhere
+production_retry = RetryConfig(
+    max_attempts=5,
+    delay=1.0,
+    backoff=2.0,
+    jitter=0.3,
+    timeout=10.0,
+    exceptions=(ConnectionError, TimeoutError),
+    log_retries=True,
+)
+
+@retry(config=production_retry)
+def service_a(): ...
+
+@retry(config=production_retry)
+def service_b(): ...
+```
+
+### 7. Context Manager
+
+For one-off retries without decorating a function:
+
+```python
+from retryflow import attempt
+
+with attempt(max_attempts=3, delay=1.0, timeout=5.0) as r:
+    data = r.run(fetch, "https://api.example.com/data")
+
+print(f"Completed in {r.elapsed:.2f}s")
+```
+
+---
+
+## API Reference
+
+### `@retry` decorator
+
+```python
+retry(
+    func=None,              # The function to wrap (when used without parentheses)
+    *,
+    max_attempts=3,         # Total attempts including the first call
+    delay=1.0,              # Base delay in seconds between attempts
+    backoff=2.0,            # Delay multiplier (1.0=constant, 2.0=exponential)
+    jitter=0.0,             # Random seconds added to each wait (0 to jitter)
+    timeout=None,           # Max seconds per attempt (None = no limit)
+    exceptions=(Exception,),# Only retry on these exception types
+    on_retry=None,          # Callable(RetryContext) called before each retry
+    on_failure=None,        # Callable(RetryContext) called when all attempts fail
+    on_success=None,        # Callable(RetryContext) called on success
+    log_retries=True,       # Emit warning logs on each retry
+    config=None,            # RetryConfig object (overrides all other params)
+)
+```
+
+### `RetryConfig`
+
+All the same parameters as `@retry`, packaged into a reusable object.
+
+```python
+cfg = RetryConfig(max_attempts=5, delay=1.0, backoff=2.0, timeout=10.0)
+```
+
+### `RetryContext`
+
+Passed to hook callbacks with information about the current state.
+
+| Attribute | Type | Description |
+|---|---|---|
+| `attempt` | `int` | Current attempt number (1-indexed) |
+| `max_attempts` | `int` | Total configured attempts |
+| `exception` | `Exception` | The exception that just occurred |
+| `elapsed` | `float` | Total elapsed seconds since first attempt |
+| `next_wait` | `float \| None` | Seconds until next retry (None on final attempt) |
+| `func_name` | `str` | Name of the decorated function |
+
+### `RetryError`
+
+Raised when all attempts are exhausted.
+
+| Attribute | Type | Description |
+|---|---|---|
+| `last_exception` | `Exception` | The final exception raised |
+| `attempts` | `int` | Total number of attempts made |
+
+### `attempt` context manager
+
+```python
+with attempt(max_attempts=3, delay=1.0, ...) as r:
+    result = r.run(func, *args, **kwargs)
+```
+
+After the `with` block, `r.result`, `r.elapsed`, `r.last_error`, and `r.total_attempts` are available.
+
+---
+
+## Backoff Formula
+
+```
+wait = delay * (backoff ^ (attempt - 1)) + random(0, jitter)
+```
+
+| attempt | delay=1, backoff=2 | delay=0.5, backoff=3 |
+|---|---|---|
+| 1st retry | 1.0s | 0.5s |
+| 2nd retry | 2.0s | 1.5s |
+| 3rd retry | 4.0s | 4.5s |
+
+---
+
+## Running Tests
+
+```bash
+pip install pytest pytest-asyncio
+pytest tests/ -v
+```
+
+---
+
+## License
+
+MIT © prabhay759

retryflow-1.0.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "retryflow"
+version = "1.0.0"
+description = "Smart retry engine with exponential backoff, jitter, per-exception rules, timeout, and async support"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "prabhay759" }]
+keywords = ["retry", "backoff", "resilience", "async", "timeout", "decorator"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-asyncio>=0.21"]
+
+[project.urls]
+Homepage = "https://github.com/prabhay759/retryflow"
+Repository = "https://github.com/prabhay759/retryflow"
+Issues = "https://github.com/prabhay759/retryflow/issues"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

retryflow-1.0.0/retryflow/__init__.py

@@ -0,0 +1,11 @@
+"""
+retryflow — Smart retry engine with exponential backoff, jitter,
+per-exception rules, timeout support, and async compatibility.
+"""
+
+from .core import retry, RetryConfig, RetryError, RetryContext
+from .context import attempt
+
+__all__ = ["retry", "RetryConfig", "RetryError", "RetryContext", "attempt"]
+__version__ = "1.0.0"
+__author__ = "prabhay759"

retryflow-1.0.0/retryflow/context.py

@@ -0,0 +1,84 @@
+"""
+retryflow.context
+-----------------
+Context manager interface for retryflow.
+
+Usage:
+    with attempt(max_attempts=3, delay=1) as r:
+        result = r.run(some_function, arg1, arg2)
+"""
+
+import time
+from typing import Any, Callable, Optional, Tuple, Type
+
+from .core import RetryConfig, RetryContext, RetryError, _sync_retry
+
+
+class attempt:
+    """
+    Context manager that executes a callable with retry logic.
+
+    Example
+    -------
+    >>> with attempt(max_attempts=3, delay=0.5, timeout=5) as r:
+    ...     data = r.run(fetch_data, url)
+
+    Parameters
+    ----------
+    Same as RetryConfig / @retry decorator.
+    """
+
+    def __init__(
+        self,
+        max_attempts: int = 3,
+        delay: float = 1.0,
+        backoff: float = 2.0,
+        jitter: float = 0.0,
+        timeout: Optional[float] = None,
+        exceptions: Tuple[Type[Exception], ...] = (Exception,),
+        on_retry=None,
+        on_failure=None,
+        on_success=None,
+        log_retries: bool = True,
+        config: Optional[RetryConfig] = None,
+    ):
+        self._cfg = config or RetryConfig(
+            max_attempts=max_attempts,
+            delay=delay,
+            backoff=backoff,
+            jitter=jitter,
+            timeout=timeout,
+            exceptions=exceptions,
+            on_retry=on_retry,
+            on_failure=on_failure,
+            on_success=on_success,
+            log_retries=log_retries,
+        )
+        self.result: Any = None
+        self.last_error: Optional[Exception] = None
+        self.total_attempts: int = 0
+        self.elapsed: float = 0.0
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        return False  # Never suppress exceptions from the with-block body
+
+    def run(self, func: Callable, *args, **kwargs) -> Any:
+        """
+        Execute func(*args, **kwargs) with the configured retry policy.
+
+        Returns the function's return value, or raises RetryError if
+        all attempts are exhausted.
+        """
+        start = time.monotonic()
+        try:
+            self.result = _sync_retry(func, self._cfg, args, kwargs)
+        except RetryError as e:
+            self.last_error = e.last_exception
+            self.total_attempts = e.attempts
+            self.elapsed = time.monotonic() - start
+            raise
+        self.elapsed = time.monotonic() - start
+        return self.result