async-rest-adapter 0.1.0__py3-none-any.whl

async_rest_adapter/__init__.py

@@ -0,0 +1,37 @@
+"""async-rest-adapter — Async REST API adapter base class.
+
+Provides BaseAdapter, the response/error models, and Attribution for building
+async REST API clients with built-in retry, rate-limit handling, and
+open-data attribution injection.
+
+Example::
+
+    from async_rest_adapter import BaseAdapter, APIResponse, APIError, Attribution
+
+    class MyAdapter(BaseAdapter):
+        ATTRIBUTION = Attribution(license="CC-BY-4.0", text="My Source", url="https://example.com")
+
+        async def health_check(self) -> APIResponse:
+            try:
+                await self._make_request("GET", "/health")
+                return self._wrap_response(success=True, data={"status": "ok"})
+            except APIError as e:
+                return self._wrap_response(success=False, error=e.message, error_type=e.error_type)
+
+    async with MyAdapter("my-api", "https://api.example.com") as adapter:
+        result = await adapter.health_check()
+        print(result.metadata["attribution"])
+"""
+
+from async_rest_adapter._base import BaseAdapter
+from async_rest_adapter._models import APIError, APIResponse, Attribution
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BaseAdapter",
+    "APIResponse",
+    "APIError",
+    "Attribution",
+    "__version__",
+]

async_rest_adapter/_base.py

