publicsgdata 0.1.0__py3-none-any.whl

publicsgdata/__init__.py

@@ -0,0 +1,23 @@
+"""publicsgdata: Python client for Singapore government public data."""
+
+from publicsgdata._exceptions import (
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    PublicSGDataError,
+    RateLimitError,
+)
+from publicsgdata.datagovsg.async_client import AsyncDataGovSGClient
+from publicsgdata.datagovsg.client import DataGovSGClient
+
+__all__ = [
+    "APIError",
+    "AsyncDataGovSGClient",
+    "AuthenticationError",
+    "DataGovSGClient",
+    "NotFoundError",
+    "PublicSGDataError",
+    "RateLimitError",
+]
+
+__version__ = "0.1.0"

publicsgdata/_base_client.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Literal, cast
+
+import httpx
+
+from publicsgdata._constants import DEFAULT_TIMEOUT, HEADER_API_KEY
+from publicsgdata._exceptions import (
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+)
+
+
+class BaseHTTPClient:
+    """Shared HTTP helpers for sync and async clients."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = 0,
+    ) -> None:
+        self._api_key = api_key
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._owns_client = False
+
+    def _auth_headers(self) -> dict[str, str]:
+        if self._api_key:
+            return {HEADER_API_KEY: self._api_key}
+        return {}
+
+    def _merge_headers(self, headers: Mapping[str, str] | None = None) -> dict[str, str]:
+        merged = dict(self._auth_headers())
+        if headers:
+            merged.update(headers)
+        return merged
+
+    def _parse_json(self, response: httpx.Response) -> Any:
+        if not response.content:
+            return None
+        return response.json()
+
+    def _raise_for_response(
+        self,
+        response: httpx.Response,
+        *,
+        payload: Any | None = None,
+    ) -> None:
+        if response.is_success:
+            if isinstance(payload, dict):
+                code = payload.get("code")
+                if code not in (None, 0) and payload.get("success") is not True:
+                    self._raise_api_payload(response, payload)
+            return
+
+        data = payload if payload is not None else self._parse_json(response)
+        if response.status_code == 429:
+            raise RateLimitError(
+                _error_message(data, response),
+                status_code=429,
+                code=_error_code(data),
+                name=_error_name(data),
+                body=data,
+            )
+        if response.status_code in (401, 403):
+            raise AuthenticationError(
+                _error_message(data, response),
+                status_code=response.status_code,
+                code=_error_code(data),
+                name=_error_name(data),
+                body=data,
+            )
+        if response.status_code == 404:
+            raise NotFoundError(
+                _error_message(data, response),
+                status_code=404,
+                code=_error_code(data),
+                name=_error_name(data),
+                body=data,
+            )
+        raise APIError(
+            _error_message(data, response),
+            status_code=response.status_code,
+            code=_error_code(data),
+            name=_error_name(data),
+            body=data,
+        )
+
+    def _raise_api_payload(self, response: httpx.Response, payload: dict[str, Any]) -> None:
+        message = _error_message(payload, response)
+        code = _error_code(payload)
+        name = _error_name(payload)
+        if response.status_code == 429 or code == 429:
+            raise RateLimitError(message, status_code=429, code=code, name=name, body=payload)
+        if name and "NOT_FOUND" in name.upper():
+            raise NotFoundError(message, status_code=404, code=code, name=name, body=payload)
+        raise APIError(
+            message,
+            status_code=response.status_code,
+            code=code,
+            name=name,
+            body=payload,
+        )
+
+
+def _error_message(data: Any, response: httpx.Response) -> str:
+    if isinstance(data, dict):
+        for key in ("errorMsg", "message", "error"):
+            value = data.get(key)
+            if isinstance(value, str) and value:
+                return value
+            if isinstance(value, dict):
+                return str(value)
+        if data.get("success") is False and isinstance(data.get("error"), dict):
+            return str(data["error"])
+    return f"HTTP {response.status_code} error for {response.request.url}"
+
+
+def _error_code(data: Any) -> int | str | None:
+    if isinstance(data, dict) and "code" in data:
+        return cast(int | str | None, data.get("code"))
+    return None
+
+
+def _error_name(data: Any) -> str | None:
+    if isinstance(data, dict) and isinstance(data.get("name"), str):
+        return cast(str, data["name"])
+    return None
+
+
+SyncHTTPClient = httpx.Client
+AsyncHTTPClient = httpx.AsyncClient
+HTTPMethod = Literal["GET", "POST", "PUT", "PATCH", "DELETE"]

publicsgdata/_constants.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import os
+
+ENV_API_KEY = "DATA_GOV_SG_API_KEY"
+HEADER_API_KEY = "x-api-key"
+
+DEFAULT_TIMEOUT = 30.0
+
+# data.gov.sg hosts
+CATALOG_BASE_URL = "https://api-production.data.gov.sg/v2/public/api"
+CKAN_BASE_URL = "https://data.gov.sg"
+REALTIME_BASE_URL = "https://api-open.data.gov.sg/v2/real-time/api"
+
+
+def default_api_key() -> str | None:
+    return os.environ.get(ENV_API_KEY)

publicsgdata/_exceptions.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class PublicSGDataError(Exception):
+    """Base exception for publicsgdata."""
+
+
+class APIError(PublicSGDataError):
+    """Raised when the API returns an error response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        code: int | str | None = None,
+        name: str | None = None,
+        body: Any | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.name = name
+        self.body = body
+
+
+class RateLimitError(APIError):
+    """Raised when rate limits are exceeded (HTTP 429)."""
+
+
+class AuthenticationError(APIError):
+    """Raised when authentication fails (HTTP 401/403)."""
+
+
+class NotFoundError(APIError):
+    """Raised when a resource is not found (HTTP 404)."""

