publicsgdata 0.1.0__tar.gz

publicsgdata-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+env/
+dist/
+build/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+*.log
+.DS_Store
+.idea/
+.vscode/

publicsgdata-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-09
+
+### Added
+
+- `DataGovSGClient` and `AsyncDataGovSGClient`: sync and async, with optional custom `httpx` clients
+- `collections.list()` and `collections.get_metadata()`
+- `datasets.list()`, `get_metadata()`, `list_rows()`, `iter_rows()`, and CKAN `search()`
+- `realtime.pm25.get()` for PM2.5 readings
+- Pydantic v2 response models
+- Optional `DATA_GOV_SG_API_KEY` auth via `x-api-key` header
+- CI, release-please, and PyPI publish workflows
+
+[0.1.0]: https://github.com/publicsgdata/publicsgdata/releases/tag/v0.1.0

publicsgdata-0.1.0/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.

publicsgdata-0.1.0/PKG-INFO

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

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

@@ -0,0 +1,104 @@
+[project]
+name = "publicsgdata"
+version = "0.1.0"
+description = "Python client for Singapore government open data (data.gov.sg, LTA, OneMap)"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "publicsgdata contributors" }]
+keywords = ["singapore", "open-data", "data.gov.sg", "api", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.27.0,<1",
+    "pydantic>=2.0,<3",
+    "typing-extensions>=4.8,<5",
+]
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.0",
+    "mypy>=1.8",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5.0",
+    "ruff>=0.8",
+]
+
+[dependency-groups]
+dev = [
+    "build>=1.0",
+    "mypy>=1.8",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5.0",
+    "ruff>=0.8",
+]
+
+[tool.uv]
+default-groups = ["dev"]
+
+[project.urls]
+Homepage = "https://github.com/publicsgdata/publicsgdata"
+Repository = "https://github.com/publicsgdata/publicsgdata"
+Documentation = "https://github.com/publicsgdata/publicsgdata#readme"
+Issues = "https://github.com/publicsgdata/publicsgdata/issues"
+
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/publicsgdata"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/README.md",
+    "/LICENSE",
+    "/CHANGELOG.md",
+    "/src/publicsgdata",
+    "/tests",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+markers = [
+    "integration: live data.gov.sg API tests (local only; use ./scripts/test_integration.sh)",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+packages = ["publicsgdata"]
+mypy_path = "src"
+files = ["src", "tests"]
+
+[[tool.mypy.overrides]]
+module = ["conftest", "test_datagovsg", "test_async_datagovsg", "test_integration_datagovsg"]
+disallow_untyped_defs = false
+
+[tool.coverage.run]
+source = ["publicsgdata"]
+branch = true

publicsgdata-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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)."""