@@ -0,0 +1,186 @@
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional
+
+import httpx
+
+from async_rest_adapter._models import APIError, APIResponse, Attribution
+
+logger = logging.getLogger(__name__)
+
+
+class BaseAdapter(ABC):
+    """
+    Abstract base for async REST API adapters.
+
+    Usage::
+
+        class MyAdapter(BaseAdapter):
+            ATTRIBUTION = Attribution(license="CC-BY-4.0", text="My Source", url="https://example.com")
+
+            async def health_check(self) -> APIResponse:
+                try:
+                    await self._make_request("GET", "/health")
+                    return self._wrap_response(success=True, data={"status": "ok"})
+                except APIError as e:
+                    return self._wrap_response(success=False, error=e.message, error_type=e.error_type)
+
+        async with MyAdapter("my-api", "https://api.example.com") as adapter:
+            result = await adapter.health_check()
+    """
+
+    ATTRIBUTION: Optional[Attribution] = None
+
+    def __init__(
+        self,
+        provider_name: str,
+        base_url: str,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ):
+        self.provider_name = provider_name
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._client: Optional[httpx.AsyncClient] = None
+        self.default_headers: Dict[str, str] = {}
+
+    @property
+    def session(self) -> Optional[httpx.AsyncClient]:
+        """Alias for _client. Allows unit tests to inject mock clients via adapter.session = mock."""
+        return self._client
+
+    @session.setter
+    def session(self, value: Optional[httpx.AsyncClient]) -> None:
+        self._client = value
+
+    async def __aenter__(self) -> "BaseAdapter":
+        self._client = httpx.AsyncClient(
+            timeout=httpx.Timeout(self.timeout),
+            headers=self.default_headers,
+            follow_redirects=True,
+        )
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        if self._client:
+            await self._client.aclose()
+
+    async def _make_request(self, method: str, endpoint: str, **kwargs) -> Dict[str, Any]:
+        """Make an HTTP request with exponential-backoff retry. Returns raw parsed body."""
+        if not self._client:
+            raise APIError("Client not initialized. Use async context manager.")
+
+        url = f"{self.base_url}{endpoint}"
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await self._client.request(method, url, **kwargs)
+
+                if await self._handle_rate_limit(response):
+                    continue
+
+                api_error = self._handle_errors(response)
+                if api_error:
+                    raise api_error
+
+                content_type = response.headers.get("content-type", "")
+                if "application/json" in content_type:
+                    return response.json()
+                elif content_type.startswith("text/"):
+                    return {"text": response.text, "content_type": content_type}
+                else:
+                    return {
+                        "content": response.content,
+                        "content_type": content_type,
+                        "content_length": response.headers.get("content-length"),
+                    }
+
+            except httpx.RequestError as e:
+                if attempt == self.max_retries:
+                    raise APIError(
+                        f"Request failed after {self.max_retries} retries: {e}",
+                        error_type="network_error",
+                    )
+                wait_time = 2**attempt
+                logger.warning(
+                    "%s request failed (attempt %d), retrying in %ds: %s",
+                    self.provider_name, attempt + 1, wait_time, e,
+                )
+                await asyncio.sleep(wait_time)
+
+        raise APIError("Maximum retries exceeded", error_type="max_retries_exceeded")
+
+    def _wrap_response(
+        self,
+        success: bool,
+        data: Any = None,
+        error: Optional[str] = None,
+        error_type: Optional[str] = None,
+        metadata: Optional[Dict] = None,
+    ) -> APIResponse:
+        """Build APIResponse, auto-injecting ATTRIBUTION into metadata on success."""
+        meta = metadata or {}
+        if success and self.ATTRIBUTION is not None:
+            meta["attribution"] = {
+                "license": self.ATTRIBUTION.license,
+                "text": self.ATTRIBUTION.text,
+                "url": self.ATTRIBUTION.url,
+            }
+        return APIResponse(success=success, data=data, error=error, error_type=error_type, metadata=meta)
+
+    async def _handle_rate_limit(self, response: httpx.Response) -> bool:
+        """Sleep and return True on 429, signalling _make_request to retry."""
+        if response.status_code != 429:
+            return False
+        retry_after = response.headers.get("Retry-After", "60")
+        try:
+            wait_time = min(int(retry_after), 300)
+        except ValueError:
+            wait_time = 60
+        logger.warning("%s rate limit hit, waiting %ds", self.provider_name, wait_time)
+        await asyncio.sleep(wait_time)
+        return True
+
+    def _handle_errors(self, response: httpx.Response) -> Optional[APIError]:
+        """Map HTTP 4xx/5xx status codes to typed APIError. Returns None on 2xx/3xx."""
+        if response.status_code < 400:
+            return None
+
+        try:
+            error_data = response.json()
+            message = error_data.get("message", error_data.get("error", f"HTTP {response.status_code}"))
+            details: Dict = error_data
+        except Exception:
+            message = f"HTTP {response.status_code}"
+            details = {}
+
+        status = response.status_code
+        if status == 401:
+            error_type = "authentication_error"
+        elif status == 403:
+            error_type = "authorization_error"
+        elif status == 404:
+            error_type = "not_found_error"
+        elif status == 429:
+            error_type = "rate_limit_error"
+        elif 400 <= status < 500:
+            error_type = "client_error"
+        else:
+            error_type = "server_error"
+
+        return APIError(message=message, status_code=status, error_type=error_type, details=details)
+
+    @abstractmethod
+    async def health_check(self) -> APIResponse:
+        pass
+
+    async def _validate_response(self, response: Dict[str, Any]) -> bool:
+        return isinstance(response, dict)
+
+    def _build_headers(self, additional_headers: Optional[Dict[str, str]] = None) -> Dict[str, str]:
+        headers = self.default_headers.copy()
+        if additional_headers:
+            headers.update(additional_headers)
+        return headers

async_rest_adapter/_models.py

@@ -0,0 +1,37 @@
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+@dataclass(frozen=True)
+class Attribution:
+    """Open-data attribution metadata. Declare as ATTRIBUTION at class level on each adapter."""
+    license: str   # e.g. "CC-BY-4.0"
+    text: str      # e.g. "Kolada / RKA"
+    url: str       # canonical source URL
+
+
+class APIError(Exception):
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        error_type: Optional[str] = None,
+        details: Optional[Dict] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.error_type = error_type
+        self.details = details or {}
+
+
+class APIResponse(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    success: bool
+    data: Optional[Any] = None
+    error: Optional[str] = None
+    error_type: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)

