swarmauri_transport_retry 0.1.0.dev1__tar.gz

swarmauri_transport_retry-0.1.0.dev1/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 Jacob Stewart
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

swarmauri_transport_retry-0.1.0.dev1/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: swarmauri_transport_retry
+Version: 0.1.0.dev1
+Summary: Policy-driven synchronous, asynchronous, and streaming HTTP retries for Swarmauri clients.
+License: Copyright 2026 Jacob Stewart
+         
+         Licensed under the Apache License, Version 2.0 (the "License");
+         you may not use this file except in compliance with the License.
+         You may obtain a copy of the License at
+         
+             http://www.apache.org/licenses/LICENSE-2.0
+         
+         Unless required by applicable law or agreed to in writing, software
+         distributed under the License is distributed on an "AS IS" BASIS,
+         WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+         See the License for the specific language governing permissions and
+         limitations under the License.
+License-File: LICENSE
+Keywords: swarmauri,http,retry,backoff,transport,async
+Author: Jacob Stewart
+Author-email: jacob@swarmauri.com
+Requires-Python: >=3.10,<3.13
+Classifier: Development Status :: 1 - Planning
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: swarmauri_core (>=0.11.0.dev5)
+Description-Content-Type: text/markdown
+
+![Swarmauri Logo](https://github.com/swarmauri/swarmauri-sdk/blob/3d4d1cfa949399d7019ae9d8f296afba773dfb7f/assets/swarmauri.brand.theme.svg)
+
+[![PyPI version](https://img.shields.io/pypi/v/swarmauri_transport_retry.svg)](https://pypi.org/project/swarmauri_transport_retry/) [![Python](https://img.shields.io/pypi/pyversions/swarmauri_transport_retry.svg)](https://pypi.org/project/swarmauri_transport_retry/) [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE) [![Downloads](https://static.pepy.tech/badge/swarmauri_transport_retry)](https://pepy.tech/project/swarmauri_transport_retry) [![Hits](https://hits.sh/github.com/swarmauri/swarmauri-sdk.svg?path=pkgs%2Fstandards%2Fswarmauri_transport_retry)](https://hits.sh/github.com/swarmauri/swarmauri-sdk/)
+
+# swarmauri_transport_retry
+
+Policy-driven retries for any client implementing Swarmauri's `IHttpClient` contract.
+
+## Features
+
+- Bounded exponential backoff with optional jitter.
+- `Retry-After` support for seconds and HTTP dates.
+- Separate policy decisions from sync, async, and streaming execution.
+- Protect non-idempotent methods from replay by default.
+- Wrap any Swarmauri HTTP client without depending on its HTTP library.
+
+## Installation
+
+```bash
+uv add swarmauri_transport_retry
+```
+
+```bash
+pip install swarmauri_transport_retry
+```
+
+## Usage
+
+```python
+from swarmauri_transport_httpx import HttpxClient
+from swarmauri_transport_retry import (
+    ExponentialBackoffRetryPolicy,
+    RetryingHttpClient,
+)
+
+client = RetryingHttpClient(
+    client=HttpxClient(base_url="https://api.example.com"),
+    policy=ExponentialBackoffRetryPolicy(max_attempts=3),
+)
+response = client.request("GET", "/models")
+response.raise_for_status()
+```
+
+The retry policy controls replay safety and delay. The wrapped transport remains responsible for moving HTTP requests and responses.
+

swarmauri_transport_retry-0.1.0.dev1/README.md

@@ -0,0 +1,44 @@
+![Swarmauri Logo](https://github.com/swarmauri/swarmauri-sdk/blob/3d4d1cfa949399d7019ae9d8f296afba773dfb7f/assets/swarmauri.brand.theme.svg)
+
+[![PyPI version](https://img.shields.io/pypi/v/swarmauri_transport_retry.svg)](https://pypi.org/project/swarmauri_transport_retry/) [![Python](https://img.shields.io/pypi/pyversions/swarmauri_transport_retry.svg)](https://pypi.org/project/swarmauri_transport_retry/) [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE) [![Downloads](https://static.pepy.tech/badge/swarmauri_transport_retry)](https://pepy.tech/project/swarmauri_transport_retry) [![Hits](https://hits.sh/github.com/swarmauri/swarmauri-sdk.svg?path=pkgs%2Fstandards%2Fswarmauri_transport_retry)](https://hits.sh/github.com/swarmauri/swarmauri-sdk/)
+
+# swarmauri_transport_retry
+
+Policy-driven retries for any client implementing Swarmauri's `IHttpClient` contract.
+
+## Features
+
+- Bounded exponential backoff with optional jitter.
+- `Retry-After` support for seconds and HTTP dates.
+- Separate policy decisions from sync, async, and streaming execution.
+- Protect non-idempotent methods from replay by default.
+- Wrap any Swarmauri HTTP client without depending on its HTTP library.
+
+## Installation
+
+```bash
+uv add swarmauri_transport_retry
+```
+
+```bash
+pip install swarmauri_transport_retry
+```
+
+## Usage
+
+```python
+from swarmauri_transport_httpx import HttpxClient
+from swarmauri_transport_retry import (
+    ExponentialBackoffRetryPolicy,
+    RetryingHttpClient,
+)
+
+client = RetryingHttpClient(
+    client=HttpxClient(base_url="https://api.example.com"),
+    policy=ExponentialBackoffRetryPolicy(max_attempts=3),
+)
+response = client.request("GET", "/models")
+response.raise_for_status()
+```
+
+The retry policy controls replay safety and delay. The wrapped transport remains responsible for moving HTTP requests and responses.

swarmauri_transport_retry-0.1.0.dev1/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "swarmauri_transport_retry"
+version = "0.1.0.dev1"
+description = "Policy-driven synchronous, asynchronous, and streaming HTTP retries for Swarmauri clients."
+readme = "README.md"
+requires-python = ">=3.10,<3.13"
+authors = [{ name = "Jacob Stewart", email = "jacob@swarmauri.com" }]
+license = { file = "LICENSE" }
+dependencies = ["swarmauri_core>=0.11.0.dev5"]
+classifiers = [
+  "Development Status :: 1 - Planning",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+keywords = ["swarmauri", "http", "retry", "backoff", "transport", "async"]
+
+[tool.uv.sources]
+swarmauri_core = { workspace = true }
+
+[project.entry-points."swarmauri.transports"]
+RetryingHttpClient = "swarmauri_transport_retry:RetryingHttpClient"
+
+[build-system]
+requires = ["poetry-core>=1.8.0"]
+build-backend = "poetry.core.masonry.api"
+
+[dependency-groups]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.24", "ruff>=0.9.9"]
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+
+[tool.ruff.lint]
+ignore = ["N999"]

swarmauri_transport_retry-0.1.0.dev1/swarmauri_transport_retry/ExponentialBackoffRetryPolicy.py

@@ -0,0 +1,113 @@
+"""Concrete exponential-backoff policy for HTTP operations."""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Collection
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Literal
+
+from swarmauri_core.transports.i_http_response import IHttpResponse
+from swarmauri_core.transports.i_http_retry_policy import IHttpRetryPolicy
+
+
+class ExponentialBackoffRetryPolicy(IHttpRetryPolicy):
+    """Retry safe HTTP operations with bounded exponential backoff."""
+
+    type: Literal["ExponentialBackoffRetryPolicy"] = (
+        "ExponentialBackoffRetryPolicy"
+    )
+
+    def __init__(
+        self,
+        *,
+        max_attempts: int = 3,
+        retryable_status_codes: Collection[int] = (429, 500, 502, 503, 504),
+        retryable_methods: Collection[str] = (
+            "GET",
+            "HEAD",
+            "OPTIONS",
+            "PUT",
+            "DELETE",
+        ),
+        base_delay: float = 1.0,
+        maximum_delay: float = 30.0,
+        respect_retry_after: bool = True,
+        retry_request_errors: bool = True,
+        jitter_ratio: float = 0.0,
+    ) -> None:
+        if max_attempts < 1:
+            raise ValueError("max_attempts must be at least 1")
+        if base_delay < 0 or maximum_delay < 0:
+            raise ValueError("retry delays cannot be negative")
+        if not 0 <= jitter_ratio <= 1:
+            raise ValueError("jitter_ratio must be between 0 and 1")
+        self.max_attempts = max_attempts
+        self.retryable_status_codes = frozenset(retryable_status_codes)
+        self.retryable_methods = frozenset(
+            method.upper() for method in retryable_methods
+        )
+        self.base_delay = base_delay
+        self.maximum_delay = maximum_delay
+        self.respect_retry_after = respect_retry_after
+        self.retry_request_errors = retry_request_errors
+        self.jitter_ratio = jitter_ratio
+
+    def should_retry(
+        self,
+        *,
+        method: str,
+        attempt: int,
+        response: IHttpResponse | None = None,
+        error: Exception | None = None,
+    ) -> bool:
+        if attempt >= self.max_attempts:
+            return False
+        if method.upper() not in self.retryable_methods:
+            return False
+        if error is not None:
+            return self.retry_request_errors
+        return (
+            response is not None
+            and response.status_code in self.retryable_status_codes
+        )
+
+    def delay_seconds(
+        self,
+        *,
+        attempt: int,
+        response: IHttpResponse | None = None,
+    ) -> float:
+        retry_after = self._retry_after_seconds(response)
+        if retry_after is not None:
+            delay = retry_after
+        else:
+            delay = self.base_delay * (2 ** max(attempt - 1, 0))
+        delay = min(delay, self.maximum_delay)
+        if self.jitter_ratio:
+            spread = delay * self.jitter_ratio
+            delay = random.uniform(max(0.0, delay - spread), delay + spread)
+        return max(0.0, min(delay, self.maximum_delay))
+
+    def _retry_after_seconds(
+        self, response: IHttpResponse | None
+    ) -> float | None:
+        if not self.respect_retry_after or response is None:
+            return None
+        value = response.headers.get("Retry-After")
+        if not value:
+            return None
+        try:
+            return max(float(value), 0.0)
+        except ValueError:
+            try:
+                retry_at = parsedate_to_datetime(value)
+            except (TypeError, ValueError):
+                return None
+            if retry_at.tzinfo is None:
+                retry_at = retry_at.replace(tzinfo=timezone.utc)
+            return max(
+                (retry_at - datetime.now(timezone.utc)).total_seconds(),
+                0.0,
+            )

swarmauri_transport_retry-0.1.0.dev1/swarmauri_transport_retry/RetryingHttpClient.py

@@ -0,0 +1,208 @@
+"""HTTP client decorator that executes concrete retry policies."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import AsyncIterator, Iterator, Mapping
+from contextlib import asynccontextmanager, contextmanager
+from typing import Any, Callable
+
+from swarmauri_core.transports.http_errors import HttpRequestError
+from swarmauri_core.transports.i_http_client import IHttpClient
+from swarmauri_core.transports.i_http_response import IHttpResponse
+from swarmauri_core.transports.i_http_retry_policy import IHttpRetryPolicy
+from swarmauri_core.transports.i_http_stream_response import (
+    IAsyncHttpStreamResponse,
+    IHttpStreamResponse,
+)
+from swarmauri_core.transports.i_managed_http_client import IManagedHttpClient
+
+
+class RetryingHttpClient(IManagedHttpClient):
+    """Decorate any Swarmauri HTTP client with an explicit retry policy."""
+
+    def __init__(
+        self,
+        *,
+        client: IHttpClient,
+        policy: IHttpRetryPolicy,
+        sleep: Callable[[float], None] = time.sleep,
+        async_sleep: Callable[[float], Any] = asyncio.sleep,
+        own_client: bool = False,
+    ) -> None:
+        self.client = client
+        self.policy = policy
+        self._sleep = sleep
+        self._async_sleep = async_sleep
+        self.own_client = own_client
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        body: bytes = b"",
+        **kwargs: Any,
+    ) -> IHttpResponse:
+        attempt = 1
+        while True:
+            try:
+                response = self.client.request(
+                    method,
+                    path,
+                    headers=headers,
+                    body=body,
+                    **kwargs,
+                )
+            except HttpRequestError as error:
+                if not self.policy.should_retry(
+                    method=method, attempt=attempt, error=error
+                ):
+                    raise
+                self._sleep(self.policy.delay_seconds(attempt=attempt))
+            else:
+                if not self.policy.should_retry(
+                    method=method, attempt=attempt, response=response
+                ):
+                    return response
+                self._sleep(
+                    self.policy.delay_seconds(
+                        attempt=attempt, response=response
+                    )
+                )
+            attempt += 1
+
+    async def arequest(
+        self,
+        method: str,
+        path: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        body: bytes = b"",
+        **kwargs: Any,
+    ) -> IHttpResponse:
+        attempt = 1
+        while True:
+            try:
+                response = await self.client.arequest(
+                    method,
+                    path,
+                    headers=headers,
+                    body=body,
+                    **kwargs,
+                )
+            except HttpRequestError as error:
+                if not self.policy.should_retry(
+                    method=method, attempt=attempt, error=error
+                ):
+                    raise
+                await self._async_sleep(
+                    self.policy.delay_seconds(attempt=attempt)
+                )
+            else:
+                if not self.policy.should_retry(
+                    method=method, attempt=attempt, response=response
+                ):
+                    return response
+                await self._async_sleep(
+                    self.policy.delay_seconds(
+                        attempt=attempt, response=response
+                    )
+                )
+            attempt += 1
+
+    @contextmanager
+    def stream(
+        self,
+        method: str,
+        path: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        body: bytes = b"",
+        **kwargs: Any,
+    ) -> Iterator[IHttpStreamResponse]:
+        attempt = 1
+        while True:
+            try:
+                with self.client.stream(
+                    method,
+                    path,
+                    headers=headers,
+                    body=body,
+                    **kwargs,
+                ) as response:
+                    if not self.policy.should_retry(
+                        method=method, attempt=attempt, response=response
+                    ):
+                        yield response
+                        return
+                    delay = self.policy.delay_seconds(
+                        attempt=attempt, response=response
+                    )
+            except HttpRequestError as error:
+                if not self.policy.should_retry(
+                    method=method, attempt=attempt, error=error
+                ):
+                    raise
+                delay = self.policy.delay_seconds(attempt=attempt)
+            self._sleep(delay)
+            attempt += 1
+
+    @asynccontextmanager
+    async def astream(
+        self,
+        method: str,
+        path: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        body: bytes = b"",
+        **kwargs: Any,
+    ) -> AsyncIterator[IAsyncHttpStreamResponse]:
+        attempt = 1
+        while True:
+            try:
+                async with self.client.astream(
+                    method,
+                    path,
+                    headers=headers,
+                    body=body,
+                    **kwargs,
+                ) as response:
+                    if not self.policy.should_retry(
+                        method=method, attempt=attempt, response=response
+                    ):
+                        yield response
+                        return
+                    delay = self.policy.delay_seconds(
+                        attempt=attempt, response=response
+                    )
+            except HttpRequestError as error:
+                if not self.policy.should_retry(
+                    method=method, attempt=attempt, error=error
+                ):
+                    raise
+                delay = self.policy.delay_seconds(attempt=attempt)
+            await self._async_sleep(delay)
+            attempt += 1
+
+    def close(self) -> None:
+        if self.own_client and isinstance(self.client, IManagedHttpClient):
+            self.client.close()
+
+    async def aclose(self) -> None:
+        if self.own_client and isinstance(self.client, IManagedHttpClient):
+            await self.client.aclose()
+
+    def __enter__(self) -> "RetryingHttpClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    async def __aenter__(self) -> "RetryingHttpClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()

swarmauri_transport_retry-0.1.0.dev1/swarmauri_transport_retry/__init__.py

@@ -0,0 +1,4 @@
+from .ExponentialBackoffRetryPolicy import ExponentialBackoffRetryPolicy
+from .RetryingHttpClient import RetryingHttpClient
+
+__all__ = ["ExponentialBackoffRetryPolicy", "RetryingHttpClient"]