ausdata-sdk 0.2.0__py3-none-any.whl

ausdata/__init__.py

@@ -0,0 +1,76 @@
+"""Python SDK for the Australian public data API at https://ausdata.io.
+
+Quick start::
+
+    from ausdata import Client
+
+    client = Client(api_key="ak_xxx")     # or set AUSDATA_API_KEY
+    result = client.real_wages(start="2019-Q1", end="2024-Q4")
+    df = result.to_dataframe()
+
+Async equivalent::
+
+    import asyncio
+    from ausdata import AsyncClient
+
+    async def main():
+        async with AsyncClient(api_key="ak_xxx") as client:
+            return await client.real_wages(start="2019-Q1")
+
+    asyncio.run(main())
+"""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .async_client import AsyncClient
+from .client import Client
+from .exceptions import (
+    AusdataError,
+    AusdataServerError,
+    AuthenticationError,
+    PermissionError,
+    RateLimitError,
+    UpstreamError,
+    ValidationError,
+)
+from .models import (
+    AccountResponse,
+    ApiResponse,
+    DatasetSummary,
+    EconomicDashboard,
+    HealthResponse,
+    Links,
+    Meta,
+    RealWageRow,
+    SearchResponse,
+    SourceCitation,
+    WhoamiResponse,
+)
+
+__all__ = [
+    "__version__",
+    # clients
+    "AsyncClient",
+    "Client",
+    # exceptions
+    "AusdataError",
+    "AusdataServerError",
+    "AuthenticationError",
+    "PermissionError",
+    "RateLimitError",
+    "UpstreamError",
+    "ValidationError",
+    # models
+    "AccountResponse",
+    "ApiResponse",
+    "DatasetSummary",
+    "EconomicDashboard",
+    "HealthResponse",
+    "Links",
+    "Meta",
+    "RealWageRow",
+    "SearchResponse",
+    "SourceCitation",
+    "WhoamiResponse",
+]

ausdata/_internal/__init__.py

@@ -0,0 +1,5 @@
+"""Internal helpers — not part of the public API.
+
+Symbols inside ``ausdata._internal`` may change between minor versions.
+Public callers should depend on the surfaces exposed in ``ausdata.__init__``.
+"""

ausdata/_internal/http.py

