ausdata-sdk 0.2.0__py3-none-any.whl

ausdata/client.py

@@ -0,0 +1,349 @@
+"""Synchronous ``Client`` for the ausdata REST API.
+
+Built on ``httpx.Client``. Mirrors :class:`ausdata.AsyncClient` one-to-one
+in surface area so callers can swap freely. Method docstrings here are the
+canonical place to learn the public surface — the async client just delegates.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Literal, Self
+
+import httpx
+
+from ._internal.http import (
+    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 _AccountNamespace:
+    """Sub-namespace for ``client.account.*`` JWT-only methods.
+
+    Implemented as an attribute proxy so callers get a clean ``client.account.api_key()``
+    surface without flooding the top-level client with dozens of methods.
+    """
+
+    def __init__(self, client: "Client") -> None:
+        self._client = client
+
+    def api_key(self) -> AccountResponse:
+        """Fetch the current account's API key (creates one if first call).
+
+        Note: the plaintext key is only returned on the very first call;
+        subsequent calls return a masked display value. Rotate the key with
+        :meth:`rotate_key` to force a new plaintext.
+        """
+        body = self._client._request("GET", "/v1/account/api-key")
+        return AccountResponse.model_validate(body)
+
+    def rotate_key(self) -> AccountResponse:
+        """Revoke the current key and issue a new one. Plaintext returned once.
+
+        Save the returned ``key`` immediately — you can't fetch the
+        plaintext again without rotating again.
+        """
+        body = self._client._request(
+            "POST", "/v1/account/api-key", params={"rotate": "true"}
+        )
+        return AccountResponse.model_validate(body)
+
+
+class Client:
+    """Synchronous client for the ausdata REST API.
+
+    Args:
+        api_key: Bearer token. If omitted, falls back to the
+            ``AUSDATA_API_KEY`` env var. Raises ``AuthenticationError``
+            when neither source is set.
+        base_url: Override the default ``https://api.ausdata.io``. Useful
+            for local development against a staging instance.
+        timeout: Per-request timeout in seconds. Defaults to 30s.
+        max_retries: Maximum retry attempts on 5xx / 429 / network errors.
+            Defaults to 3.
+        retry_backoff_factor: Multiplier for exponential backoff between
+            retries. Defaults to 2.0 (so delays go 1s, 2s, 4s).
+        transport: Optional ``httpx.BaseTransport`` for advanced use
+            (mocking in tests, custom DNS, etc.).
+    """
+
+    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.BaseTransport | None = None,
+    ) -> None:
+        resolved_key = resolve_api_key(api_key)
+        self._base_url = normalise_base_url(base_url)
+        self._retry_policy = RetryPolicy(
+            max_retries=max_retries,
+            backoff_factor=retry_backoff_factor,
+        )
+        self._httpx = httpx.Client(
+            base_url=self._base_url,
+            headers=build_default_headers(resolved_key),
+            timeout=timeout,
+            transport=transport,
+        )
+        self.account = _AccountNamespace(self)
+
+    # ------------------------------------------------------------------
+    # Context manager — encourage explicit cleanup of the connection pool.
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Release the underlying httpx connection pool."""
+        self._httpx.close()
+
+    # ------------------------------------------------------------------
+    # Endpoint methods
+    # ------------------------------------------------------------------
+
+    def health(self) -> HealthResponse:
+        """``GET /v1/health`` — service status; doesn't consume your quota."""
+        body = self._request("GET", "/v1/health")
+        return HealthResponse.model_validate(body)
+
+    def whoami(self) -> WhoamiResponse:
+        """``GET /v1/whoami`` — verify credentials and see your tier/usage.
+
+        Works for both API-key and JWT callers. Never includes the plaintext
+        key — safe to print or log.
+        """
+        body = self._request("GET", "/v1/whoami")
+        return WhoamiResponse.model_validate(body)
+
+    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.
+
+        Args:
+            q: Plain-English query, 2-200 chars.
+            source: Optional restriction to specific sources. Accepts a
+                comma-separated string or a list (e.g. ``["abs", "rba"]``).
+            limit: Max results (1-50, default 10).
+        """
+        params: dict[str, Any] = {"q": q, "limit": limit}
+        if source is not None:
+            params["source"] = (
+                source if isinstance(source, str) else ",".join(source)
+            )
+        body = self._request("GET", "/v1/search-datasets", params=params)
+        return parse_api_response(body, data_list_model=DatasetSummary)
+
+    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.
+
+        Args:
+            start: Quarter start, ``YYYY`` or ``YYYY-Qn``. Bare years coerce
+                to Q1 server-side.
+            end: Quarter end. Defaults to the latest published quarter.
+            seasonal_adjustment: Match the ABS methodology you want.
+        """
+        params: dict[str, Any] = {
+            "start": start,
+            "seasonal_adjustment": seasonal_adjustment,
+        }
+        if end is not None:
+            params["end"] = end
+        body = self._request("GET", "/v1/real-wages", params=params)
+        return parse_api_response(body, data_list_model=RealWageRow)
+
+    def economic_dashboard(
+        self,
+        *,
+        period: str = "latest",
+    ) -> ApiResponse[EconomicDashboard]:
+        """``GET /v1/economic-dashboard`` — five headline macro indicators.
+
+        Composes RBA F1.1 cash rate + ABS CPI / LF / WPI / LEND_HOUSING.
+        """
+        body = self._request(
+            "GET", "/v1/economic-dashboard", params={"period": period}
+        )
+        return parse_api_response(body, data_model=EconomicDashboard)
+
+    def list_datasets(self, source: str) -> dict[str, Any]:
+        """``GET /v1/datasets/{source}`` — enumerate curated datasets for a source.
+
+        Useful for surveying what's available before drilling in. Pairs with
+        :meth:`describe` and :meth:`get_data` for the full discover →
+        introspect → fetch loop.
+
+        Args:
+            source: One of ``abs``, ``rba``, ``ato``, ``apra``, ``aihw``,
+                ``asic``, ``aemo``, ``wgea``.
+
+        Example::
+
+            ds = client.list_datasets("abs")
+            for d in ds["data"]:
+                print(d["id"], "→", d.get("name"))
+        """
+        return self._request("GET", f"/v1/datasets/{source}")
+
+    def describe(self, source: str, dataset_id: str) -> dict[str, Any]:
+        """``GET /v1/describe/{source}/{dataset_id}`` — schema introspection.
+
+        Returns the dataset's dimensions, valid filters, valid values per
+        filter, units, and source links. Call this after a 400 'Unknown
+        filter' / 'Unknown value' from :meth:`get_data` to discover the
+        correct shape.
+
+        Args:
+            source: One of ``abs``, ``rba``, ``ato``, ``apra``, ``aihw``,
+                ``asic``, ``aemo``, ``wgea``.
+            dataset_id: Dataset ID from search results (e.g. ``"LF"``,
+                ``"F1.1"``). Source-prefixed forms like ``"abs.LF"`` also
+                accepted — the prefix is stripped server-side.
+
+        Example::
+
+            schema = client.describe("abs", "LF")
+            for dim in schema["data"]["dimensions"]:
+                print(dim["name"], "→", [v["key"] for v in dim["values"]])
+        """
+        return self._request(
+            "GET", f"/v1/describe/{source}/{dataset_id}"
+        )
+
+    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.
+
+        Fetches data from any of the 9 sister MCPs. Discover IDs with
+        :meth:`search_datasets`.
+
+        Args:
+            source: One of ``abs``, ``rba``, ``ato``, ``apra``, ``aihw``,
+                ``asic``, ``aemo``, ``au_weather``, ``wgea``.
+            dataset_id: Dataset ID from search results (e.g. ``"CPI"``,
+                ``"F1.1"``, ``"ADI_KEY_STATS"``).
+            start: Inclusive start period. Format varies by source —
+                ``YYYY-Q1`` quarterly, ``YYYY-MM`` monthly, ``YYYY`` annual.
+            end: Inclusive end period (same format as ``start``).
+            limit: Max rows (1-1000, default 100).
+            format: ``"json"`` (default) or ``"csv"``.
+            **filters: Source-specific dimension filters forwarded as query
+                params (e.g. ``region="australia"``, ``measure="change_year"``).
+
+        Example::
+
+            cpi = client.get_data("abs", "CPI", region="australia",
+                                   measure="change_year", limit=12)
+        """
+        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 = self._request("GET", f"/v1/data/{source}/{dataset_id}", params=params)
+        return parse_api_response(body)
+
+    # ------------------------------------------------------------------
+    # Request execution + retry loop
+    # ------------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any | None = None,
+    ) -> dict[str, Any]:
+        """Execute one request, retrying transient failures per the policy."""
+        attempt = 0
+        while True:
+            try:
+                response = 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
+                    time.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)
+                time.sleep(wait)
+                continue
+
+            # Out of retries — let raise_for_response translate to a typed error.
+            raise_for_response(response)
+            # raise_for_response always raises on non-2xx, but keep mypy happy.
+            return {}  # pragma: no cover
+        # Unreachable — loop only exits via return or raise.

ausdata/exceptions.py

@@ -0,0 +1,101 @@
+"""Exception hierarchy for the ausdata SDK.
+
+All errors inherit from :class:`AusdataError` so callers can do a single
+``except AusdataError`` if they don't care about specifics. Each specific
+class carries the API's error message plus the actionable ``hint`` returned
+by the server when present (see ``ErrorDetail`` in ausdata-api).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class AusdataError(Exception):
+    """Base class for every error raised by the ausdata SDK.
+
+    Attributes:
+        message: Human-readable error string.
+        status_code: HTTP status code that caused the error (None for
+            client-side errors like missing API key).
+        hint: Optional "Try X" guidance returned by the API. Surfaced
+            prominently when present.
+        response_body: Raw JSON body from the API, if parsed successfully.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        hint: str | None = None,
+        response_body: dict[str, Any] | None = None,
+    ) -> None:
+        self.message = message
+        self.status_code = status_code
+        self.hint = hint
+        self.response_body = response_body
+        full = message
+        if hint:
+            full = f"{message} (hint: {hint})"
+        super().__init__(full)
+
+
+class AuthenticationError(AusdataError):
+    """401 — API key is missing, malformed, or revoked.
+
+    Check your ``AUSDATA_API_KEY`` env var or the ``api_key`` argument
+    passed to ``Client(...)``. Rotate the key in the dashboard if you
+    suspect it has been compromised.
+    """
+
+
+class PermissionError(AusdataError):  # noqa: A001 — intentional shadow of builtin
+    """403 — your tier doesn't grant access to this endpoint or feature.
+
+    The ``hint`` typically names the tier required (e.g. "Upgrade to
+    ANALYST at https://ausdata.io/pricing").
+    """
+
+
+class RateLimitError(AusdataError):
+    """429 — monthly call quota exceeded, or per-minute burst limit hit.
+
+    Attributes:
+        retry_after: Seconds to wait before retrying, parsed from the
+            ``Retry-After`` response header. ``None`` if absent.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_after: float | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self.retry_after = retry_after
+        super().__init__(message, **kwargs)
+
+
+class ValidationError(AusdataError):
+    """400 — request rejected by the API.
+
+    Common causes: malformed period strings, unknown dataset IDs,
+    invalid enum values. The ``hint`` usually suggests the fix.
+    """
+
+
+class UpstreamError(AusdataError):
+    """502/503 — a sister data source (ABS, RBA, etc.) is failing upstream.
+
+    Retries already happened automatically before this was raised. The
+    API may serve a stale cached response on subsequent calls (look for
+    ``meta.stale=True``).
+    """
+
+
+class AusdataServerError(AusdataError):
+    """5xx — generic server-side failure not covered by :class:`UpstreamError`.
+
+    Raised after the SDK's automatic retries are exhausted.
+    """