async-rest-adapter 0.1.0__tar.gz

async_rest_adapter-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,91 @@
+# 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/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "async-rest-adapter"
+version = "0.1.0"
+description = "Async REST API adapter base class with retry, rate-limit handling, and attribution injection"
+requires-python = ">=3.11"
+license = "MIT"
+readme = "README.md"
+authors = [{ name = "Tomas Amlov", email = "tomasamlov@gmail.com" }]
+keywords = ["async", "rest", "api", "adapter", "httpx", "retry"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Framework :: AsyncIO",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27,<1.0",
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/tomasamlov/async-rest-adapter"
+Repository = "https://github.com/tomasamlov/async-rest-adapter"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-httpx>=0.30",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["async_rest_adapter"]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+"tests/**" = ["F401", "E402"]

async_rest_adapter-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

async_rest_adapter-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/src/async_rest_adapter.egg-info/PKG-INFO

@@ -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/src/async_rest_adapter.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/async_rest_adapter/__init__.py
+src/async_rest_adapter/_base.py
+src/async_rest_adapter/_models.py
+src/async_rest_adapter.egg-info/PKG-INFO
+src/async_rest_adapter.egg-info/SOURCES.txt
+src/async_rest_adapter.egg-info/dependency_links.txt
+src/async_rest_adapter.egg-info/requires.txt
+src/async_rest_adapter.egg-info/top_level.txt
+tests/test_base_adapter.py

async_rest_adapter-0.1.0/src/async_rest_adapter.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

async_rest_adapter-0.1.0/src/async_rest_adapter.egg-info/requires.txt

@@ -0,0 +1,7 @@
+httpx<1.0,>=0.27
+pydantic>=2.0
+
+[dev]
+pytest>=8.0
+pytest-asyncio>=0.23
+pytest-httpx>=0.30

async_rest_adapter-0.1.0/src/async_rest_adapter.egg-info/top_level.txt

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

async_rest_adapter-0.1.0/tests/test_base_adapter.py

@@ -0,0 +1,206 @@
+"""Tests for async-rest-adapter core: models, _wrap_response, _handle_errors, _handle_rate_limit."""
+
+import pytest
+import httpx
+from pytest_httpx import HTTPXMock
+
+from async_rest_adapter import APIError, APIResponse, Attribution, BaseAdapter
+
+
+# ---------------------------------------------------------------------------
+# Minimal concrete adapter for testing
+# ---------------------------------------------------------------------------
+
+class _TestAdapter(BaseAdapter):
+    ATTRIBUTION = Attribution(license="MIT", text="Test Source", url="https://test.example.com")
+
+    async def health_check(self) -> APIResponse:
+        try:
+            data = await self._make_request("GET", "/health")
+            return self._wrap_response(success=True, data=data)
+        except APIError as e:
+            return self._wrap_response(success=False, error=e.message, error_type=e.error_type)
+
+
+class _NoAttributionAdapter(BaseAdapter):
+    async def health_check(self) -> APIResponse:
+        return self._wrap_response(success=True, data={})
+
+
+# ---------------------------------------------------------------------------
+# Model tests
+# ---------------------------------------------------------------------------
+
+def test_attribution_is_frozen():
+    attr = Attribution(license="CC-BY-4.0", text="Source", url="https://example.com")
+    with pytest.raises(Exception):
+        attr.license = "other"  # type: ignore[misc]
+
+
+def test_api_error_stores_fields():
+    err = APIError("bad request", status_code=400, error_type="client_error", details={"x": 1})
+    assert err.message == "bad request"
+    assert err.status_code == 400
+    assert err.error_type == "client_error"
+    assert err.details == {"x": 1}
+    assert str(err) == "bad request"
+
+
+def test_api_response_defaults():
+    r = APIResponse(success=True)
+    assert r.data is None
+    assert r.error is None
+    assert r.metadata == {}
+
+
+# ---------------------------------------------------------------------------
+# _wrap_response
+# ---------------------------------------------------------------------------
+
+def test_wrap_response_injects_attribution():
+    adapter = _TestAdapter("test", "https://api.example.com")
+    result = adapter._wrap_response(success=True, data={"x": 1})
+    assert result.success is True
+    assert result.metadata["attribution"]["license"] == "MIT"
+    assert result.metadata["attribution"]["url"] == "https://test.example.com"
+
+
+def test_wrap_response_no_attribution_on_failure():
+    adapter = _TestAdapter("test", "https://api.example.com")
+    result = adapter._wrap_response(success=False, error="oops", error_type="server_error")
+    assert result.success is False
+    assert "attribution" not in result.metadata
+
+
+def test_wrap_response_no_attribution_when_not_declared():
+    adapter = _NoAttributionAdapter("test", "https://api.example.com")
+    result = adapter._wrap_response(success=True, data={})
+    assert "attribution" not in result.metadata
+
+
+def test_wrap_response_preserves_existing_metadata():
+    adapter = _TestAdapter("test", "https://api.example.com")
+    result = adapter._wrap_response(success=True, data={}, metadata={"page": 1})
+    assert result.metadata["page"] == 1
+    assert "attribution" in result.metadata
+
+
+# ---------------------------------------------------------------------------
+# _handle_errors
+# ---------------------------------------------------------------------------
+
+@pytest.mark.parametrize("status,expected_type", [
+    (401, "authentication_error"),
+    (403, "authorization_error"),
+    (404, "not_found_error"),
+    (429, "rate_limit_error"),
+    (422, "client_error"),
+    (500, "server_error"),
+    (503, "server_error"),
+])
+def test_handle_errors_maps_status_codes(status, expected_type):
+    adapter = _TestAdapter("test", "https://api.example.com")
+    response = httpx.Response(status_code=status, json={"error": "something went wrong"})
+    error = adapter._handle_errors(response)
+    assert error is not None
+    assert error.status_code == status
+    assert error.error_type == expected_type
+
+
+def test_handle_errors_returns_none_on_success():
+    adapter = _TestAdapter("test", "https://api.example.com")
+    response = httpx.Response(status_code=200, json={"data": []})
+    assert adapter._handle_errors(response) is None
+
+
+def test_handle_errors_extracts_message_from_json():
+    adapter = _TestAdapter("test", "https://api.example.com")
+    response = httpx.Response(status_code=400, json={"message": "Invalid parameter"})
+    error = adapter._handle_errors(response)
+    assert error is not None
+    assert error.message == "Invalid parameter"
+
+
+def test_handle_errors_fallback_message_on_non_json():
+    adapter = _TestAdapter("test", "https://api.example.com")
+    response = httpx.Response(status_code=500, text="Internal Server Error")
+    error = adapter._handle_errors(response)
+    assert error is not None
+    assert "500" in error.message
+
+
+# ---------------------------------------------------------------------------
+# _handle_rate_limit
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_handle_rate_limit_returns_true_on_429(monkeypatch):
+    adapter = _TestAdapter("test", "https://api.example.com")
+    slept = []
+    monkeypatch.setattr("asyncio.sleep", lambda t: slept.append(t) or _noop())
+    response = httpx.Response(status_code=429, headers={"Retry-After": "5"})
+    result = await adapter._handle_rate_limit(response)
+    assert result is True
+    assert slept == [5]
+
+
+@pytest.mark.asyncio
+async def test_handle_rate_limit_returns_false_on_200():
+    adapter = _TestAdapter("test", "https://api.example.com")
+    response = httpx.Response(status_code=200, json={})
+    result = await adapter._handle_rate_limit(response)
+    assert result is False
+
+
+@pytest.mark.asyncio
+async def test_handle_rate_limit_caps_wait_at_300(monkeypatch):
+    adapter = _TestAdapter("test", "https://api.example.com")
+    slept = []
+    monkeypatch.setattr("asyncio.sleep", lambda t: slept.append(t) or _noop())
+    response = httpx.Response(status_code=429, headers={"Retry-After": "9999"})
+    await adapter._handle_rate_limit(response)
+    assert slept[0] == 300
+
+
+# ---------------------------------------------------------------------------
+# HTTP integration via pytest-httpx
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_health_check_success(httpx_mock: HTTPXMock):
+    httpx_mock.add_response(url="https://api.example.com/health", json={"status": "ok"})
+    async with _TestAdapter("test", "https://api.example.com") as adapter:
+        result = await adapter.health_check()
+    assert result.success is True
+    assert result.data == {"status": "ok"}
+    assert result.metadata["attribution"]["license"] == "MIT"
+
+
+@pytest.mark.asyncio
+async def test_health_check_404(httpx_mock: HTTPXMock):
+    httpx_mock.add_response(url="https://api.example.com/health", status_code=404, json={"error": "not found"})
+    async with _TestAdapter("test", "https://api.example.com") as adapter:
+        result = await adapter.health_check()
+    assert result.success is False
+    assert result.error_type == "not_found_error"
+
+
+@pytest.mark.asyncio
+async def test_make_request_requires_context_manager():
+    adapter = _TestAdapter("test", "https://api.example.com")
+    with pytest.raises(APIError, match="context manager"):
+        await adapter._make_request("GET", "/health")
+
+
+@pytest.mark.asyncio
+async def test_base_adapter_is_abstract():
+    with pytest.raises(TypeError):
+        BaseAdapter("test", "https://api.example.com")  # type: ignore[abstract]
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+async def _noop():
+    pass