retryhttp2 0.1.0__tar.gz

retryhttp2-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  release:
+    types: [published]
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest --tb=short -q
+
+  publish:
+    name: Publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release'
+    environment: pypi
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install hatch
+
+      - name: Build package
+        run: hatch build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

retryhttp2-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.pytest_cache/
+.mypy_cache/
+*.so

retryhttp2-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Praneeth Vedantham
+
+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.

retryhttp2-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: retryhttp2
+Version: 0.1.0
+Summary: Zero-config HTTP retries with exponential backoff, jitter, and OAuth2 token refresh for httpx and requests
+Project-URL: Homepage, https://github.com/praneethv2003/retryhttp
+Project-URL: Repository, https://github.com/praneethv2003/retryhttp
+Project-URL: Issues, https://github.com/praneethv2003/retryhttp/issues
+Author-email: Praneeth Vedantham <praneethvedantham@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: backoff,http,httpx,oauth2,requests,retry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: httpx>=0.25; extra == 'all'
+Requires-Dist: requests>=2.28; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: httpx>=0.25; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.28; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: requests>=2.28; extra == 'dev'
+Requires-Dist: responses>=0.24; extra == 'dev'
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.25; extra == 'httpx'
+Provides-Extra: requests
+Requires-Dist: requests>=2.28; extra == 'requests'
+Description-Content-Type: text/markdown
+
+# retryhttp
+
+Zero-config HTTP retries with exponential backoff, jitter, and OAuth2 token refresh — for both **httpx** and **requests**.
+
+```python
+from retryhttp import RetryClient
+
+with RetryClient(token_refresher=lambda: fetch_token()) as client:
+    resp = client.get("https://api.example.com/data")
+```
+
+## Why
+
+Every team rewrites retry logic from scratch. `retryhttp` gives you:
+
+- **Exponential backoff with full jitter** (AWS-recommended strategy)
+- **Token refresh hooks** — pass a callable, 401s are handled automatically
+- **Per-status-code retry policies** — retry 503 but not 404
+- **Network error retries** — connection errors and timeouts included
+- **Async support** via `AsyncRetryClient`
+- **Drop-in replacements** — subclasses `httpx.Client` and `requests.Session`, so existing code works unchanged
+
+## Install
+
+```bash
+# httpx support
+pip install "retryhttp[httpx]"
+
+# requests support
+pip install "retryhttp[requests]"
+
+# both
+pip install "retryhttp[all]"
+```
+
+## Usage
+
+### httpx (sync)
+
+```python
+from retryhttp import RetryClient, RetryConfig
+
+config = RetryConfig(
+    max_attempts=5,
+    backoff_base=0.5,
+    backoff_max=30.0,
+    retry_statuses=frozenset({429, 500, 502, 503, 504}),
+)
+
+def get_token() -> str:
+    # call your auth server
+    return "new-bearer-token"
+
+with RetryClient(config=config, token_refresher=get_token) as client:
+    resp = client.get("https://api.example.com/resource")
+    print(resp.json())
+```
+
+### httpx (async)
+
+```python
+import asyncio
+from retryhttp import AsyncRetryClient
+
+async def get_token() -> str:
+    return "new-bearer-token"
+
+async def main():
+    async with AsyncRetryClient(token_refresher=get_token) as client:
+        resp = await client.get("https://api.example.com/resource")
+        print(resp.json())
+
+asyncio.run(main())
+```
+
+### requests
+
+```python
+from retryhttp import RetrySession
+
+with RetrySession(token_refresher=lambda: "new-token") as session:
+    resp = session.get("https://api.example.com/resource")
+```
+
+## Configuration
+
+`RetryConfig` controls all retry behaviour:
+
+| Parameter | Default | Description |
+|---|---|---|
+| `max_attempts` | `3` | Total attempts (1 = no retries) |
+| `retry_statuses` | `{429,500,502,503,504}` | Status codes that trigger a retry |
+| `backoff_base` | `1.0` | Base backoff in seconds |
+| `backoff_max` | `60.0` | Maximum backoff ceiling |
+| `jitter` | `True` | Full jitter on each delay |
+| `retry_on_network_error` | `True` | Retry on connection/timeout errors |
+| `token_refresh_status` | `401` | Status that triggers token refresh |
+| `raise_on_exhaust` | `True` | Raise `RetryExhausted` when all attempts fail; `False` returns the last response |
+
+## How backoff works
+
+Uses AWS's **Full Jitter** strategy:
+
+```
+cap = min(backoff_max, backoff_base × 2^attempt)
+sleep = random(0, cap)
+```
+
+This avoids thundering-herd problems when many clients retry simultaneously.
+
+## Exceptions
+
+```python
+from retryhttp import RetryExhausted
+
+try:
+    client.get("https://api.example.com")
+except RetryExhausted as e:
+    print(f"Failed after {e.attempts} attempts, last status: {e.last_status}")
+```
+
+## Development
+
+```bash
+git clone https://github.com/praneethvedantham/retryhttp
+cd retryhttp
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

retryhttp2-0.1.0/README.md

@@ -0,0 +1,133 @@
+# retryhttp
+
+Zero-config HTTP retries with exponential backoff, jitter, and OAuth2 token refresh — for both **httpx** and **requests**.
+
+```python
+from retryhttp import RetryClient
+
+with RetryClient(token_refresher=lambda: fetch_token()) as client:
+    resp = client.get("https://api.example.com/data")
+```
+
+## Why
+
+Every team rewrites retry logic from scratch. `retryhttp` gives you:
+
+- **Exponential backoff with full jitter** (AWS-recommended strategy)
+- **Token refresh hooks** — pass a callable, 401s are handled automatically
+- **Per-status-code retry policies** — retry 503 but not 404
+- **Network error retries** — connection errors and timeouts included
+- **Async support** via `AsyncRetryClient`
+- **Drop-in replacements** — subclasses `httpx.Client` and `requests.Session`, so existing code works unchanged
+
+## Install
+
+```bash
+# httpx support
+pip install "retryhttp[httpx]"
+
+# requests support
+pip install "retryhttp[requests]"
+
+# both
+pip install "retryhttp[all]"
+```
+
+## Usage
+
+### httpx (sync)
+
+```python
+from retryhttp import RetryClient, RetryConfig
+
+config = RetryConfig(
+    max_attempts=5,
+    backoff_base=0.5,
+    backoff_max=30.0,
+    retry_statuses=frozenset({429, 500, 502, 503, 504}),
+)
+
+def get_token() -> str:
+    # call your auth server
+    return "new-bearer-token"
+
+with RetryClient(config=config, token_refresher=get_token) as client:
+    resp = client.get("https://api.example.com/resource")
+    print(resp.json())
+```
+
+### httpx (async)
+
+```python
+import asyncio
+from retryhttp import AsyncRetryClient
+
+async def get_token() -> str:
+    return "new-bearer-token"
+
+async def main():
+    async with AsyncRetryClient(token_refresher=get_token) as client:
+        resp = await client.get("https://api.example.com/resource")
+        print(resp.json())
+
+asyncio.run(main())
+```
+
+### requests
+
+```python
+from retryhttp import RetrySession
+
+with RetrySession(token_refresher=lambda: "new-token") as session:
+    resp = session.get("https://api.example.com/resource")
+```
+
+## Configuration
+
+`RetryConfig` controls all retry behaviour:
+
+| Parameter | Default | Description |
+|---|---|---|
+| `max_attempts` | `3` | Total attempts (1 = no retries) |
+| `retry_statuses` | `{429,500,502,503,504}` | Status codes that trigger a retry |
+| `backoff_base` | `1.0` | Base backoff in seconds |
+| `backoff_max` | `60.0` | Maximum backoff ceiling |
+| `jitter` | `True` | Full jitter on each delay |
+| `retry_on_network_error` | `True` | Retry on connection/timeout errors |
+| `token_refresh_status` | `401` | Status that triggers token refresh |
+| `raise_on_exhaust` | `True` | Raise `RetryExhausted` when all attempts fail; `False` returns the last response |
+
+## How backoff works
+
+Uses AWS's **Full Jitter** strategy:
+
+```
+cap = min(backoff_max, backoff_base × 2^attempt)
+sleep = random(0, cap)
+```
+
+This avoids thundering-herd problems when many clients retry simultaneously.
+
+## Exceptions
+
+```python
+from retryhttp import RetryExhausted
+
+try:
+    client.get("https://api.example.com")
+except RetryExhausted as e:
+    print(f"Failed after {e.attempts} attempts, last status: {e.last_status}")
+```
+
+## Development
+
+```bash
+git clone https://github.com/praneethvedantham/retryhttp
+cd retryhttp
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

