fpu-barometer 0.3.0__tar.gz

fpu_barometer-0.3.0/.gitignore

@@ -0,0 +1,9 @@
+data/*
+.env
+.pytest_cache/
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+*.whl
+.ruff_cache/

fpu_barometer-0.3.0/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2026 Free Press Unlimited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

fpu_barometer-0.3.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: fpu-barometer
+Version: 0.3.0
+Summary: Free Press Unlimited researcher-facing API client
+Project-URL: Homepage, https://www.freepressunlimited.org
+Author: Phillip Kersten, Jannes Kelso, Jos Bartman
+License-Expression: MIT
+License-File: LICENSE.md
+Keywords: barometer,data-science,fpu,journalists,press
+Requires-Python: >=3.10
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: requests>=2.28.0
+Description-Content-Type: text/markdown
+
+# fpu-barometer
+
+Lightweight researcher-facing API client for Barometer.

fpu_barometer-0.3.0/README.md

@@ -0,0 +1,3 @@
+# fpu-barometer
+
+Lightweight researcher-facing API client for Barometer.

fpu_barometer-0.3.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fpu-barometer"
+version = "0.3.0"
+description = "Free Press Unlimited researcher-facing API client"
+authors = [
+    {name = "Phillip Kersten"},
+    {name = "Jannes Kelso"},
+    {name = "Jos Bartman"},
+]
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "pandas>=2.0.0",
+    "requests>=2.28.0",
+]
+keywords = [
+    "press",
+    "journalists",
+    "fpu",
+    "barometer",
+    "data-science",
+]
+
+[project.urls]
+Homepage = "https://www.freepressunlimited.org"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fpu_barometer"]

fpu_barometer-0.3.0/src/fpu_barometer/__init__.py

@@ -0,0 +1,70 @@
+"""FPU/Barometer thin researcher-facing API client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fpu_barometer.client import FPUClient
+from fpu_barometer.config import configure, get_config
+from fpu_barometer.dataframe import response_to_dataframe
+from fpu_barometer.models import (
+    DataResponse,
+    DatasetFilter,
+    DatasetListResponse,
+    DatasetStatus,
+    EnrichmentRequest,
+    EventsRequest,
+    InvalidCursorError,
+    PredictorsRequest,
+    decode_page_cursor,
+    encode_page_cursor,
+)
+
+__version__ = "0.3.0"
+
+
+def client() -> FPUClient:
+    return FPUClient()
+
+
+def get_events(events: str | list[str], countries: list[str] | None = None, years: list[int] | None = None, **kwargs: Any):
+    with FPUClient() as api:
+        return api.get_events(events, countries, years, **kwargs)
+
+
+def get_predictors(predictors: str | list[str], countries: list[str] | None = None, years: list[int] | None = None, **kwargs: Any):
+    with FPUClient() as api:
+        return api.get_predictors(predictors, countries, years, **kwargs)
+
+
+def enrich_events(events: str | list[str], predictors: str | list[str], countries: list[str] | None = None, years: list[int] | None = None, **kwargs: Any):
+    with FPUClient() as api:
+        return api.enrich_events(events, predictors, countries, years, **kwargs)
+
+
+def list_datasets() -> dict[str, Any]:
+    with FPUClient() as api:
+        return api.list_datasets()
+
+
+__all__ = [
+    "FPUClient",
+    "configure",
+    "get_config",
+    "client",
+    "get_events",
+    "get_predictors",
+    "enrich_events",
+    "list_datasets",
+    "response_to_dataframe",
+    "DataResponse",
+    "DatasetFilter",
+    "DatasetListResponse",
+    "DatasetStatus",
+    "EventsRequest",
+    "PredictorsRequest",
+    "EnrichmentRequest",
+    "InvalidCursorError",
+    "encode_page_cursor",
+    "decode_page_cursor",
+]

fpu_barometer-0.3.0/src/fpu_barometer/client.py

@@ -0,0 +1,151 @@
+"""Researcher-facing HTTP API client for Barometer."""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+import pandas as pd
+import requests
+
+from fpu_barometer.config import FPUConfig, get_config
+from fpu_barometer.dataframe import response_to_dataframe
+from fpu_barometer.models import (
+    DataResponse,
+    DatasetListResponse,
+    EnrichmentRequest,
+    EventsRequest,
+    PredictorsRequest,
+)
+
+
+class FPUClient:
+    """Thin HTTP client.
+
+    This class only sends HTTP requests. Backend resolution of current
+    Processed Dataset Versions happens behind the API.
+    """
+
+    def __init__(self, config: FPUConfig | None = None, session: requests.Session | None = None):
+        self.config = config or get_config()
+        self.base_url = self.config.api_base_url
+        self.session = session or requests.Session()
+        headers = {"Content-Type": "application/json"}
+        if self.config.api_key:
+            headers["Authorization"] = f"Bearer {self.config.api_key}"
+        self.session.headers.update(headers)
+
+    def get_events(self, events: str | list[str], countries: list[str] | None = None, years: list[int] | None = None, **kwargs: Any):
+        return self._paginated_data_response(
+            "events", EventsRequest,
+            events=_as_list(events), countries=countries, years=years, **kwargs,
+        )
+
+    def get_predictors(self, predictors: str | list[str], countries: list[str] | None = None, years: list[int] | None = None, **kwargs: Any):
+        return self._paginated_data_response(
+            "predictors", PredictorsRequest,
+            predictors=_as_list(predictors), countries=countries, years=years, **kwargs,
+        )
+
+    def enrich_events(self, events: str | list[str], predictors: str | list[str], countries: list[str] | None = None, years: list[int] | None = None, **kwargs: Any):
+        return self._paginated_data_response(
+            "enrich", EnrichmentRequest,
+            events=_as_list(events), predictors=_as_list(predictors), countries=countries, years=years, **kwargs,
+        )
+
+    def list_datasets(self) -> dict[str, Any]:
+        return DatasetListResponse.from_dict(self._request("GET", "datasets")).to_dict()
+
+    def _paginated_data_response(self, route: str, request_cls: type, **kwargs: Any) -> pd.DataFrame:
+        """Fetch all pages for a data response endpoint, looping on next_cursor."""
+        limit = _pop_client_limit(kwargs)
+        requested_page_size = kwargs.pop("page_size", 10_000)
+        warn_on_unbounded = kwargs.pop("warn_on_unbounded", True)
+
+        frames: list[pd.DataFrame] = []
+        warned = False
+        rows_so_far = 0
+        next_cursor: str | None = None
+
+        while True:
+            if limit is not None:
+                remaining = limit - rows_so_far
+                if remaining <= 0:
+                    break
+                page_size = min(requested_page_size, remaining)
+            else:
+                page_size = requested_page_size
+
+            payload_kwargs = dict(kwargs)
+            payload_kwargs["page_size"] = page_size
+            if next_cursor is not None:
+                payload_kwargs["cursor"] = next_cursor
+
+            request = request_cls.from_dict(_payload(**payload_kwargs))
+            response = self.post_data_response(route, request.to_dict())
+            frame = response_to_dataframe(response)
+            frames.append(frame)
+            rows_so_far += len(frame)
+
+            next_cursor = response.next_cursor
+
+            if next_cursor is None:
+                break
+
+            if limit is None and warn_on_unbounded and not warned:
+                warnings.warn(
+                    f"{route} is fetching {page_size} rows per page "
+                    f"without a client limit; this may download many rows. "
+                    f"Use `limit=N` to cap it, or `warn_on_unbounded=False` to suppress."
+                )
+                warned = True
+
+        result = pd.concat(frames, ignore_index=True) if frames else pd.DataFrame()
+        if limit is not None:
+            result = result.head(limit)
+        return result
+
+    def post_data_response(self, route: str, payload: dict[str, Any]) -> DataResponse:
+        return DataResponse.from_dict(self._request("POST", route, json=payload))
+
+    def _request(self, method: str, route: str, **kwargs: Any) -> dict[str, Any]:
+        response = self.session.request(
+            method,
+            f"{self.base_url}/{route.lstrip('/')}",
+            timeout=self.config.timeout,
+            **kwargs,
+        )
+        if response.status_code >= 400:
+            raise RuntimeError(f"API request failed: {response.status_code} - {response.text}")
+        return response.json()
+
+    def close(self) -> None:
+        self.session.close()
+
+    def __enter__(self) -> "FPUClient":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+
+def _as_list(value: str | list[str]) -> list[str]:
+    if isinstance(value, str):
+        return [value]
+    return list(value)
+
+
+def _pop_client_limit(kwargs: dict[str, Any]) -> int | None:
+    if "limit" not in kwargs:
+        return None
+    limit = kwargs.pop("limit")
+    if limit is None:
+        return None
+    if isinstance(limit, bool) or not isinstance(limit, int) or limit < 1:
+        raise ValueError("limit must be a positive integer")
+    kwargs.setdefault("page_size", min(10_000, limit))
+    return limit
+
+
+def _payload(**values: Any) -> dict[str, Any]:
+    return {key: value for key, value in values.items() if value is not None}

fpu_barometer-0.3.0/src/fpu_barometer/config.py

@@ -0,0 +1,98 @@
+"""Endpoint/auth/timeout configuration for the thin Barometer API client."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class FPUConfig:
+    """Researcher-facing API client configuration."""
+
+    api_endpoint: str = "https://barometer-api-prod-flex.azurewebsites.net"
+    api_key: str | None = None
+    timeout: int = 30
+    max_retries: int = 3
+
+    def __post_init__(self) -> None:
+        if self.api_key is None:
+            self.api_key = os.getenv("FPU_API_KEY")
+
+    @property
+    def api_base_url(self) -> str:
+        base_url = self.api_endpoint.rstrip("/")
+        return base_url if base_url.endswith("/api") else f"{base_url}/api"
+
+    def to_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        data.pop("api_key", None)
+        return data
+
+
+_config: FPUConfig | None = None
+
+
+def configure(**kwargs: Any) -> FPUConfig:
+    """Configure the thin HTTP API client."""
+    global _config
+    # Backward-compatible aliases: mode/local data paths are intentionally ignored
+    # because the public package is now HTTP-only.
+    kwargs.pop("mode", None)
+    kwargs.pop("data_path", None)
+    kwargs.pop("cache_enabled", None)
+    kwargs.pop("cache_path", None)
+    kwargs.pop("local_db_path", None)
+    kwargs.pop("chunk_size", None)
+    kwargs.pop("compression", None)
+
+    if _config is None:
+        _config = FPUConfig(**kwargs)
+    else:
+        for key, value in kwargs.items():
+            if not hasattr(_config, key):
+                raise ValueError(f"Unknown configuration parameter: {key}")
+            setattr(_config, key, value)
+        _config.__post_init__()
+    return _config
+
+
+def get_config() -> FPUConfig:
+    global _config
+    if _config is None:
+        _config = FPUConfig()
+    return _config
+
+
+def reset_config() -> None:
+    global _config
+    _config = None
+
+
+def get_api_base_url() -> str:
+    return get_config().api_base_url
+
+
+def set_api_endpoint(endpoint: str) -> FPUConfig:
+    return configure(api_endpoint=endpoint)
+
+
+def load_config_from_file(config_path: str) -> FPUConfig:
+    path = Path(config_path)
+    if not path.exists():
+        raise FileNotFoundError(f"Configuration file not found: {path}")
+    if path.suffix == ".json":
+        import json
+        return configure(**json.loads(path.read_text()))
+    raise ValueError(f"Unsupported configuration file format: {path.suffix}")
+
+
+def save_config_to_file(config_path: str, config: FPUConfig | None = None) -> None:
+    path = Path(config_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.suffix != ".json":
+        raise ValueError(f"Unsupported configuration file format: {path.suffix}")
+    import json
+    path.write_text(json.dumps((config or get_config()).to_dict(), indent=2))

fpu_barometer-0.3.0/src/fpu_barometer/dataframe.py

@@ -0,0 +1,77 @@
+"""Helpers for converting Barometer JSON/tabular API responses to pandas."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from fpu_barometer.models import DataResponse
+
+
+def response_to_dataframe(
+    response: DataResponse | dict[str, Any] | list[dict[str, Any]],
+) -> pd.DataFrame:
+    """Convert a shared DataResponse, response dict, or records list to a DataFrame."""
+    if isinstance(response, DataResponse):
+        records = response.data
+    elif isinstance(response, dict):
+        records = response.get("data", [])
+    else:
+        records = response
+    return pd.DataFrame(records)
+
+
+def dataframe_to_response(df: pd.DataFrame, **metadata: Any) -> DataResponse:
+    """Convert a DataFrame to the shared tabular response contract."""
+    query_time_seconds = metadata.pop("query_time_seconds", None)
+    next_cursor = metadata.pop("next_cursor", None)
+    page_size = metadata.pop("page_size", None)
+    sort_by = metadata.pop("sort_by", None)
+    sort_order = metadata.pop("sort_order", None)
+    records = [
+        {key: _jsonable_cell(value) for key, value in record.items()}
+        for record in df.to_dict(orient="records")
+    ]
+    return DataResponse(
+        data=records,
+        rows=len(records),
+        query_time_seconds=query_time_seconds,
+        metadata=metadata,
+        next_cursor=next_cursor,
+        page_size=page_size,
+        sort_by=sort_by,
+        sort_order=sort_order,
+    )
+
+
+def _jsonable_cell(value: Any) -> Any:
+    if value is None:
+        return None
+    if _is_numpy_array(value):
+        items = value.tolist()
+        if not isinstance(items, list):
+            return _jsonable_cell(items)
+        return [_jsonable_cell(item) for item in items]
+    if isinstance(value, (list, tuple)):
+        return [_jsonable_cell(item) for item in value]
+    if isinstance(value, dict):
+        return {key: _jsonable_cell(item) for key, item in value.items()}
+    try:
+        if pd.isna(value):
+            return None
+    except (TypeError, ValueError):
+        pass
+    item = getattr(value, "item", None)
+    if callable(item):
+        try:
+            return item()
+        except (TypeError, ValueError):
+            pass
+    return value
+
+
+def _is_numpy_array(value: Any) -> bool:
+    return (
+        type(value).__module__.startswith("numpy") and type(value).__name__ == "ndarray"
+    )

fpu_barometer-0.3.0/src/fpu_barometer/models.py

@@ -0,0 +1,501 @@
+"""Shared request/response contracts for the Barometer HTTP API."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+from dataclasses import asdict, dataclass, field
+import json
+import re
+from typing import Any, Literal
+
+DatasetKind = Literal["events", "predictors"]
+AvailabilityStatus = Literal["available", "stale", "unavailable"]
+RunStatus = Literal["running", "success", "failed", "skipped"]
+ExpectedCadence = Literal["static", "daily", "monthly", "annual", "ad_hoc"]
+RefreshMode = Literal["full_refresh", "incremental"]
+SourceType = Literal[
+    "static_file",
+    "api_endpoint",
+    "watched_file",
+    "zipped_file_download",
+    "release_asset",
+]
+
+_DATASET_NAME_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_ISO3_PATTERN = re.compile(r"^[A-Z]{3}$")
+_DATASET_KINDS = {"events", "predictors"}
+_AVAILABILITY_STATUSES = {"available", "stale", "unavailable"}
+_RUN_STATUSES = {"running", "success", "failed", "skipped"}
+_EXPECTED_CADENCES = {"static", "daily", "monthly", "annual", "ad_hoc"}
+_REFRESH_MODES = {"full_refresh", "incremental"}
+_SOURCE_TYPES = {
+    "static_file",
+    "api_endpoint",
+    "watched_file",
+    "zipped_file_download",
+    "release_asset",
+    "web_download",
+}
+_MAX_PAGE_SIZE = 10_000
+_SORT_ORDERS = {"asc", "desc"}
+_DATASET_STATUS_FIELDS = {
+    "dataset",
+    "kind",
+    "availability_status",
+    "last_run_status",
+    "last_successful_refresh",
+    "last_attempted_refresh",
+    "expected_cadence",
+    "refresh_mode",
+    "source_type",
+    "current_version_id",
+    "row_count",
+}
+
+
+class APIContractError(ValueError):
+    """Base error for invalid public API contracts."""
+
+    code = "invalid_request"
+
+    def __init__(self, message: str, *, details: dict[str, Any] | None = None):
+        super().__init__(message)
+        self.details = details or {}
+
+
+class InvalidRequestError(APIContractError):
+    """Request body shape does not match the public API contract."""
+
+    code = "invalid_request"
+
+
+class InvalidFilterError(APIContractError):
+    """Request filters do not match the public API contract."""
+
+    code = "invalid_filter"
+
+
+class InvalidCursorError(APIContractError):
+    """Page Cursor cannot be decoded as a public API cursor."""
+
+    code = "invalid_cursor"
+
+
+@dataclass(frozen=True)
+class DatasetFilter:
+    """Common country/year filters accepted by data requests."""
+
+    countries: list[str] | None = None
+    years: list[int] | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "DatasetFilter":
+        data = data or {}
+        if not isinstance(data, dict):
+            raise InvalidRequestError("Request body must be a JSON object", details={})
+        countries = _optional_array(data, "countries", _validate_country, InvalidFilterError)
+        years = _optional_array(data, "years", _validate_year, InvalidFilterError)
+        return cls(countries=countries, years=years)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {k: v for k, v in asdict(self).items() if v is not None}
+
+
+@dataclass(frozen=True)
+class EventsRequest:
+    events: list[str]
+    filters: DatasetFilter = field(default_factory=DatasetFilter)
+    page_size: int = _MAX_PAGE_SIZE
+    cursor: str | None = None
+    sort_by: str = "date"
+    sort_order: str = "desc"
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "EventsRequest":
+        _validate_object(data)
+        _reject_removed_limit(data)
+        events = _required_dataset_array(data, "events")
+        _reject_unknown_fields(data, {"events", "countries", "years", "page_size", "cursor", "sort_by", "sort_order"})
+        pagination = _parse_pagination(data, allowed_sort_by={"date"}, default_sort_by="date")
+        return cls(events=events, filters=DatasetFilter.from_dict(data), **pagination)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "events": self.events,
+            **self.filters.to_dict(),
+            **_pagination_to_dict(self.page_size, self.cursor, self.sort_by, self.sort_order),
+        }
+
+
+@dataclass(frozen=True)
+class PredictorsRequest:
+    predictors: list[str]
+    filters: DatasetFilter = field(default_factory=DatasetFilter)
+    page_size: int = _MAX_PAGE_SIZE
+    cursor: str | None = None
+    sort_by: str = "year"
+    sort_order: str = "desc"
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "PredictorsRequest":
+        _validate_object(data)
+        _reject_removed_limit(data)
+        predictors = _required_dataset_array(data, "predictors")
+        _reject_unknown_fields(data, {"predictors", "countries", "years", "page_size", "cursor", "sort_by", "sort_order"})
+        pagination = _parse_pagination(data, allowed_sort_by={"year"}, default_sort_by="year")
+        return cls(predictors=predictors, filters=DatasetFilter.from_dict(data), **pagination)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "predictors": self.predictors,
+            **self.filters.to_dict(),
+            **_pagination_to_dict(self.page_size, self.cursor, self.sort_by, self.sort_order),
+        }
+
+
+@dataclass(frozen=True)
+class EnrichmentRequest:
+    events: list[str]
+    predictors: list[str]
+    filters: DatasetFilter = field(default_factory=DatasetFilter)
+    page_size: int = _MAX_PAGE_SIZE
+    cursor: str | None = None
+    sort_by: str = "date"
+    sort_order: str = "desc"
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "EnrichmentRequest":
+        _validate_object(data)
+        _reject_removed_limit(data)
+        events = _required_dataset_array(data, "events")
+        predictors = _required_dataset_array(data, "predictors")
+        _reject_unknown_fields(data, {"events", "predictors", "countries", "years", "page_size", "cursor", "sort_by", "sort_order"})
+        pagination = _parse_pagination(data, allowed_sort_by={"date"}, default_sort_by="date")
+        return cls(
+            events=events,
+            predictors=predictors,
+            filters=DatasetFilter.from_dict(data),
+            **pagination,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "events": self.events,
+            "predictors": self.predictors,
+            **self.filters.to_dict(),
+            **_pagination_to_dict(self.page_size, self.cursor, self.sort_by, self.sort_order),
+        }
+
+
+@dataclass(frozen=True)
+class DatasetStatus:
+    """Public Dataset Status item returned by the dataset listing endpoint."""
+
+    dataset: str
+    kind: DatasetKind
+    availability_status: AvailabilityStatus
+    last_run_status: RunStatus | None
+    last_successful_refresh: str | None
+    last_attempted_refresh: str | None
+    expected_cadence: ExpectedCadence
+    refresh_mode: RefreshMode
+    source_type: SourceType
+    current_version_id: str | None
+    row_count: int | None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "DatasetStatus":
+        _validate_object(data)
+        _require_fields(data, _DATASET_STATUS_FIELDS, "Dataset status")
+        _reject_unknown_fields(data, _DATASET_STATUS_FIELDS)
+        dataset = _validate_dataset_name(data["dataset"], "dataset")
+        return cls(
+            dataset=dataset,
+            kind=_literal(data["kind"], "kind", _DATASET_KINDS),
+            availability_status=_literal(
+                data["availability_status"],
+                "availability_status",
+                _AVAILABILITY_STATUSES,
+            ),
+            last_run_status=_nullable_literal(
+                data["last_run_status"], "last_run_status", _RUN_STATUSES
+            ),
+            last_successful_refresh=_nullable_str(
+                data["last_successful_refresh"], "last_successful_refresh"
+            ),
+            last_attempted_refresh=_nullable_str(
+                data["last_attempted_refresh"], "last_attempted_refresh"
+            ),
+            expected_cadence=_literal(
+                data["expected_cadence"], "expected_cadence", _EXPECTED_CADENCES
+            ),
+            refresh_mode=_literal(data["refresh_mode"], "refresh_mode", _REFRESH_MODES),
+            source_type=_literal(data["source_type"], "source_type", _SOURCE_TYPES),
+            current_version_id=_nullable_str(
+                data["current_version_id"], "current_version_id"
+            ),
+            row_count=_nullable_nonnegative_int(data["row_count"], "row_count"),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class DatasetListResponse:
+    """Public dataset listing response."""
+
+    datasets: list[DatasetStatus]
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "DatasetListResponse":
+        _validate_object(data)
+        _require_fields(data, {"datasets"}, "Dataset list response")
+        _reject_unknown_fields(data, {"datasets"})
+        datasets = data["datasets"]
+        if not isinstance(datasets, list):
+            raise InvalidRequestError(
+                "datasets must be an array", details={"field": "datasets"}
+            )
+        return cls(datasets=[DatasetStatus.from_dict(item) for item in datasets])
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"datasets": [dataset.to_dict() for dataset in self.datasets]}
+
+
+@dataclass(frozen=True)
+class DataResponse:
+    """Tabular API response shared by client and handlers."""
+
+    data: list[dict[str, Any]]
+    rows: int | None = None
+    query_time_seconds: float | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    next_cursor: str | None = None
+    page_size: int | None = None
+    sort_by: str | None = None
+    sort_order: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "DataResponse":
+        known = {
+            "data",
+            "rows",
+            "query_time_seconds",
+            "metadata",
+            "next_cursor",
+            "page_size",
+            "sort_by",
+            "sort_order",
+        }
+        metadata = dict(data.get("metadata") or {})
+        metadata.update({k: v for k, v in data.items() if k not in known})
+        return cls(
+            data=list(data.get("data", [])),
+            rows=data.get("rows"),
+            query_time_seconds=data.get("query_time_seconds"),
+            metadata=metadata,
+            next_cursor=data.get("next_cursor"),
+            page_size=data.get("page_size"),
+            sort_by=data.get("sort_by"),
+            sort_order=data.get("sort_order"),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {"data": self.data, "rows": self.rows if self.rows is not None else len(self.data)}
+        if self.query_time_seconds is not None:
+            payload["query_time_seconds"] = self.query_time_seconds
+        if self.metadata:
+            payload["metadata"] = self.metadata
+        if self.next_cursor is not None:
+            payload["next_cursor"] = self.next_cursor
+        if self.page_size is not None:
+            payload["page_size"] = self.page_size
+        if self.sort_by is not None:
+            payload["sort_by"] = self.sort_by
+        if self.sort_order is not None:
+            payload["sort_order"] = self.sort_order
+        return payload
+
+
+def encode_page_cursor(payload: dict[str, Any]) -> str:
+    """Encode a Page Cursor payload as URL-safe base64 JSON."""
+
+    if not isinstance(payload, dict):
+        raise InvalidCursorError("cursor payload must be a JSON object", details={"field": "cursor"})
+    raw = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+
+def decode_page_cursor(cursor: str) -> dict[str, Any]:
+    """Decode an opaque Page Cursor string into its JSON object payload."""
+
+    if not isinstance(cursor, str) or not cursor:
+        raise InvalidCursorError("cursor is invalid", details={"field": "cursor"})
+    try:
+        padded = cursor + "=" * (-len(cursor) % 4)
+        raw = base64.urlsafe_b64decode(padded.encode("ascii"))
+        payload = json.loads(raw.decode("utf-8"))
+    except (binascii.Error, json.JSONDecodeError, UnicodeDecodeError, ValueError):
+        raise InvalidCursorError("cursor is invalid", details={"field": "cursor"}) from None
+    if not isinstance(payload, dict) or not payload:
+        raise InvalidCursorError("cursor is invalid", details={"field": "cursor"})
+    return payload
+
+
+def _validate_object(data: Any) -> None:
+    if not isinstance(data, dict):
+        raise InvalidRequestError("Request body must be a JSON object", details={})
+
+
+def _reject_removed_limit(data: dict[str, Any]) -> None:
+    if "limit" in data:
+        raise InvalidRequestError(
+            "limit is no longer accepted; use page_size and cursor",
+            details={"field": "limit"},
+        )
+
+
+def _reject_unknown_fields(data: dict[str, Any], allowed: set[str]) -> None:
+    unknown = sorted(set(data) - allowed)
+    if unknown:
+        raise InvalidRequestError(
+            f"Unknown request field: {unknown[0]}",
+            details={"field": unknown[0]},
+        )
+
+
+def _parse_pagination(
+    data: dict[str, Any], *, allowed_sort_by: set[str], default_sort_by: str
+) -> dict[str, int | str | None]:
+    page_size = data.get("page_size", _MAX_PAGE_SIZE)
+    if isinstance(page_size, bool) or not isinstance(page_size, int) or not 1 <= page_size <= _MAX_PAGE_SIZE:
+        raise InvalidRequestError(
+            f"page_size must be an integer between 1 and {_MAX_PAGE_SIZE}",
+            details={"field": "page_size"},
+        )
+    cursor = data.get("cursor")
+    if cursor is not None:
+        decode_page_cursor(cursor)
+    sort_by = data.get("sort_by", default_sort_by)
+    if not isinstance(sort_by, str) or sort_by not in allowed_sort_by:
+        raise InvalidRequestError("sort_by has an unsupported value", details={"field": "sort_by"})
+    sort_order = data.get("sort_order", "desc")
+    if not isinstance(sort_order, str) or sort_order not in _SORT_ORDERS:
+        raise InvalidRequestError(
+            "sort_order has an unsupported value", details={"field": "sort_order"}
+        )
+    return {
+        "page_size": page_size,
+        "cursor": cursor,
+        "sort_by": sort_by,
+        "sort_order": sort_order,
+    }
+
+
+def _pagination_to_dict(
+    page_size: int, cursor: str | None, sort_by: str, sort_order: str
+) -> dict[str, int | str]:
+    payload: dict[str, int | str] = {
+        "page_size": page_size,
+        "sort_by": sort_by,
+        "sort_order": sort_order,
+    }
+    if cursor is not None:
+        payload["cursor"] = cursor
+    return payload
+
+
+def _require_fields(data: dict[str, Any], required: set[str], label: str) -> None:
+    missing = sorted(required - set(data))
+    if missing:
+        raise InvalidRequestError(
+            f"{label} missing required field: {missing[0]}",
+            details={"field": missing[0]},
+        )
+
+
+def _validate_dataset_name(value: Any, field: str) -> str:
+    if not isinstance(value, str) or not _DATASET_NAME_PATTERN.fullmatch(value):
+        raise InvalidRequestError(
+            f"{field} must be a safe dataset name", details={"field": field}
+        )
+    return value
+
+
+def _literal(value: Any, field: str, allowed: set[str]) -> Any:
+    if not isinstance(value, str) or value not in allowed:
+        raise InvalidRequestError(
+            f"{field} has an unsupported value", details={"field": field}
+        )
+    return value
+
+
+def _nullable_literal(value: Any, field: str, allowed: set[str]) -> Any | None:
+    if value is None:
+        return None
+    return _literal(value, field, allowed)
+
+
+def _nullable_str(value: Any, field: str) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise InvalidRequestError(f"{field} must be a string", details={"field": field})
+    return value
+
+
+def _nullable_nonnegative_int(value: Any, field: str) -> int | None:
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        raise InvalidRequestError(
+            f"{field} must be a non-negative integer", details={"field": field}
+        )
+    return value
+
+
+def _required_dataset_array(data: dict[str, Any], field: str) -> list[str]:
+    if field not in data:
+        raise InvalidRequestError(f"Missing required field: {field}", details={"field": field})
+    return _dataset_array(data[field], field)
+
+
+def _dataset_array(value: Any, field: str) -> list[str]:
+    if not isinstance(value, list) or not value:
+        raise InvalidRequestError(f"{field} must be a non-empty array", details={"field": field})
+    datasets: list[str] = []
+    for item in value:
+        if not isinstance(item, str) or not _DATASET_NAME_PATTERN.fullmatch(item):
+            raise InvalidRequestError(
+                f"{field} must contain safe dataset names",
+                details={"field": field},
+            )
+        datasets.append(item)
+    return datasets
+
+
+def _optional_array(data: dict[str, Any], field: str, validate_item, error_type: type[APIContractError]) -> list[Any] | None:
+    if field not in data:
+        return None
+    value = data[field]
+    if value is None:
+        raise error_type(f"{field} must be an array", details={"field": field})
+    if not isinstance(value, list):
+        raise error_type(f"{field} must be an array", details={"field": field})
+    if not value:
+        raise error_type(f"{field} must be a non-empty array", details={"field": field})
+    return [validate_item(item, field) for item in value]
+
+
+def _validate_country(value: Any, field: str) -> str:
+    if not isinstance(value, str) or not _ISO3_PATTERN.fullmatch(value):
+        raise InvalidFilterError("countries must be ISO3 country codes", details={"field": field})
+    return value
+
+
+def _validate_year(value: Any, field: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise InvalidFilterError("years must be integers", details={"field": field})
+    return value