publicsgdata/_pagination.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator
+from typing import Any, Generic, TypeVar
+
+from publicsgdata.datagovsg.models.common import DatasetRow
+
+T = TypeVar("T")
+
+
+class SyncPageIterator(Generic[T]):
+    """Iterate paginated API results synchronously."""
+
+    def __init__(
+        self,
+        fetch_page: Any,
+        *,
+        get_items: Any,
+        get_next_cursor: Any,
+    ) -> None:
+        self._fetch_page = fetch_page
+        self._get_items = get_items
+        self._get_next_cursor = get_next_cursor
+        self._cursor: str | None = None
+        self._buffer: list[T] = []
+        self._index = 0
+        self._exhausted = False
+
+    def __iter__(self) -> Iterator[T]:
+        return self
+
+    def __next__(self) -> T:
+        if self._index >= len(self._buffer):
+            if self._exhausted:
+                raise StopIteration
+            response = self._fetch_page(self._cursor)
+            self._buffer = list(self._get_items(response))
+            self._index = 0
+            self._cursor = self._get_next_cursor(response)
+            if not self._buffer:
+                self._exhausted = True
+                raise StopIteration
+            if self._cursor is None:
+                self._exhausted = True
+        item = self._buffer[self._index]
+        self._index += 1
+        return item
+
+
+class AsyncPageIterator(Generic[T]):
+    """Iterate paginated API results asynchronously."""
+
+    def __init__(
+        self,
+        fetch_page: Any,
+        *,
+        get_items: Any,
+        get_next_cursor: Any,
+    ) -> None:
+        self._fetch_page = fetch_page
+        self._get_items = get_items
+        self._get_next_cursor = get_next_cursor
+        self._cursor: str | None = None
+        self._buffer: list[T] = []
+        self._index = 0
+        self._exhausted = False
+
+    def __aiter__(self) -> AsyncIterator[T]:
+        return self
+
+    async def __anext__(self) -> T:
+        if self._index >= len(self._buffer):
+            if self._exhausted:
+                raise StopAsyncIteration
+            response = await self._fetch_page(self._cursor)
+            self._buffer = list(self._get_items(response))
+            self._index = 0
+            self._cursor = self._get_next_cursor(response)
+            if not self._buffer:
+                self._exhausted = True
+                raise StopAsyncIteration
+            if self._cursor is None:
+                self._exhausted = True
+        item = self._buffer[self._index]
+        self._index += 1
+        return item
+
+
+def parse_cursor_from_next_link(next_link: str | None) -> str | None:
+    """Extract cursor query string from v2 list-rows next link."""
+    if not next_link:
+        return None
+    return next_link
+
+
+def offset_from_ckan_link(next_link: str | None, *, base_path: str) -> int | None:
+    """Parse offset from CKAN _links.next relative URL."""
+    if not next_link:
+        return None
+    from urllib.parse import parse_qs, urlparse
+
+    parsed = urlparse(next_link if "://" in next_link else f"{base_path}{next_link}")
+    values = parse_qs(parsed.query).get("offset")
+    if not values:
+        return None
+    return int(values[0])
+
+
+class CkanSearchIterator(SyncPageIterator[DatasetRow]):
+    """Sync iterator for CKAN datastore_search offset pagination."""
+
+    def __init__(
+        self,
+        fetch_page: Any,
+        *,
+        initial_offset: int = 0,
+    ) -> None:
+        super().__init__(
+            lambda cursor: fetch_page(int(cursor) if cursor is not None else initial_offset),
+            get_items=lambda response: response.records,
+            get_next_cursor=lambda response: (
+                str(response.offset + len(response.records))
+                if response.links.next is not None and len(response.records) > 0
+                else None
+            ),
+        )
+        if initial_offset:
+            self._cursor = str(initial_offset)
+
+
+class AsyncCkanSearchIterator(AsyncPageIterator[DatasetRow]):
+    """Async iterator for CKAN datastore_search offset pagination."""
+
+    def __init__(
+        self,
+        fetch_page: Any,
+        *,
+        initial_offset: int = 0,
+    ) -> None:
+        super().__init__(
+            lambda cursor: fetch_page(int(cursor) if cursor is not None else initial_offset),
+            get_items=lambda response: response.records,
+            get_next_cursor=lambda response: (
+                str(response.offset + len(response.records))
+                if response.links.next is not None and len(response.records) > 0
+                else None
+            ),
+        )
+        if initial_offset:
+            self._cursor = str(initial_offset)

publicsgdata/datagovsg/__init__.py