retryhttp2-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "retryhttp2"
+version = "0.1.0"
+description = "Zero-config HTTP retries with exponential backoff, jitter, and OAuth2 token refresh for httpx and requests"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Praneeth Vedantham", email = "praneethvedantham@gmail.com" }]
+keywords = ["http", "retry", "backoff", "httpx", "requests", "oauth2"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+httpx = ["httpx>=0.25"]
+requests = ["requests>=2.28"]
+all = ["httpx>=0.25", "requests>=2.28"]
+dev = [
+    "httpx>=0.25",
+    "requests>=2.28",
+    "pytest>=7.4",
+    "pytest-asyncio>=0.23",
+    "pytest-httpx>=0.28",
+    "responses>=0.24",
+    "hatch",
+]
+
+[project.urls]
+Homepage = "https://github.com/praneethv2003/retryhttp"
+Repository = "https://github.com/praneethv2003/retryhttp"
+Issues = "https://github.com/praneethv2003/retryhttp/issues"
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/retryhttp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

retryhttp2-0.1.0/src/retryhttp/__init__.py

@@ -0,0 +1,20 @@
+"""retryhttp — zero-config HTTP retries with backoff and OAuth2 token refresh."""
+
+from retryhttp.retry import RetryConfig, RetryExhausted
+from retryhttp.backoff import backoff_delay
+
+__all__ = ["RetryConfig", "RetryExhausted", "backoff_delay"]
+
+try:
+    from retryhttp.httpx_client import RetryClient, AsyncRetryClient
+
+    __all__ += ["RetryClient", "AsyncRetryClient"]
+except ImportError:
+    pass
+
+try:
+    from retryhttp.requests_client import RetrySession
+
+    __all__ += ["RetrySession"]
+except ImportError:
+    pass

retryhttp2-0.1.0/src/retryhttp/backoff.py

@@ -0,0 +1,39 @@
+"""Backoff delay calculation."""
+
+from __future__ import annotations
+
+import random
+
+
+def backoff_delay(
+    attempt: int,
+    *,
+    base: float = 1.0,
+    maximum: float = 60.0,
+    jitter: bool = True,
+) -> float:
+    """Compute an exponential backoff delay with optional full jitter.
+
+    Uses the "Full Jitter" strategy from AWS architecture blog:
+    https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
+
+    Args:
+        attempt: Zero-indexed attempt number (0 = first retry → shortest delay).
+        base: Backoff base in seconds.
+        maximum: Hard ceiling on the computed delay.
+        jitter: When True, randomise within [0, computed_cap].
+
+    Returns:
+        Seconds to sleep before the next attempt.
+
+    Example::
+
+        for i in range(3):
+            time.sleep(backoff_delay(i, base=0.5, maximum=30))
+    """
+    if base <= 0:
+        raise ValueError("base must be positive")
+    cap = min(maximum, base * (2**attempt))
+    if jitter:
+        return random.uniform(0, cap)
+    return cap

retryhttp2-0.1.0/src/retryhttp/httpx_client.py

@@ -0,0 +1,234 @@
+"""httpx adapters: RetryClient (sync) and AsyncRetryClient."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+
+from retryhttp.backoff import backoff_delay
+from retryhttp.retry import RetryConfig, RetryExhausted
+
+logger = logging.getLogger(__name__)
+
+# Types for the token-refresh callable.
+# Sync: () -> str  |  Async: async () -> str
+TokenRefresher = Callable[[], str]
+AsyncTokenRefresher = Callable[[], Any]  # must be a coroutine function
+
+
+class RetryClient(httpx.Client):
+    """An httpx.Client that retries failed requests with exponential backoff.
+
+    Args:
+        config: Retry policy. Defaults to RetryConfig() (3 attempts, sane backoff).
+        token_refresher: Optional callable ``() -> str`` that returns a fresh
+            bearer token. Called automatically on 401 responses. The new token
+            is injected into ``self.headers["Authorization"]`` before the retry.
+        **kwargs: Forwarded verbatim to httpx.Client.
+
+    Example::
+
+        def refresh() -> str:
+            return fetch_new_token()
+
+        with RetryClient(token_refresher=refresh) as client:
+            resp = client.get("https://api.example.com/data")
+    """
+
+    def __init__(
+        self,
+        *,
+        config: RetryConfig | None = None,
+        token_refresher: TokenRefresher | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self.retry_config = config or RetryConfig()
+        self._token_refresher = token_refresher
+
+    def _maybe_refresh_token(self) -> None:
+        if self._token_refresher is not None:
+            new_token = self._token_refresher()
+            self.headers["Authorization"] = f"Bearer {new_token}"
+            logger.debug("retryhttp: token refreshed")
+
+    def send(self, request: httpx.Request, **kwargs: Any) -> httpx.Response:  # type: ignore[override]
+        cfg = self.retry_config
+        last_exc: Exception | None = None
+        last_response: httpx.Response | None = None
+
+        for attempt in range(cfg.max_attempts):
+            try:
+                response = super().send(request, **kwargs)
+            except (httpx.ConnectError, httpx.TimeoutException, httpx.NetworkError) as exc:
+                if not cfg.retry_on_network_error or attempt == cfg.max_attempts - 1:
+                    raise
+                last_exc = exc
+                delay = backoff_delay(attempt, base=cfg.backoff_base, maximum=cfg.backoff_max, jitter=cfg.jitter)
+                logger.warning(
+                    "retryhttp: network error on attempt %d/%d (%s), retrying in %.2fs",
+                    attempt + 1,
+                    cfg.max_attempts,
+                    exc,
+                    delay,
+                )
+                time.sleep(delay)
+                continue
+
+            last_response = response
+            last_exc = None
+
+            # Token refresh on 401.
+            if cfg.token_refresh_status and response.status_code == cfg.token_refresh_status:
+                if attempt < cfg.max_attempts - 1:
+                    logger.info("retryhttp: 401 received, refreshing token (attempt %d)", attempt + 1)
+                    self._maybe_refresh_token()
+                    # Re-build the request so the new Authorization header is sent.
+                    request = self.build_request(
+                        method=request.method,
+                        url=request.url,
+                        content=request.content,
+                        headers=dict(request.headers),
+                    )
+                    continue
+
+            if not cfg.should_retry_status(response.status_code):
+                return response
+
+            if attempt == cfg.max_attempts - 1:
+                if cfg.raise_on_exhaust:
+                    raise RetryExhausted(
+                        f"All {cfg.max_attempts} attempts failed",
+                        attempts=cfg.max_attempts,
+                        last_status=response.status_code,
+                    )
+                return response
+
+            delay = backoff_delay(attempt, base=cfg.backoff_base, maximum=cfg.backoff_max, jitter=cfg.jitter)
+            logger.warning(
+                "retryhttp: HTTP %d on attempt %d/%d, retrying in %.2fs",
+                response.status_code,
+                attempt + 1,
+                cfg.max_attempts,
+                delay,
+            )
+            time.sleep(delay)
+
+        # Should only be reached via network-error path exhaustion.
+        if cfg.raise_on_exhaust:
+            raise RetryExhausted(
+                f"All {cfg.max_attempts} attempts failed",
+                attempts=cfg.max_attempts,
+                last_status=last_response.status_code if last_response else None,
+            )
+        assert last_response is not None
+        return last_response
+
+
+class AsyncRetryClient(httpx.AsyncClient):
+    """An async httpx.AsyncClient that retries with exponential backoff.
+
+    Args:
+        config: Retry policy.
+        token_refresher: Optional *async* callable ``async () -> str``.
+        **kwargs: Forwarded to httpx.AsyncClient.
+
+    Example::
+
+        async def refresh() -> str:
+            return await fetch_new_token_async()
+
+        async with AsyncRetryClient(token_refresher=refresh) as client:
+            resp = await client.get("https://api.example.com/data")
+    """
+
+    def __init__(
+        self,
+        *,
+        config: RetryConfig | None = None,
+        token_refresher: AsyncTokenRefresher | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self.retry_config = config or RetryConfig()
+        self._token_refresher = token_refresher
+
+    async def _maybe_refresh_token(self) -> None:
+        if self._token_refresher is not None:
+            if asyncio.iscoroutinefunction(self._token_refresher):
+                new_token = await self._token_refresher()
+            else:
+                new_token = self._token_refresher()
+            self.headers["Authorization"] = f"Bearer {new_token}"
+            logger.debug("retryhttp: token refreshed (async)")
+
+    async def send(self, request: httpx.Request, **kwargs: Any) -> httpx.Response:  # type: ignore[override]
+        cfg = self.retry_config
+        last_response: httpx.Response | None = None
+
+        for attempt in range(cfg.max_attempts):
+            try:
+                response = await super().send(request, **kwargs)
+            except (httpx.ConnectError, httpx.TimeoutException, httpx.NetworkError) as exc:
+                if not cfg.retry_on_network_error or attempt == cfg.max_attempts - 1:
+                    raise
+                delay = backoff_delay(attempt, base=cfg.backoff_base, maximum=cfg.backoff_max, jitter=cfg.jitter)
+                logger.warning(
+                    "retryhttp: network error on attempt %d/%d (%s), retrying in %.2fs",
+                    attempt + 1,
+                    cfg.max_attempts,
+                    exc,
+                    delay,
+                )
+                await asyncio.sleep(delay)
+                continue
+
+            last_response = response
+
+            if cfg.token_refresh_status and response.status_code == cfg.token_refresh_status:
+                if attempt < cfg.max_attempts - 1:
+                    logger.info("retryhttp: 401 received, refreshing token (attempt %d)", attempt + 1)
+                    await self._maybe_refresh_token()
+                    request = self.build_request(
+                        method=request.method,
+                        url=request.url,
+                        content=request.content,
+                        headers=dict(request.headers),
+                    )
+                    continue
+
+            if not cfg.should_retry_status(response.status_code):
+                return response
+
+            if attempt == cfg.max_attempts - 1:
+                if cfg.raise_on_exhaust:
+                    raise RetryExhausted(
+                        f"All {cfg.max_attempts} attempts failed",
+                        attempts=cfg.max_attempts,
+                        last_status=response.status_code,
+                    )
+                return response
+
+            delay = backoff_delay(attempt, base=cfg.backoff_base, maximum=cfg.backoff_max, jitter=cfg.jitter)
+            logger.warning(
+                "retryhttp: HTTP %d on attempt %d/%d, retrying in %.2fs",
+                response.status_code,
+                attempt + 1,
+                cfg.max_attempts,
+                delay,
+            )
+            await asyncio.sleep(delay)
+
+        if cfg.raise_on_exhaust:
+            raise RetryExhausted(
+                f"All {cfg.max_attempts} attempts failed",
+                attempts=cfg.max_attempts,
+                last_status=last_response.status_code if last_response else None,
+            )
+        assert last_response is not None
+        return last_response

retryhttp2-0.1.0/src/retryhttp/requests_client.py

@@ -0,0 +1,143 @@
+"""requests adapter: RetrySession."""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+from typing import Any
+
+import requests
+from requests import PreparedRequest, Response
+from requests.adapters import HTTPAdapter
+
+from retryhttp.backoff import backoff_delay
+from retryhttp.retry import RetryConfig, RetryExhausted
+
+logger = logging.getLogger(__name__)
+
+TokenRefresher = Callable[[], str]
+
+
+class _RetryAdapter(HTTPAdapter):
+    """Internal HTTPAdapter that carries a RetryConfig.
+
+    The actual retry loop lives in RetrySession.send so that the token-refresh
+    hook has access to the session-level headers.
+    """
+
+    def __init__(self, config: RetryConfig, **kwargs: Any) -> None:
+        self.retry_config = config
+        super().__init__(**kwargs)
+
+
+class RetrySession(requests.Session):
+    """A requests.Session that retries failed requests with exponential backoff.
+
+    Args:
+        config: Retry policy. Defaults to RetryConfig() (3 attempts, sane backoff).
+        token_refresher: Optional callable ``() -> str`` that returns a fresh
+            bearer token. Triggered on 401 responses.
+        **kwargs: Not used; present for forward-compatibility.
+
+    Example::
+
+        def refresh() -> str:
+            return fetch_new_token()
+
+        with RetrySession(token_refresher=refresh) as session:
+            resp = session.get("https://api.example.com/data")
+    """
+
+    def __init__(
+        self,
+        *,
+        config: RetryConfig | None = None,
+        token_refresher: TokenRefresher | None = None,
+    ) -> None:
+        super().__init__()
+        self.retry_config = config or RetryConfig()
+        self._token_refresher = token_refresher
+
+        adapter = _RetryAdapter(self.retry_config)
+        self.mount("https://", adapter)
+        self.mount("http://", adapter)
+
+    def _maybe_refresh_token(self) -> None:
+        if self._token_refresher is not None:
+            new_token = self._token_refresher()
+            self.headers["Authorization"] = f"Bearer {new_token}"
+            logger.debug("retryhttp: token refreshed")
+
+    def send(self, request: PreparedRequest, **kwargs: Any) -> Response:  # type: ignore[override]
+        cfg = self.retry_config
+        last_response: Response | None = None
+
+        for attempt in range(cfg.max_attempts):
+            try:
+                response = super().send(request, **kwargs)
+            except (requests.ConnectionError, requests.Timeout) as exc:
+                if not cfg.retry_on_network_error or attempt == cfg.max_attempts - 1:
+                    raise
+                delay = backoff_delay(attempt, base=cfg.backoff_base, maximum=cfg.backoff_max, jitter=cfg.jitter)
+                logger.warning(
+                    "retryhttp: network error on attempt %d/%d (%s), retrying in %.2fs",
+                    attempt + 1,
+                    cfg.max_attempts,
+                    exc,
+                    delay,
+                )
+                time.sleep(delay)
+                continue
+
+            last_response = response
+
+            # Token refresh on 401.
+            if cfg.token_refresh_status and response.status_code == cfg.token_refresh_status:
+                if attempt < cfg.max_attempts - 1:
+                    logger.info("retryhttp: 401 received, refreshing token (attempt %d)", attempt + 1)
+                    self._maybe_refresh_token()
+                    # Re-prepare the request so the updated session headers are baked in.
+                    req = response.request
+                    assert req.url is not None
+                    prepped = self.prepare_request(
+                        requests.Request(
+                            method=req.method or "GET",
+                            url=req.url,
+                            headers=dict(self.headers),
+                            data=req.body,
+                        )
+                    )
+                    request = prepped
+                    continue
+
+            if not cfg.should_retry_status(response.status_code):
+                return response
+
+            if attempt == cfg.max_attempts - 1:
+                if cfg.raise_on_exhaust:
+                    raise RetryExhausted(
+                        f"All {cfg.max_attempts} attempts failed",
+                        attempts=cfg.max_attempts,
+                        last_status=response.status_code,
+                    )
+                return response
+
+            delay = backoff_delay(attempt, base=cfg.backoff_base, maximum=cfg.backoff_max, jitter=cfg.jitter)
+            logger.warning(
+                "retryhttp: HTTP %d on attempt %d/%d, retrying in %.2fs",
+                response.status_code,
+                attempt + 1,
+                cfg.max_attempts,
+                delay,
+            )
+            time.sleep(delay)
+
+        if cfg.raise_on_exhaust:
+            raise RetryExhausted(
+                f"All {cfg.max_attempts} attempts failed",
+                attempts=cfg.max_attempts,
+                last_status=last_response.status_code if last_response else None,
+            )
+        assert last_response is not None
+        return last_response

retryhttp2-0.1.0/src/retryhttp/retry.py

@@ -0,0 +1,82 @@
+"""Core retry configuration and exception types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+# HTTP status codes that are safe to retry by default.
+DEFAULT_RETRY_STATUSES: frozenset[int] = frozenset(
+    {
+        429,  # Too Many Requests
+        500,  # Internal Server Error
+        502,  # Bad Gateway
+        503,  # Service Unavailable
+        504,  # Gateway Timeout
+    }
+)
+
+
+class RetryExhausted(Exception):
+    """Raised when all retry attempts have been spent.
+
+    Attributes:
+        attempts: Number of attempts made before giving up.
+        last_status: HTTP status code of the final response, or None if the
+            last attempt raised a network-level exception.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        attempts: int,
+        last_status: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.attempts = attempts
+        self.last_status = last_status
+
+
+@dataclass
+class RetryConfig:
+    """Declarative retry policy passed to RetryClient / RetrySession.
+
+    Args:
+        max_attempts: Total number of attempts (1 = no retries).
+        retry_statuses: Set of HTTP status codes that trigger a retry.
+        backoff_base: Base for exponential backoff in seconds.
+        backoff_max: Maximum backoff ceiling in seconds.
+        jitter: When True, adds random jitter to each backoff delay.
+        retry_on_network_error: Retry on connection errors, timeouts, etc.
+        token_refresh_status: Status code that triggers a token refresh
+            (default 401). Set to None to disable.
+        raise_on_exhaust: Raise RetryExhausted when all attempts fail.
+            When False, the final bad response is returned instead.
+
+    Example::
+
+        config = RetryConfig(max_attempts=5, backoff_base=0.5)
+        client = RetryClient(config=config, token_refresher=my_refresh_fn)
+    """
+
+    max_attempts: int = 3
+    retry_statuses: frozenset[int] = field(default_factory=lambda: DEFAULT_RETRY_STATUSES)
+    backoff_base: float = 1.0
+    backoff_max: float = 60.0
+    jitter: bool = True
+    retry_on_network_error: bool = True
+    token_refresh_status: int | None = 401
+    raise_on_exhaust: bool = True
+
+    def __post_init__(self) -> None:
+        if self.max_attempts < 1:
+            raise ValueError("max_attempts must be >= 1")
+        if self.backoff_base <= 0:
+            raise ValueError("backoff_base must be positive")
+        if self.backoff_max < self.backoff_base:
+            raise ValueError("backoff_max must be >= backoff_base")
+
+    def should_retry_status(self, status: int) -> bool:
+        """Return True if *status* is in the retry set."""
+        return status in self.retry_statuses

retryhttp2-0.1.0/tests/test_backoff.py

@@ -0,0 +1,27 @@
+"""Tests for the backoff delay calculation."""
+
+import pytest
+
+from retryhttp.backoff import backoff_delay
+
+
+def test_no_jitter_grows_exponentially():
+    delays = [backoff_delay(i, base=1.0, maximum=60.0, jitter=False) for i in range(5)]
+    assert delays == [1.0, 2.0, 4.0, 8.0, 16.0]
+
+
+def test_maximum_caps_delay():
+    delay = backoff_delay(100, base=1.0, maximum=10.0, jitter=False)
+    assert delay == 10.0
+
+
+def test_jitter_within_bounds():
+    for attempt in range(10):
+        d = backoff_delay(attempt, base=1.0, maximum=60.0, jitter=True)
+        cap = min(60.0, 1.0 * (2**attempt))
+        assert 0.0 <= d <= cap
+
+
+def test_base_zero_raises():
+    with pytest.raises(Exception):
+        backoff_delay(0, base=0, maximum=10.0)

retryhttp2-0.1.0/tests/test_httpx_client.py

@@ -0,0 +1,142 @@
+"""Tests for RetryClient and AsyncRetryClient (httpx)."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import httpx
+import pytest
+from pytest_httpx import HTTPXMock
+
+from retryhttp import AsyncRetryClient, RetryClient
+from retryhttp.retry import RetryConfig, RetryExhausted
+
+
+# ---------------------------------------------------------------------------
+# Sync RetryClient
+# ---------------------------------------------------------------------------
+
+
+def test_successful_request(httpx_mock: HTTPXMock):
+    httpx_mock.add_response(status_code=200, json={"ok": True})
+    with RetryClient() as client:
+        resp = client.get("https://example.com/api")
+    assert resp.status_code == 200
+
+
+def test_retries_on_503(httpx_mock: HTTPXMock):
+    httpx_mock.add_response(status_code=503)
+    httpx_mock.add_response(status_code=503)
+    httpx_mock.add_response(status_code=200, json={"ok": True})
+
+    cfg = RetryConfig(max_attempts=3, jitter=False, backoff_base=0.0001)
+    with RetryClient(config=cfg) as client:
+        resp = client.get("https://example.com/api")
+    assert resp.status_code == 200
+
+
+def test_raises_retry_exhausted(httpx_mock: HTTPXMock):
+    httpx_mock.add_response(status_code=503)
+    httpx_mock.add_response(status_code=503)
+    httpx_mock.add_response(status_code=503)
+
+    cfg = RetryConfig(max_attempts=3, jitter=False, backoff_base=0.0001)
+    with pytest.raises(RetryExhausted) as exc_info:
+        with RetryClient(config=cfg) as client:
+            client.get("https://example.com/api")
+
+    assert exc_info.value.attempts == 3
+    assert exc_info.value.last_status == 503
+
+
+def test_no_retry_on_404(httpx_mock: HTTPXMock):
+    httpx_mock.add_response(status_code=404)
+
+    cfg = RetryConfig(max_attempts=3)
+    with RetryClient(config=cfg) as client:
+        resp = client.get("https://example.com/api")
+    assert resp.status_code == 404
+    # Only one request should have been made.
+    assert len(httpx_mock.get_requests()) == 1
+
+
+def test_token_refresh_on_401(httpx_mock: HTTPXMock):
+    httpx_mock.add_response(status_code=401)
+    httpx_mock.add_response(status_code=200, json={"ok": True})
+
+    refresh_calls: list[str] = []
+
+    def refresher() -> str:
+        refresh_calls.append("called")
+        return "new-token-xyz"
+
+    cfg = RetryConfig(max_attempts=3, jitter=False, backoff_base=0.0001)
+    with RetryClient(config=cfg, token_refresher=refresher) as client:
+        resp = client.get("https://example.com/api")
+
+    assert resp.status_code == 200
+    assert len(refresh_calls) == 1
+    assert client.headers["Authorization"] == "Bearer new-token-xyz"
+
+
+def test_raise_on_exhaust_false_returns_response(httpx_mock: HTTPXMock):
+    httpx_mock.add_response(status_code=503)
+    httpx_mock.add_response(status_code=503)
+    httpx_mock.add_response(status_code=503)
+
+    cfg = RetryConfig(max_attempts=3, jitter=False, backoff_base=0.0001, raise_on_exhaust=False)
+    with RetryClient(config=cfg) as client:
+        resp = client.get("https://example.com/api")
+    assert resp.status_code == 503
+
+
+# ---------------------------------------------------------------------------
+# Async AsyncRetryClient
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_async_successful_request(httpx_mock: HTTPXMock):
+    httpx_mock.add_response(status_code=200, json={"ok": True})
+    async with AsyncRetryClient() as client:
+        resp = await client.get("https://example.com/api")
+    assert resp.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_async_retries_on_503(httpx_mock: HTTPXMock):
+    httpx_mock.add_response(status_code=503)
+    httpx_mock.add_response(status_code=200, json={"ok": True})
+
+    cfg = RetryConfig(max_attempts=3, jitter=False, backoff_base=0.0001)
+    async with AsyncRetryClient(config=cfg) as client:
+        resp = await client.get("https://example.com/api")
+    assert resp.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_async_token_refresh_on_401(httpx_mock: HTTPXMock):
+    httpx_mock.add_response(status_code=401)
+    httpx_mock.add_response(status_code=200, json={"ok": True})
+
+    async def async_refresher() -> str:
+        return "async-new-token"
+
+    cfg = RetryConfig(max_attempts=3, jitter=False, backoff_base=0.0001)
+    async with AsyncRetryClient(config=cfg, token_refresher=async_refresher) as client:
+        resp = await client.get("https://example.com/api")
+
+    assert resp.status_code == 200
+    assert client.headers["Authorization"] == "Bearer async-new-token"
+
+
+@pytest.mark.asyncio
+async def test_async_raises_retry_exhausted(httpx_mock: HTTPXMock):
+    httpx_mock.add_response(status_code=503)
+    httpx_mock.add_response(status_code=503)
+    httpx_mock.add_response(status_code=503)
+
+    cfg = RetryConfig(max_attempts=3, jitter=False, backoff_base=0.0001)
+    with pytest.raises(RetryExhausted):
+        async with AsyncRetryClient(config=cfg) as client:
+            await client.get("https://example.com/api")

retryhttp2-0.1.0/tests/test_requests_client.py

@@ -0,0 +1,84 @@
+"""Tests for RetrySession (requests)."""
+
+from __future__ import annotations
+
+import pytest
+import responses as resp_mock
+from responses import RequestsMock
+
+from retryhttp import RetrySession
+from retryhttp.retry import RetryConfig, RetryExhausted
+
+
+@resp_mock.activate
+def test_successful_request():
+    resp_mock.add(resp_mock.GET, "https://example.com/api", status=200, json={"ok": True})
+    with RetrySession() as session:
+        resp = session.get("https://example.com/api")
+    assert resp.status_code == 200
+
+
+@resp_mock.activate
+def test_retries_on_503():
+    resp_mock.add(resp_mock.GET, "https://example.com/api", status=503)
+    resp_mock.add(resp_mock.GET, "https://example.com/api", status=503)
+    resp_mock.add(resp_mock.GET, "https://example.com/api", status=200, json={"ok": True})
+
+    cfg = RetryConfig(max_attempts=3, jitter=False, backoff_base=0.0001)
+    with RetrySession(config=cfg) as session:
+        resp = session.get("https://example.com/api")
+    assert resp.status_code == 200
+
+
+@resp_mock.activate
+def test_raises_retry_exhausted():
+    for _ in range(3):
+        resp_mock.add(resp_mock.GET, "https://example.com/api", status=503)
+
+    cfg = RetryConfig(max_attempts=3, jitter=False, backoff_base=0.0001)
+    with pytest.raises(RetryExhausted) as exc_info:
+        with RetrySession(config=cfg) as session:
+            session.get("https://example.com/api")
+
+    assert exc_info.value.attempts == 3
+    assert exc_info.value.last_status == 503
+
+
+@resp_mock.activate
+def test_no_retry_on_404():
+    resp_mock.add(resp_mock.GET, "https://example.com/api", status=404)
+
+    with RetrySession() as session:
+        resp = session.get("https://example.com/api")
+    assert resp.status_code == 404
+    assert len(resp_mock.calls) == 1
+
+
+@resp_mock.activate
+def test_token_refresh_on_401():
+    resp_mock.add(resp_mock.GET, "https://example.com/api", status=401)
+    resp_mock.add(resp_mock.GET, "https://example.com/api", status=200, json={"ok": True})
+
+    calls: list[str] = []
+
+    def refresher() -> str:
+        calls.append("called")
+        return "fresh-token"
+
+    cfg = RetryConfig(max_attempts=3, jitter=False, backoff_base=0.0001)
+    with RetrySession(config=cfg, token_refresher=refresher) as session:
+        resp = session.get("https://example.com/api")
+
+    assert resp.status_code == 200
+    assert len(calls) == 1
+
+
+@resp_mock.activate
+def test_raise_on_exhaust_false_returns_response():
+    for _ in range(3):
+        resp_mock.add(resp_mock.GET, "https://example.com/api", status=503)
+
+    cfg = RetryConfig(max_attempts=3, jitter=False, backoff_base=0.0001, raise_on_exhaust=False)
+    with RetrySession(config=cfg) as session:
+        resp = session.get("https://example.com/api")
+    assert resp.status_code == 503

retryhttp2-0.1.0/tests/test_retry_config.py

@@ -0,0 +1,40 @@
+"""Tests for RetryConfig validation and behaviour."""
+
+import pytest
+
+from retryhttp.retry import DEFAULT_RETRY_STATUSES, RetryConfig
+
+
+def test_defaults():
+    cfg = RetryConfig()
+    assert cfg.max_attempts == 3
+    assert cfg.jitter is True
+    assert cfg.retry_statuses == DEFAULT_RETRY_STATUSES
+
+
+def test_should_retry_status():
+    cfg = RetryConfig()
+    assert cfg.should_retry_status(503) is True
+    assert cfg.should_retry_status(200) is False
+    assert cfg.should_retry_status(404) is False
+
+
+def test_invalid_max_attempts():
+    with pytest.raises(ValueError, match="max_attempts"):
+        RetryConfig(max_attempts=0)
+
+
+def test_invalid_backoff_base():
+    with pytest.raises(ValueError, match="backoff_base"):
+        RetryConfig(backoff_base=0)
+
+
+def test_backoff_max_lt_base():
+    with pytest.raises(ValueError, match="backoff_max"):
+        RetryConfig(backoff_base=10.0, backoff_max=5.0)
+
+
+def test_custom_retry_statuses():
+    cfg = RetryConfig(retry_statuses=frozenset({503, 429}))
+    assert cfg.should_retry_status(503)
+    assert not cfg.should_retry_status(500)