@@ -0,0 +1,143 @@
+"""Shared HTTP plumbing for the sync and async clients.
+
+Responsibilities kept here:
+- API-key resolution (constructor arg → env var → informative error)
+- Default headers (Authorization, User-Agent)
+- Mapping HTTP status codes to typed :class:`AusdataError` subclasses
+
+The actual request execution + retry loop lives in the sync/async clients
+because the two transport styles can't share that wrapper cleanly.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from .._version import __version__
+from ..exceptions import (
+    AusdataError,
+    AusdataServerError,
+    AuthenticationError,
+    PermissionError,
+    RateLimitError,
+    UpstreamError,
+    ValidationError,
+)
+
+DEFAULT_BASE_URL = "https://api.ausdata.io"
+DEFAULT_TIMEOUT = 30.0
+API_KEY_ENV_VAR = "AUSDATA_API_KEY"
+BASE_URL_ENV_VAR = "AUSDATA_BASE_URL"
+
+
+def resolve_api_key(api_key: str | None) -> str:
+    """Return ``api_key``, falling back to the ``AUSDATA_API_KEY`` env var.
+
+    Raises ``AuthenticationError`` with a directly actionable message when
+    neither source is set — failing here is much better than a cryptic 401
+    from the API on the first call.
+    """
+    if api_key:
+        return api_key
+    env_value = os.environ.get(API_KEY_ENV_VAR)
+    if env_value:
+        return env_value
+    raise AuthenticationError(
+        "No API key provided.",
+        hint=(
+            f"Pass api_key='ak_...' to Client(), or set the {API_KEY_ENV_VAR} "
+            "environment variable. Get a free key at https://ausdata.io."
+        ),
+    )
+
+
+def build_default_headers(api_key: str) -> dict[str, str]:
+    return {
+        "Authorization": f"Bearer {api_key}",
+        "User-Agent": f"ausdata-python/{__version__}",
+        "Accept": "application/json",
+    }
+
+
+def normalise_base_url(base_url: str | None) -> str:
+    """Resolve base URL: explicit arg → ``AUSDATA_BASE_URL`` env → default.
+
+    Trailing slash is stripped so endpoint paths can always start with ``/v1/...``.
+    """
+    resolved = base_url or os.environ.get(BASE_URL_ENV_VAR) or DEFAULT_BASE_URL
+    return resolved.rstrip("/")
+
+
+def parse_error_body(response: httpx.Response) -> tuple[str, str | None, dict[str, Any] | None]:
+    """Best-effort extraction of ``(message, hint, raw_body)`` from a non-2xx body.
+
+    The API's :class:`ErrorDetail` shape is ``{"error", "message", "hint"}``;
+    FastAPI's default validation failures use ``{"detail"}``. We accept either.
+    """
+    try:
+        body = response.json()
+    except (ValueError, httpx.DecodingError):
+        return response.text or response.reason_phrase or "API error", None, None
+
+    if not isinstance(body, dict):
+        return str(body), None, None
+
+    hint = body.get("hint")
+    if "message" in body:
+        return str(body["message"]), hint, body
+    if "detail" in body:
+        detail = body["detail"]
+        if isinstance(detail, str):
+            return detail, hint, body
+        return str(detail), hint, body
+    if "error" in body:
+        return str(body["error"]), hint, body
+    return response.reason_phrase or "API error", hint, body
+
+
+def raise_for_response(response: httpx.Response) -> None:
+    """Map an HTTP status code to the right :class:`AusdataError` subclass.
+
+    Called by the sync/async clients after exhausting the retry policy.
+    """
+    if response.is_success:
+        return
+
+    status = response.status_code
+    message, hint, raw = parse_error_body(response)
+
+    if status == 400:
+        raise ValidationError(message, status_code=status, hint=hint, response_body=raw)
+    if status == 401:
+        raise AuthenticationError(message, status_code=status, hint=hint, response_body=raw)
+    if status == 402:
+        # Treat 402 ("payment required" / tier-blocked) as a permission error.
+        raise PermissionError(message, status_code=status, hint=hint, response_body=raw)
+    if status == 403:
+        raise PermissionError(message, status_code=status, hint=hint, response_body=raw)
+    if status == 404:
+        raise ValidationError(message, status_code=status, hint=hint, response_body=raw)
+    if status == 429:
+        retry_after_header = response.headers.get("Retry-After")
+        retry_after: float | None = None
+        if retry_after_header:
+            try:
+                retry_after = float(retry_after_header)
+            except ValueError:
+                retry_after = None
+        raise RateLimitError(
+            message,
+            status_code=status,
+            hint=hint,
+            response_body=raw,
+            retry_after=retry_after,
+        )
+    if status in (502, 503, 504):
+        raise UpstreamError(message, status_code=status, hint=hint, response_body=raw)
+    if 500 <= status < 600:
+        raise AusdataServerError(message, status_code=status, hint=hint, response_body=raw)
+
+    raise AusdataError(message, status_code=status, hint=hint, response_body=raw)

ausdata/_internal/retry.py

@@ -0,0 +1,63 @@
+"""Retry policy shared by the sync and async clients.
+
+The policy:
+- Auto-retry on 5xx with exponential backoff (default 1s, 2s, 4s, max 3 attempts)
+- Retry on 429 if a ``Retry-After`` header is present (capped at ``max_retry_after_seconds``)
+- Never retry on other 4xx
+- Caller-side ``ConnectError`` / ``ReadTimeout`` failures retry like 5xx
+
+Sleeping is delegated to a caller-provided callable so the async client can
+``await asyncio.sleep`` while the sync client uses ``time.sleep``. This keeps
+the policy decision in one place.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """Configuration for the SDK's automatic retry behaviour.
+
+    Defaults are conservative — 3 attempts (so 2 retries after the first
+    failure), 2x exponential backoff starting at 1 second. ``Retry-After``
+    headers on 429 responses are always respected up to
+    ``max_retry_after_seconds`` (default 60s).
+    """
+
+    max_retries: int = 3
+    backoff_factor: float = 2.0
+    initial_backoff: float = 1.0
+    max_retry_after_seconds: float = 60.0
+
+    def should_retry_status(self, status_code: int) -> bool:
+        if status_code == 429:
+            return True
+        return 500 <= status_code < 600
+
+    def should_retry_exception(self, exc: BaseException) -> bool:
+        # httpx network-layer failures get the same retry treatment as 5xx.
+        return isinstance(
+            exc,
+            (httpx.ConnectError, httpx.ReadTimeout, httpx.WriteTimeout, httpx.RemoteProtocolError),
+        )
+
+    def backoff_seconds(self, attempt: int) -> float:
+        """Backoff for the ``attempt``-th retry (1-indexed)."""
+        return self.initial_backoff * (self.backoff_factor ** (attempt - 1))
+
+    def retry_after_seconds(self, response: httpx.Response) -> float | None:
+        """Parse the ``Retry-After`` header. Returns None if absent or bogus."""
+        header = response.headers.get("Retry-After") or response.headers.get(
+            "retry-after"
+        )
+        if not header:
+            return None
+        try:
+            value = float(header)
+        except ValueError:
+            return None
+        return min(value, self.max_retry_after_seconds)