@@ -0,0 +1,6 @@
+"""data.gov.sg API client."""
+
+from publicsgdata.datagovsg.async_client import AsyncDataGovSGClient
+from publicsgdata.datagovsg.client import DataGovSGClient
+
+__all__ = ["AsyncDataGovSGClient", "DataGovSGClient"]

publicsgdata/datagovsg/_request.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from enum import Enum
+from typing import Any
+from urllib.parse import urljoin
+
+from publicsgdata._base_client import BaseHTTPClient
+from publicsgdata._constants import CATALOG_BASE_URL, CKAN_BASE_URL, REALTIME_BASE_URL
+
+
+class DataGovSGHost(str, Enum):
+    CATALOG = "catalog"
+    CKAN = "ckan"
+    REALTIME = "realtime"
+
+
+class DataGovSGRequestMixin(BaseHTTPClient):
+    """HTTP request helpers routed to data.gov.sg hosts."""
+
+    def _base_url(self, host: DataGovSGHost) -> str:
+        if host is DataGovSGHost.CATALOG:
+            return CATALOG_BASE_URL
+        if host is DataGovSGHost.CKAN:
+            return CKAN_BASE_URL
+        return REALTIME_BASE_URL
+
+    def _build_url(self, host: DataGovSGHost, path: str) -> str:
+        base = self._base_url(host)
+        if not path.startswith("/"):
+            path = f"/{path}"
+        return urljoin(f"{base}/", path.lstrip("/"))
+
+    def _catalog_data(self, payload: dict[str, Any]) -> dict[str, Any]:
+        data = payload.get("data")
+        if isinstance(data, dict):
+            return data
+        return payload
+
+    def _realtime_data(self, payload: dict[str, Any]) -> dict[str, Any]:
+        data = payload.get("data")
+        if isinstance(data, dict):
+            return data
+        return payload
+
+    @staticmethod
+    def _cursor_params(cursor: str | None, *, limit: int | None = None) -> dict[str, str]:
+        params: dict[str, str] = {}
+        if limit is not None:
+            params["limit"] = str(limit)
+        if cursor:
+            for part in cursor.split("&"):
+                if "=" in part:
+                    key, value = part.split("=", 1)
+                    params[key] = value
+        return params
+
+    @staticmethod
+    def _encode_query(params: Mapping[str, Any]) -> dict[str, str]:
+        encoded: dict[str, str] = {}
+        for key, value in params.items():
+            if value is None:
+                continue
+            encoded[key] = str(value)
+        return encoded