async_rest_adapter-0.1.0.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: async-rest-adapter
+Version: 0.1.0
+Summary: Async REST API adapter base class with retry, rate-limit handling, and attribution injection
+Author-email: Tomas Amlov <tomasamlov@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/tomasamlov/async-rest-adapter
+Project-URL: Repository, https://github.com/tomasamlov/async-rest-adapter
+Keywords: async,rest,api,adapter,httpx,retry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30; extra == "dev"
+
+# async-rest-adapter
+
+A lightweight async REST API adapter base class built on [httpx](https://www.python-httpx.org/).
+
+Provides a reusable `BaseAdapter` ABC that handles:
+- Async HTTP client lifecycle (httpx.AsyncClient via context manager)
+- Exponential-backoff retry on `httpx.RequestError`
+- Rate-limit handling (HTTP 429 → sleep → retry)
+- Typed error taxonomy (12 status-code → `APIError` mappings)
+- Attribution injection into every successful response
+- Structured `APIResponse` / `APIError` models (Pydantic v2)
+
+## Installation
+
+```bash
+pip install async-rest-adapter
+```
+
+## Quick start
+
+```python
+from async_rest_adapter import BaseAdapter, APIResponse, Attribution
+
+class MyAdapter(BaseAdapter):
+    ATTRIBUTION = Attribution(
+        license="CC-BY-4.0",
+        text="My Data Source",
+        url="https://example.com",
+    )
+
+    async def health_check(self) -> APIResponse:
+        try:
+            data = await self._make_request("GET", "/health")
+            return self._wrap_response(True, data)
+        except Exception as e:
+            return self._wrap_response(False, error=str(e), error_type="health_check_failed")
+
+async with MyAdapter("my-api", "https://api.example.com") as adapter:
+    result = await adapter.health_check()
+    print(result.success, result.data)
+```
+
+## API
+
+### `BaseAdapter(provider_name, base_url, timeout=30.0, max_retries=3)`
+
+Subclass and implement `health_check() -> APIResponse`.
+
+**Key methods:**
+- `_make_request(method, endpoint, **kwargs)` — HTTP request with retry, returns parsed body
+- `_wrap_response(success, data, error, error_type, metadata)` — builds `APIResponse`, auto-injects `ATTRIBUTION`
+- `_handle_rate_limit(response)` — sleep on 429, return True to retry
+- `_handle_errors(response)` — map 4xx/5xx to `APIError`
+
+**Test injection:**
+```python
+adapter.session = mock_client  # inject mock httpx client in tests
+```
+
+### `APIResponse`
+
+```python
+class APIResponse(BaseModel):
+    success: bool
+    data: Any | None
+    error: str | None
+    error_type: str | None
+    metadata: dict  # includes "attribution" on every successful response
+```
+
+### `APIError(Exception)`
+
+```python
+raise APIError("Not found", status_code=404, error_type="not_found_error")
+```
+
+### `Attribution`
+
+```python
+Attribution(license="CC-BY-4.0", text="Source Name", url="https://example.com")
+```
+
+## Requirements
+
+- Python 3.11+
+- httpx ≥ 0.27
+- pydantic ≥ 2.0
+
+## License
+
+MIT

async_rest_adapter-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+async_rest_adapter/__init__.py,sha256=SpvZFNsB0jJoLwBuAOJc9wt9Rb6x5xlYAFbFcqJVNaA,1241
+async_rest_adapter/_base.py,sha256=JUKin9SgDG_WeoE08Pl1iDxRlvxmLS6i6-NdwXscnyM,6843
+async_rest_adapter/_models.py,sha256=hH9Vm3XdpW9n7kFX4P1z6AaTiVNek74pOEDrUg2Artk,1050
+async_rest_adapter-0.1.0.dist-info/METADATA,sha256=_oERHseetj0Fp_78GrhImmMpLR64e4oyR-6RUgucMBU,3749
+async_rest_adapter-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+async_rest_adapter-0.1.0.dist-info/top_level.txt,sha256=4lQKkLEhEZ3IggbqJuRIi33FjnV5XkZzakOSPxjP2b0,19
+async_rest_adapter-0.1.0.dist-info/RECORD,,

async_rest_adapter-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

async_rest_adapter-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+async_rest_adapter