ausdata/_version.py

@@ -0,0 +1,11 @@
+"""Single source of truth for the SDK version string.
+
+Kept in its own module so internal helpers can import it without forcing
+the full ``ausdata/__init__.py`` to initialise (which would cause a circular
+import: ``__init__`` imports ``Client``, which imports ``_internal.http``,
+which used to import back from ``__init__`` for ``__version__``).
+"""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"

ausdata/async_client.py

@@ -0,0 +1,253 @@
+"""Asynchronous ``AsyncClient`` for the ausdata REST API.
+
+Mirrors :class:`ausdata.Client` one-to-one; only the I/O is awaitable. The
+two classes deliberately share neither a base class nor a transport so the
+sync version stays usable without an event loop.
+
+Usage::
+
+    async with AsyncClient(api_key="ak_xxx") as client:
+        result = await client.real_wages(start="2019-Q1")
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Literal, Self
+
+import httpx
+
+from ._internal.http import (
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    build_default_headers,
+    normalise_base_url,
+    raise_for_response,
+    resolve_api_key,
+)
+from ._internal.retry import RetryPolicy
+from .exceptions import AusdataError
+from .models import (
+    AccountResponse,
+    ApiResponse,
+    DatasetSummary,
+    EconomicDashboard,
+    HealthResponse,
+    RealWageRow,
+    WhoamiResponse,
+    parse_api_response,
+)
+
+
+class _AsyncAccountNamespace:
+    """Async equivalent of :class:`ausdata.client._AccountNamespace`."""
+
+    def __init__(self, client: "AsyncClient") -> None:
+        self._client = client
+
+    async def api_key(self) -> AccountResponse:
+        """Fetch the current account's API key (creates one if first call)."""
+        body = await self._client._request("GET", "/v1/account/api-key")
+        return AccountResponse.model_validate(body)
+
+    async def rotate_key(self) -> AccountResponse:
+        """Revoke the current key and issue a new one. Plaintext returned once."""
+        body = await self._client._request(
+            "POST", "/v1/account/api-key", params={"rotate": "true"}
+        )
+        return AccountResponse.model_validate(body)
+
+
+class AsyncClient:
+    """Asynchronous client for the ausdata REST API.
+
+    Construction args mirror :class:`ausdata.Client`. Use as an async
+    context manager so the underlying ``httpx.AsyncClient`` connection
+    pool is released::
+
+        async with AsyncClient(api_key="ak_xxx") as client:
+            ...
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = 3,
+        retry_backoff_factor: float = 2.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        resolved_key = resolve_api_key(api_key)
+        self._base_url = normalise_base_url(base_url) or DEFAULT_BASE_URL
+        self._retry_policy = RetryPolicy(
+            max_retries=max_retries,
+            backoff_factor=retry_backoff_factor,
+        )
+        self._httpx = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers=build_default_headers(resolved_key),
+            timeout=timeout,
+            transport=transport,
+        )
+        self.account = _AsyncAccountNamespace(self)
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Release the underlying httpx connection pool."""
+        await self._httpx.aclose()
+
+    # ------------------------------------------------------------------
+    # Endpoint methods (parameter docs live on the sync Client)
+    # ------------------------------------------------------------------
+
+    async def health(self) -> HealthResponse:
+        """``GET /v1/health`` — service status; doesn't consume your quota."""
+        body = await self._request("GET", "/v1/health")
+        return HealthResponse.model_validate(body)
+
+    async def whoami(self) -> WhoamiResponse:
+        """``GET /v1/whoami`` — verify credentials and see your tier/usage."""
+        body = await self._request("GET", "/v1/whoami")
+        return WhoamiResponse.model_validate(body)
+
+    async def search_datasets(
+        self,
+        q: str,
+        *,
+        source: str | list[str] | None = None,
+        limit: int = 10,
+    ) -> ApiResponse[list[DatasetSummary]]:
+        """``GET /v1/search-datasets`` — fan-out search across all 9 sources."""
+        params: dict[str, Any] = {"q": q, "limit": limit}
+        if source is not None:
+            params["source"] = (
+                source if isinstance(source, str) else ",".join(source)
+            )
+        body = await self._request("GET", "/v1/search-datasets", params=params)
+        return parse_api_response(body, data_list_model=DatasetSummary)
+
+    async def real_wages(
+        self,
+        *,
+        start: str = "2019-Q1",
+        end: str | None = None,
+        seasonal_adjustment: Literal[
+            "original", "trend", "seasonally_adjusted"
+        ] = "trend",
+    ) -> ApiResponse[list[RealWageRow]]:
+        """``GET /v1/real-wages`` — WPI YoY minus CPI YoY quarterly series."""
+        params: dict[str, Any] = {
+            "start": start,
+            "seasonal_adjustment": seasonal_adjustment,
+        }
+        if end is not None:
+            params["end"] = end
+        body = await self._request("GET", "/v1/real-wages", params=params)
+        return parse_api_response(body, data_list_model=RealWageRow)
+
+    async def economic_dashboard(
+        self,
+        *,
+        period: str = "latest",
+    ) -> ApiResponse[EconomicDashboard]:
+        """``GET /v1/economic-dashboard`` — five headline macro indicators."""
+        body = await self._request(
+            "GET", "/v1/economic-dashboard", params={"period": period}
+        )
+        return parse_api_response(body, data_model=EconomicDashboard)
+
+    async def list_datasets(self, source: str) -> dict[str, Any]:
+        """``GET /v1/datasets/{source}`` — see sync client docs."""
+        return await self._request("GET", f"/v1/datasets/{source}")
+
+    async def describe(self, source: str, dataset_id: str) -> dict[str, Any]:
+        """``GET /v1/describe/{source}/{dataset_id}`` — see sync client docs."""
+        return await self._request(
+            "GET", f"/v1/describe/{source}/{dataset_id}"
+        )
+
+    async def get_data(
+        self,
+        source: str,
+        dataset_id: str,
+        *,
+        start: str | None = None,
+        end: str | None = None,
+        limit: int = 100,
+        format: Literal["json", "csv"] = "json",
+        **filters: Any,
+    ) -> ApiResponse[list[dict[str, Any]]]:
+        """``GET /v1/data/{source}/{dataset_id}`` — generic data passthrough.
+
+        See :meth:`ausdata.Client.get_data` for parameter docs.
+        """
+        params: dict[str, Any] = {"limit": limit, "format": format, **filters}
+        if start is not None:
+            params["start"] = start
+        if end is not None:
+            params["end"] = end
+        body = await self._request("GET", f"/v1/data/{source}/{dataset_id}", params=params)
+        return parse_api_response(body)
+
+    # ------------------------------------------------------------------
+    # Request execution + retry loop
+    # ------------------------------------------------------------------
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any | None = None,
+    ) -> dict[str, Any]:
+        attempt = 0
+        while True:
+            try:
+                response = await self._httpx.request(
+                    method, path, params=params, json=json
+                )
+            except Exception as exc:
+                if (
+                    self._retry_policy.should_retry_exception(exc)
+                    and attempt < self._retry_policy.max_retries
+                ):
+                    attempt += 1
+                    await asyncio.sleep(self._retry_policy.backoff_seconds(attempt))
+                    continue
+                raise AusdataError(
+                    f"Transport error contacting ausdata API: {exc}"
+                ) from exc
+
+            if response.is_success:
+                try:
+                    return response.json()
+                except ValueError as exc:
+                    raise AusdataError(
+                        "API returned a non-JSON 2xx response.",
+                        status_code=response.status_code,
+                    ) from exc
+
+            if (
+                self._retry_policy.should_retry_status(response.status_code)
+                and attempt < self._retry_policy.max_retries
+            ):
+                attempt += 1
+                if response.status_code == 429:
+                    wait = self._retry_policy.retry_after_seconds(response) or (
+                        self._retry_policy.backoff_seconds(attempt)
+                    )
+                else:
+                    wait = self._retry_policy.backoff_seconds(attempt)
+                await asyncio.sleep(wait)
+                continue
+
+            raise_for_response(response)
+            return {}  # pragma: no cover