publicsgdata/datagovsg/async_client.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from publicsgdata._constants import DEFAULT_TIMEOUT, default_api_key
+from publicsgdata.datagovsg._request import DataGovSGHost, DataGovSGRequestMixin
+from publicsgdata.datagovsg.resources.collections import AsyncCollectionsResource
+from publicsgdata.datagovsg.resources.datasets import AsyncDatasetsResource
+from publicsgdata.datagovsg.resources.realtime import AsyncRealtimeResource
+
+
+class AsyncDataGovSGClient(DataGovSGRequestMixin):
+    """Async client for data.gov.sg APIs."""
+
+    _http_client: httpx.AsyncClient
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        http_client: httpx.AsyncClient | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = 0,
+    ) -> None:
+        super().__init__(
+            api_key=api_key or default_api_key(), timeout=timeout, max_retries=max_retries
+        )
+        if http_client is not None:
+            self._http_client = http_client
+            self._owns_client = False
+        else:
+            self._http_client = httpx.AsyncClient(timeout=timeout)
+            self._owns_client = True
+
+        self.collections = AsyncCollectionsResource(self)
+        self.datasets = AsyncDatasetsResource(self)
+        self.realtime = AsyncRealtimeResource(self)
+
+    async def __aenter__(self) -> AsyncDataGovSGClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._http_client.aclose()
+
+    async def _request_json(
+        self,
+        method: str,
+        host: DataGovSGHost,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        url = self._build_url(host, path)
+        encoded = self._encode_query(params) if params else None
+        response = await self._http_client.request(
+            method,
+            url,
+            params=encoded,
+            headers=self._merge_headers(),
+        )
+        payload = self._parse_json(response)
+        if not isinstance(payload, dict):
+            self._raise_for_response(response, payload=payload)
+            return {}
+        self._raise_for_response(response, payload=payload)
+        return payload

publicsgdata/datagovsg/client.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from publicsgdata._constants import DEFAULT_TIMEOUT, default_api_key
+from publicsgdata.datagovsg._request import DataGovSGHost, DataGovSGRequestMixin
+from publicsgdata.datagovsg.resources.collections import CollectionsResource
+from publicsgdata.datagovsg.resources.datasets import DatasetsResource
+from publicsgdata.datagovsg.resources.realtime import RealtimeResource
+
+
+class DataGovSGClient(DataGovSGRequestMixin):
+    """Sync client for data.gov.sg APIs."""
+
+    _http_client: httpx.Client
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        http_client: httpx.Client | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = 0,
+    ) -> None:
+        super().__init__(
+            api_key=api_key or default_api_key(), timeout=timeout, max_retries=max_retries
+        )
+        if http_client is not None:
+            self._http_client = http_client
+            self._owns_client = False
+        else:
+            self._http_client = httpx.Client(timeout=timeout)
+            self._owns_client = True
+
+        self.collections = CollectionsResource(self)
+        self.datasets = DatasetsResource(self)
+        self.realtime = RealtimeResource(self)
+
+    def __enter__(self) -> DataGovSGClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http_client.close()
+
+    def _request_json(
+        self,
+        method: str,
+        host: DataGovSGHost,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        url = self._build_url(host, path)
+        encoded = self._encode_query(params) if params else None
+        response = self._http_client.request(
+            method,
+            url,
+            params=encoded,
+            headers=self._merge_headers(),
+        )
+        payload = self._parse_json(response)
+        if not isinstance(payload, dict):
+            self._raise_for_response(response, payload=payload)
+            return {}
+        self._raise_for_response(response, payload=payload)
+        return payload

publicsgdata/datagovsg/models/__init__.py

@@ -0,0 +1,29 @@
+from publicsgdata.datagovsg.models.common import (
+    CollectionListResponse,
+    CollectionMetadata,
+    CollectionMetadataResponse,
+    CollectionSummary,
+    DatasetListResponse,
+    DatasetMetadata,
+    DatasetMetadataResponse,
+    DatasetRow,
+    DatasetRowsResponse,
+    DatasetSummary,
+    DatastoreSearchResult,
+    PM25Response,
+)
+
+__all__ = [
+    "CollectionListResponse",
+    "CollectionMetadata",
+    "CollectionMetadataResponse",
+    "CollectionSummary",
+    "DatasetListResponse",
+    "DatasetMetadata",
+    "DatasetMetadataResponse",
+    "DatasetRow",
+    "DatasetRowsResponse",
+    "DatasetSummary",
+    "DatastoreSearchResult",
+    "PM25Response",
+]

publicsgdata/datagovsg/models/common.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ApiModel(BaseModel):
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+class PaginationLinks(ApiModel):
+    next: str | None = None
+    start: str | None = None
+
+
+class DatasetRow(ApiModel):
+    model_config = ConfigDict(extra="allow")
+
+
+class CollectionSummary(ApiModel):
+    collection_id: str = Field(alias="collectionId")
+    name: str
+    description: str | None = None
+    created_at: str | None = Field(default=None, alias="createdAt")
+    last_updated_at: str | None = Field(default=None, alias="lastUpdatedAt")
+    frequency: str | None = None
+    sources: list[str] | None = None
+    managed_by_agency_name: str | None = Field(default=None, alias="managedByAgencyName")
+    child_datasets: list[str] | None = Field(default=None, alias="childDatasets")
+
+
+class CollectionMetadata(ApiModel):
+    collection_id: str = Field(alias="collectionId")
+    name: str
+    description: str | None = None
+    created_at: str | None = Field(default=None, alias="createdAt")
+    last_updated_at: str | None = Field(default=None, alias="lastUpdatedAt")
+    frequency: str | None = None
+    sources: list[str] | None = None
+    managed_by: str | None = Field(default=None, alias="managedBy")
+    child_datasets: list[str] | None = Field(default=None, alias="childDatasets")
+
+
+class CollectionListResponse(ApiModel):
+    collections: list[CollectionSummary]
+
+
+class CollectionMetadataResponse(ApiModel):
+    collection_metadata: CollectionMetadata = Field(alias="collectionMetadata")
+
+
+class DatasetSummary(ApiModel):
+    dataset_id: str = Field(alias="datasetId")
+    name: str
+    status: str | None = None
+    description: str | None = None
+    format: str | None = None
+    created_at: str | None = Field(default=None, alias="createdAt")
+    last_updated_at: str | None = Field(default=None, alias="lastUpdatedAt")
+    managed_by_agency_name: str | None = Field(default=None, alias="managedByAgencyName")
+    coverage_start: str | None = Field(default=None, alias="coverageStart")
+    coverage_end: str | None = Field(default=None, alias="coverageEnd")
+
+
+class DatasetListResponse(ApiModel):
+    datasets: list[DatasetSummary]
+    pages: int | None = None
+
+
+class DatasetMetadata(ApiModel):
+    dataset_id: str = Field(alias="datasetId")
+    name: str
+    description: str | None = None
+    format: str | None = None
+    status: str | None = None
+    created_at: str | None = Field(default=None, alias="createdAt")
+    last_updated_at: str | None = Field(default=None, alias="lastUpdatedAt")
+    managed_by: str | None = Field(default=None, alias="managedBy")
+    collection_ids: list[str] | None = Field(default=None, alias="collectionIds")
+    coverage_start: str | None = Field(default=None, alias="coverageStart")
+    coverage_end: str | None = Field(default=None, alias="coverageEnd")
+    contact_emails: list[str] | None = Field(default=None, alias="contactEmails")
+    dataset_size: int | None = Field(default=None, alias="datasetSize")
+    column_metadata: dict[str, Any] | None = Field(default=None, alias="columnMetadata")
+
+
+class DatasetMetadataResponse(ApiModel):
+    dataset_metadata: DatasetMetadata | None = Field(default=None, alias="datasetMetadata")
+
+    @property
+    def metadata(self) -> DatasetMetadata:
+        if self.dataset_metadata is not None:
+            return self.dataset_metadata
+        raise ValueError("dataset metadata missing from response")
+
+
+class DatasetRowsResponse(ApiModel):
+    dataset_id: str = Field(alias="datasetId")
+    dataset_name: str | None = Field(default=None, alias="datasetName")
+    rows: list[DatasetRow]
+    limit: int
+    links: PaginationLinks | None = None
+
+
+class DatastoreField(ApiModel):
+    id: str
+    type: str | None = None
+
+
+class DatastoreSearchLinks(ApiModel):
+    start: str | None = None
+    next: str | None = None
+
+
+class DatastoreSearchResult(ApiModel):
+    resource_id: str
+    fields: list[DatastoreField]
+    records: list[DatasetRow]
+    total: int
+    limit: int
+    offset: int = 0
+    links: DatastoreSearchLinks = Field(default_factory=DatastoreSearchLinks)
+
+
+class PM25Reading(ApiModel):
+    date: str | None = None
+    updated_timestamp: str | None = Field(default=None, alias="updatedTimestamp")
+    timestamp: str | None = None
+    readings: dict[str, Any] | None = None
+
+
+class PM25RegionMetadata(ApiModel):
+    name: str
+    label_location: dict[str, float] | None = Field(default=None, alias="labelLocation")
+
+
+class PM25Response(ApiModel):
+    region_metadata: list[PM25RegionMetadata] = Field(default_factory=list, alias="regionMetadata")
+    items: list[PM25Reading] = Field(default_factory=list)
+    pagination_token: str | None = Field(default=None, alias="paginationToken")

publicsgdata/datagovsg/resources/collections.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from publicsgdata.datagovsg._request import DataGovSGHost
+from publicsgdata.datagovsg.models import (
+    CollectionListResponse,
+    CollectionMetadata,
+    CollectionMetadataResponse,
+)
+
+if TYPE_CHECKING:
+    from publicsgdata.datagovsg.client import DataGovSGClient
+
+
+class CollectionsResource:
+    def __init__(self, client: DataGovSGClient) -> None:
+        self._client = client
+
+    def list(self) -> CollectionListResponse:
+        payload = self._client._request_json("GET", DataGovSGHost.CATALOG, "/collections")
+        return CollectionListResponse.model_validate(self._client._catalog_data(payload))
+
+    def get_metadata(self, collection_id: str) -> CollectionMetadata:
+        path = f"/collections/{collection_id}/metadata"
+        payload = self._client._request_json("GET", DataGovSGHost.CATALOG, path)
+        response = CollectionMetadataResponse.model_validate(self._client._catalog_data(payload))
+        return response.collection_metadata
+
+
+class AsyncCollectionsResource:
+    def __init__(self, client: object) -> None:
+        self._client = client
+
+    async def list(self) -> CollectionListResponse:
+        payload = await self._client._request_json("GET", DataGovSGHost.CATALOG, "/collections")  # type: ignore[attr-defined]
+        return CollectionListResponse.model_validate(self._client._catalog_data(payload))  # type: ignore[attr-defined]
+
+    async def get_metadata(self, collection_id: str) -> CollectionMetadata:
+        path = f"/collections/{collection_id}/metadata"
+        payload = await self._client._request_json("GET", DataGovSGHost.CATALOG, path)  # type: ignore[attr-defined]
+        response = CollectionMetadataResponse.model_validate(self._client._catalog_data(payload))  # type: ignore[attr-defined]
+        return response.collection_metadata

publicsgdata/datagovsg/resources/datasets.py

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator, Iterator, Mapping
+from typing import TYPE_CHECKING, Any
+
+from publicsgdata._pagination import AsyncCkanSearchIterator, CkanSearchIterator, SyncPageIterator
+from publicsgdata.datagovsg._request import DataGovSGHost
+from publicsgdata.datagovsg.models import (
+    DatasetListResponse,
+    DatasetMetadata,
+    DatasetRow,
+    DatasetRowsResponse,
+    DatastoreSearchResult,
+)
+
+if TYPE_CHECKING:
+    from publicsgdata.datagovsg.async_client import AsyncDataGovSGClient
+    from publicsgdata.datagovsg.client import DataGovSGClient
+
+
+class DatasetsResource:
+    def __init__(self, client: DataGovSGClient) -> None:
+        self._client = client
+
+    def list(self, *, page: int | None = None) -> DatasetListResponse:
+        params = {"page": page} if page is not None else None
+        payload = self._client._request_json(
+            "GET", DataGovSGHost.CATALOG, "/datasets", params=params
+        )
+        return DatasetListResponse.model_validate(self._client._catalog_data(payload))
+
+    def get_metadata(self, dataset_id: str) -> DatasetMetadata:
+        path = f"/datasets/{dataset_id}/metadata"
+        payload = self._client._request_json("GET", DataGovSGHost.CATALOG, path)
+        return DatasetMetadata.model_validate(self._client._catalog_data(payload))
+
+    def list_rows(
+        self,
+        dataset_id: str,
+        *,
+        limit: int = 100,
+        cursor: str | None = None,
+    ) -> DatasetRowsResponse:
+        path = f"/datasets/{dataset_id}/list-rows"
+        params = self._client._cursor_params(cursor, limit=limit)
+        payload = self._client._request_json("GET", DataGovSGHost.CATALOG, path, params=params)
+        return DatasetRowsResponse.model_validate(self._client._catalog_data(payload))
+
+    def iter_rows(
+        self,
+        dataset_id: str,
+        *,
+        limit: int = 100,
+        cursor: str | None = None,
+    ) -> Iterator[DatasetRow]:
+        iterator: SyncPageIterator[DatasetRow] = SyncPageIterator(
+            lambda next_cursor: self.list_rows(dataset_id, limit=limit, cursor=next_cursor),
+            get_items=lambda response: response.rows,
+            get_next_cursor=lambda response: (
+                response.links.next if response.links is not None else None
+            ),
+        )
+        iterator._cursor = cursor
+        return iterator
+
+    def search(
+        self,
+        resource_id: str,
+        *,
+        limit: int = 100,
+        offset: int = 0,
+        filters: Mapping[str, Any] | None = None,
+        q: str | Mapping[str, Any] | None = None,
+        sort: str | None = None,
+        fields: str | None = None,
+    ) -> DatastoreSearchResult:
+        params: dict[str, Any] = {
+            "resource_id": resource_id,
+            "limit": limit,
+            "offset": offset,
+        }
+        if filters is not None:
+            params["filters"] = json.dumps(filters)
+        if q is not None:
+            params["q"] = json.dumps(q) if isinstance(q, Mapping) else q
+        if sort is not None:
+            params["sort"] = sort
+        if fields is not None:
+            params["fields"] = fields
+
+        payload = self._client._request_json(
+            "GET",
+            DataGovSGHost.CKAN,
+            "/api/action/datastore_search",
+            params=params,
+        )
+        result = payload.get("result", payload)
+        records = result.get("records", [])
+        return DatastoreSearchResult(
+            resource_id=result.get("resource_id", resource_id),
+            fields=result.get("fields", []),
+            records=records,
+            total=result.get("total", len(records)),
+            limit=result.get("limit", limit),
+            offset=offset,
+            links=result.get("_links", {}),
+        )
+
+    def iter_search(
+        self,
+        resource_id: str,
+        *,
+        limit: int = 100,
+        offset: int = 0,
+        filters: Mapping[str, Any] | None = None,
+        q: str | Mapping[str, Any] | None = None,
+        sort: str | None = None,
+    ) -> Iterator[DatasetRow]:
+        def fetch_page(page_offset: int) -> DatastoreSearchResult:
+            return self.search(
+                resource_id,
+                limit=limit,
+                offset=page_offset,
+                filters=filters,
+                q=q,
+                sort=sort,
+            )
+
+        return CkanSearchIterator(fetch_page, initial_offset=offset)
+
+
+class AsyncDatasetsResource:
+    def __init__(self, client: AsyncDataGovSGClient) -> None:
+        self._client = client
+
+    async def list(self, *, page: int | None = None) -> DatasetListResponse:
+        params = {"page": page} if page is not None else None
+        payload = await self._client._request_json(
+            "GET", DataGovSGHost.CATALOG, "/datasets", params=params
+        )
+        return DatasetListResponse.model_validate(self._client._catalog_data(payload))
+
+    async def get_metadata(self, dataset_id: str) -> DatasetMetadata:
+        path = f"/datasets/{dataset_id}/metadata"
+        payload = await self._client._request_json("GET", DataGovSGHost.CATALOG, path)
+        return DatasetMetadata.model_validate(self._client._catalog_data(payload))
+
+    async def list_rows(
+        self,
+        dataset_id: str,
+        *,
+        limit: int = 100,
+        cursor: str | None = None,
+    ) -> DatasetRowsResponse:
+        path = f"/datasets/{dataset_id}/list-rows"
+        params = self._client._cursor_params(cursor, limit=limit)
+        payload = await self._client._request_json(
+            "GET", DataGovSGHost.CATALOG, path, params=params
+        )
+        return DatasetRowsResponse.model_validate(self._client._catalog_data(payload))
+
+    async def iter_rows(
+        self,
+        dataset_id: str,
+        *,
+        limit: int = 100,
+        cursor: str | None = None,
+    ) -> AsyncIterator[DatasetRow]:
+        from publicsgdata._pagination import AsyncPageIterator
+
+        iterator: AsyncPageIterator[DatasetRow] = AsyncPageIterator(
+            lambda next_cursor: self.list_rows(dataset_id, limit=limit, cursor=next_cursor),
+            get_items=lambda response: response.rows,
+            get_next_cursor=lambda response: (
+                response.links.next if response.links is not None else None
+            ),
+        )
+        iterator._cursor = cursor
+        async for row in iterator:
+            yield row
+
+    async def search(
+        self,
+        resource_id: str,
+        *,
+        limit: int = 100,
+        offset: int = 0,
+        filters: Mapping[str, Any] | None = None,
+        q: str | Mapping[str, Any] | None = None,
+        sort: str | None = None,
+        fields: str | None = None,
+    ) -> DatastoreSearchResult:
+        params: dict[str, Any] = {
+            "resource_id": resource_id,
+            "limit": limit,
+            "offset": offset,
+        }
+        if filters is not None:
+            params["filters"] = json.dumps(filters)
+        if q is not None:
+            params["q"] = json.dumps(q) if isinstance(q, Mapping) else q
+        if sort is not None:
+            params["sort"] = sort
+        if fields is not None:
+            params["fields"] = fields
+
+        payload = await self._client._request_json(
+            "GET",
+            DataGovSGHost.CKAN,
+            "/api/action/datastore_search",
+            params=params,
+        )
+        result = payload.get("result", payload)
+        records = result.get("records", [])
+        return DatastoreSearchResult(
+            resource_id=result.get("resource_id", resource_id),
+            fields=result.get("fields", []),
+            records=records,
+            total=result.get("total", len(records)),
+            limit=result.get("limit", limit),
+            offset=offset,
+            links=result.get("_links", {}),
+        )
+
+    async def iter_search(
+        self,
+        resource_id: str,
+        *,
+        limit: int = 100,
+        offset: int = 0,
+        filters: Mapping[str, Any] | None = None,
+        q: str | Mapping[str, Any] | None = None,
+        sort: str | None = None,
+    ) -> AsyncIterator[DatasetRow]:
+        iterator = AsyncCkanSearchIterator(
+            lambda page_offset: self.search(
+                resource_id,
+                limit=limit,
+                offset=page_offset,
+                filters=filters,
+                q=q,
+                sort=sort,
+            ),
+            initial_offset=offset,
+        )
+        async for row in iterator:
+            yield row

publicsgdata/datagovsg/resources/realtime/__init__.py

@@ -0,0 +1,11 @@
+from publicsgdata.datagovsg.resources.realtime.pm25 import AsyncPM25Resource, PM25Resource
+
+
+class RealtimeResource:
+    def __init__(self, client: object) -> None:
+        self.pm25 = PM25Resource(client)  # type: ignore[arg-type]
+
+
+class AsyncRealtimeResource:
+    def __init__(self, client: object) -> None:
+        self.pm25 = AsyncPM25Resource(client)  # type: ignore[arg-type]

publicsgdata/datagovsg/resources/realtime/pm25.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from publicsgdata.datagovsg._request import DataGovSGHost
+from publicsgdata.datagovsg.models import PM25Response
+
+if TYPE_CHECKING:
+    from publicsgdata.datagovsg.async_client import AsyncDataGovSGClient
+    from publicsgdata.datagovsg.client import DataGovSGClient
+
+
+class PM25Resource:
+    def __init__(self, client: DataGovSGClient) -> None:
+        self._client = client
+
+    def get(
+        self,
+        *,
+        date: str | None = None,
+        pagination_token: str | None = None,
+    ) -> PM25Response:
+        params: dict[str, str] = {}
+        if date is not None:
+            params["date"] = date
+        if pagination_token is not None:
+            params["paginationToken"] = pagination_token
+        payload = self._client._request_json(
+            "GET",
+            DataGovSGHost.REALTIME,
+            "/pm25",
+            params=params or None,
+        )
+        return PM25Response.model_validate(self._client._realtime_data(payload))
+
+
+class AsyncPM25Resource:
+    def __init__(self, client: AsyncDataGovSGClient) -> None:
+        self._client = client
+
+    async def get(
+        self,
+        *,
+        date: str | None = None,
+        pagination_token: str | None = None,
+    ) -> PM25Response:
+        params: dict[str, str] = {}
+        if date is not None:
+            params["date"] = date
+        if pagination_token is not None:
+            params["paginationToken"] = pagination_token
+        payload = await self._client._request_json(
+            "GET",
+            DataGovSGHost.REALTIME,
+            "/pm25",
+            params=params or None,
+        )
+        return PM25Response.model_validate(self._client._realtime_data(payload))

publicsgdata-0.1.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: publicsgdata
+Version: 0.1.0
+Summary: Python client for Singapore government open data (data.gov.sg, LTA, OneMap)
+Project-URL: Homepage, https://github.com/publicsgdata/publicsgdata
+Project-URL: Repository, https://github.com/publicsgdata/publicsgdata
+Project-URL: Documentation, https://github.com/publicsgdata/publicsgdata#readme
+Project-URL: Issues, https://github.com/publicsgdata/publicsgdata/issues
+Author: publicsgdata contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,data.gov.sg,open-data,sdk,singapore
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27.0
+Requires-Dist: pydantic<3,>=2.0
+Requires-Dist: typing-extensions<5,>=4.8
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# publicsgdata
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Python client for Singapore government open data: data.gov.sg today, LTA and OneMap later.
+
+## Install
+
+Requires [uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+```bash
+uv pip install publicsgdata
+```
+
+## Quickstart
+
+```python
+from publicsgdata import DataGovSGClient
+
+with DataGovSGClient() as client:  # optional: api_key="..." or DATA_GOV_SG_API_KEY
+    catalog = client.collections.list()
+    print(f"{len(catalog.collections)} collections")
+    print(catalog.collections[0].name)
+
+    # HDB resale prices (swap in any dataset ID)
+    rows = client.datasets.list_rows("d_8b84c4ee58e3cfc0ece0d773c8ca6abc", limit=10)
+    for row in rows.rows:
+        print(row.model_dump())
+
+    pm25 = client.realtime.pm25.get()
+    print(pm25.items[0].readings)
+```
+
+### Async
+
+```python
+from publicsgdata import AsyncDataGovSGClient
+
+async with AsyncDataGovSGClient() as client:
+    rows = await client.datasets.list_rows("d_8b84c4ee58e3cfc0ece0d773c8ca6abc", limit=5)
+    print(len(rows.rows))
+```
+
+### Custom HTTP client
+
+Pass your own `httpx` client if you need custom timeouts, proxies, etc.
+
+```python
+import httpx
+from publicsgdata import DataGovSGClient
+
+with httpx.Client(timeout=30.0) as http:
+    client = DataGovSGClient(http_client=http)
+    print(len(client.collections.list().collections))
+```
+
+## Authentication
+
+You can call the API without a key while experimenting. For regular use, get a key from [data.gov.sg](https://data.gov.sg/) and set:
+
+```bash
+export DATA_GOV_SG_API_KEY="your-key"
+```
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `DATA_GOV_SG_API_KEY` | No | data.gov.sg API key (`x-api-key` header) |
+
+## Development
+
+You'll need [uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+```bash
+./scripts/dev_setup.sh         # creates .venv from uv.lock
+./scripts/format.sh
+./scripts/validate.sh
+./scripts/test.sh              # unit tests, runs in CI
+./scripts/test_integration.sh  # hits the real API, local only
+```
+
+Or run things directly: `uv run pytest`, `uv run ruff check .`, etc.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) if you're opening a PR.
+
+## Roadmap
+
+- **v0.1.0**: `DataGovSGClient`
+- **v0.2.0**: `LTAClient` (LTA DataMall)
+- **v0.3.0**: `OneMapClient`
+
+## License
+
+MIT. See [LICENSE](LICENSE).

publicsgdata-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+publicsgdata/__init__.py,sha256=kHOfMJK12wYtUePZFhP9_92TsI-LRLPfQ63wGxTonBE,542
+publicsgdata/_base_client.py,sha256=X1Yt2To2c6BsYJ6IsuCtnyF_E2tak7G5pp_7aY5Gqbg,4461
+publicsgdata/_constants.py,sha256=wO3st5DA3qEUA-F-ZnUVRS_SkH9mbRKuQWmHPMj10tU,411
+publicsgdata/_exceptions.py,sha256=9hijaCArdQf9_kQif0qAVzDatIW-1GemSZzZw8ch4c8,890
+publicsgdata/_pagination.py,sha256=TStPrqGU6vt3OnAc1HZgTdLSQoxaWF8HyvZp9dy6IiY,4668
+publicsgdata/datagovsg/__init__.py,sha256=DUckqefYi2A1yMVT6MpwoQgS3yYwoyZpDkjs7cScXXY,213
+publicsgdata/datagovsg/_request.py,sha256=ZXgf0jdPOUZZuIdkWfxAb6vgNsuKWV3p3eXqUtoqS0Q,2047
+publicsgdata/datagovsg/async_client.py,sha256=GhHJvDwLC01MNMnTWfPwTZ-Cerej2K8Fz1YCo0ExORg,2377
+publicsgdata/datagovsg/client.py,sha256=r9H7Kmw4WQyQVumTpQe5GF300MsuS7LR5jF7NwOx_9w,2276
+publicsgdata/datagovsg/models/__init__.py,sha256=sAyhoD5UzMfFElfUB4Ug8ZCbxsKJ1kM2AIbyXEtul2U,668
+publicsgdata/datagovsg/models/common.py,sha256=H1IU2AJLOveVHDq5HpgOPRCjplQdEcRRD9u9i_JTLRk,4808
+publicsgdata/datagovsg/resources/collections.py,sha256=WQYYwP3xaIJEh9VD1hGGxCWovR_PPVV0rIVo8SRXHck,1867
+publicsgdata/datagovsg/resources/datasets.py,sha256=uIRdAsf4lX5KMI7rpqwJeTPKx-06EkuQ-0FHg5Gs0Ag,8505
+publicsgdata/datagovsg/resources/realtime/__init__.py,sha256=ih0Qlw4FBLQ_DlFEPcziWKbLrRZYr6b8rW0PhX5htx4,383
+publicsgdata/datagovsg/resources/realtime/pm25.py,sha256=MORU5kFFMBowYhPp9SHzj2TL4iPdqP_0AMlpAr0hOjo,1747
+publicsgdata-0.1.0.dist-info/METADATA,sha256=KIewjVREndffBI3lx8YAd8bnjwmpFWnoEFrtP03ZdCk,3894
+publicsgdata-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+publicsgdata-0.1.0.dist-info/licenses/LICENSE,sha256=dGDq1NgMiTjZ7uCBQxhaCI22b_iq-mx12z2RdZ0mHvc,1062
+publicsgdata-0.1.0.dist-info/RECORD,,

publicsgdata-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

publicsgdata-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harry
+
+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.