chile-open-data-sdk 0.1.0__py3-none-any.whl

chile_open_data_sdk/__init__.py

@@ -0,0 +1,8 @@
+"""Unofficial Chile-first CKAN Action API SDK."""
+
+from chile_open_data_sdk.client import ChileOpenDataClient, CKANClient
+from chile_open_data_sdk.config import ClientConfig
+from chile_open_data_sdk.types import JSONValue
+
+__version__ = "0.1.0"
+__all__ = ["CKANClient", "ChileOpenDataClient", "ClientConfig", "JSONValue", "__version__"]

chile_open_data_sdk/_internal/__init__.py

@@ -0,0 +1 @@
+"""Private network-independent implementation helpers."""

chile_open_data_sdk/_internal/responses.py

@@ -0,0 +1,111 @@
+"""Parse CKAN envelopes and redact diagnostic payloads."""
+
+import json
+from typing import cast
+
+import httpx
+from pydantic import BaseModel, ConfigDict, JsonValue, StrictBool, ValidationError
+
+from chile_open_data_sdk.errors import (
+    CKANAPIError,
+    CKANAuthenticationError,
+    CKANAuthorizationError,
+    CKANError,
+    CKANHTTPError,
+    CKANNotFoundError,
+    CKANProtocolError,
+    CKANRateLimitError,
+    CKANValidationError,
+)
+from chile_open_data_sdk.types import JSONValue
+
+
+class ActionResponse(BaseModel):
+    """Internal envelope; extension metadata is tolerated."""
+
+    model_config = ConfigDict(extra="allow")
+    success: StrictBool
+    result: JsonValue = None
+    error: dict[str, JsonValue] | None = None
+
+
+def redact(value: JSONValue, token: str | None) -> JSONValue:
+    """Remove configured tokens and values of credential-like diagnostic keys."""
+    if isinstance(value, str):
+        return value.replace(token, "[REDACTED]") if token else value
+    if isinstance(value, list):
+        return [redact(item, token) for item in value]
+    if isinstance(value, dict):
+        return {
+            str(redact(key, token)): (
+                "[REDACTED]"
+                if any(
+                    part in key.lower()
+                    for part in (
+                        "token",
+                        "authorization",
+                        "password",
+                        "secret",
+                        "api_key",
+                        "apikey",
+                    )
+                )
+                else redact(item, token)
+            )
+            for key, item in value.items()
+        }
+    return value
+
+
+_STATUS_ERRORS: dict[int, type[CKANError]] = {
+    400: CKANValidationError,
+    401: CKANAuthenticationError,
+    403: CKANAuthorizationError,
+    404: CKANNotFoundError,
+    409: CKANValidationError,
+    422: CKANValidationError,
+    429: CKANRateLimitError,
+}
+_TYPE_ERRORS: dict[str, type[CKANError]] = {
+    "Authentication Error": CKANAuthenticationError,
+    "Authorization Error": CKANAuthorizationError,
+    "Not Found Error": CKANNotFoundError,
+    "Validation Error": CKANValidationError,
+}
+
+
+def parse_response(response: httpx.Response, action: str, token: str | None) -> JSONValue:
+    """Return only the result; convert HTTP, CKAN, and malformed response failures."""
+    envelope = None
+    try:
+        envelope = ActionResponse.model_validate_json(response.content)
+    except (ValidationError, ValueError):
+        pass
+    status = response.status_code
+    if not response.is_success or (envelope is not None and not envelope.success):
+        details = redact(cast(JSONValue, envelope.error), token) if envelope else None
+        error_type = details.get("__type") if isinstance(details, dict) else None
+        error_type = error_type if isinstance(error_type, str) else None
+        error_class = _STATUS_ERRORS.get(status)
+        if error_class is None:
+            error_class = _TYPE_ERRORS.get(error_type or "")
+        if error_class is None:
+            error_class = CKANHTTPError if not response.is_success else CKANAPIError
+        raise error_class(
+            "CKAN action failed",
+            action=action,
+            status_code=status,
+            error_type=error_type,
+            details=details,
+        )
+    if envelope is None or "result" not in envelope.model_fields_set:
+        raise CKANProtocolError("Invalid CKAN response envelope", action=action, status_code=status)
+    # The JSON parser must reject non-standard NaN/Infinity accepted by some decoders.
+    result: JSONValue = envelope.result
+    try:
+        json.dumps(result, allow_nan=False)
+    except ValueError:
+        raise CKANProtocolError(
+            "Non-finite JSON result", action=action, status_code=status
+        ) from None
+    return result

chile_open_data_sdk/client.py

@@ -0,0 +1,142 @@
+"""Synchronous CKAN clients and generic JSON Action API access."""
+
+import json
+import re
+from collections.abc import Mapping
+from types import TracebackType
+from typing import Self
+
+import httpx
+
+from chile_open_data_sdk._internal.responses import parse_response, redact
+from chile_open_data_sdk.config import ClientConfig
+from chile_open_data_sdk.errors import CKANConnectionError, CKANError, CKANTimeoutError
+from chile_open_data_sdk.types import JSONValue
+
+
+class ActionService:
+    """Generic CKAN JSON actions, with no automatic retries or redirects."""
+
+    def __init__(self, http: httpx.Client, config: ClientConfig) -> None:
+        self._http = http
+        self._config = config
+
+    def call(self, action: str, data: Mapping[str, JSONValue] | None = None) -> JSONValue:
+        """POST action parameters as JSON and return the unwrapped result.
+
+        Action names must be single alphanumeric/underscore identifiers. Calls
+        may mutate server data: choose actions and credentials deliberately.
+        Unsupported payload values raise ValueError before any network request.
+        """
+        if not re.fullmatch(r"[A-Za-z][A-Za-z0-9_]*", action):
+            raise ValueError("action must be a CKAN action identifier")
+        safe_action = str(redact(action, self._config.api_token))
+        if self._http.is_closed:
+            raise CKANError("Client is closed", action=safe_action)
+        try:
+            payload = json.dumps(dict(data) if data is not None else {}, allow_nan=False)
+        except (TypeError, ValueError):
+            raise ValueError("data must be a JSON-compatible mapping with finite numbers") from None
+        # Suppress raw HTTPX exception messages and chains, which can contain credentials.
+        failure: CKANError
+        try:
+            response = self._http.post(
+                self._config.action_url + "/" + action, content=payload.encode("utf-8")
+            )
+        except httpx.TimeoutException:
+            failure = CKANTimeoutError("CKAN request timed out", action=safe_action)
+        except httpx.RequestError:
+            failure = CKANConnectionError("CKAN request could not complete", action=safe_action)
+        else:
+            return parse_response(response, safe_action, self._config.api_token)
+        raise failure
+
+
+class CKANClient:
+    """Reusable synchronous client for an explicitly configured CKAN site.
+
+    Supply either ``site_url`` (and optionally ``api_token``) or ``config``.
+    An injected HTTPX transport is owned and closed by this client.
+    """
+
+    def __init__(
+        self,
+        site_url: str | None = None,
+        *,
+        api_token: str | None = None,
+        config: ClientConfig | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        if config is not None and (site_url is not None or api_token is not None):
+            raise ValueError("Pass config or site_url/api_token, not both")
+        if config is None:
+            if site_url is None:
+                raise ValueError("CKANClient requires site_url or config")
+            config = ClientConfig(site_url=site_url, api_token=api_token)
+        self.config = config
+        headers = {
+            "User-Agent": config.user_agent,
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+        if config.api_token is not None:
+            headers["Authorization"] = config.api_token
+        self._http = httpx.Client(
+            headers=headers,
+            timeout=httpx.Timeout(
+                connect=config.connect_timeout,
+                read=config.read_timeout,
+                write=config.write_timeout,
+                pool=config.pool_timeout,
+            ),
+            limits=httpx.Limits(
+                max_connections=config.max_connections,
+                max_keepalive_connections=config.max_keepalive_connections,
+            ),
+            verify=config.verify,
+            follow_redirects=False,
+            trust_env=False,
+            transport=transport,
+        )
+        self.actions = ActionService(self._http, config)
+
+    @property
+    def is_closed(self) -> bool:
+        """Whether the owned HTTP client has been closed."""
+        return self._http.is_closed
+
+    def close(self) -> None:
+        """Release the connection pool; safe to call more than once."""
+        self._http.close()
+
+    def __enter__(self) -> Self:
+        if self.is_closed:
+            raise CKANError("Client is closed", action="")
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class ChileOpenDataClient(CKANClient):
+    """CKAN client defaulting to https://datos.gob.cl/api/3/action."""
+
+    def __init__(
+        self,
+        site_url: str | None = None,
+        *,
+        api_token: str | None = None,
+        config: ClientConfig | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        super().__init__(
+            site_url="https://datos.gob.cl" if config is None and site_url is None else site_url,
+            api_token=api_token,
+            config=config,
+            transport=transport,
+        )

chile_open_data_sdk/config.py

@@ -0,0 +1,93 @@
+"""Validated, immutable connection settings; constructors never read credentials implicitly."""
+
+import re
+from dataclasses import dataclass, field
+from math import isfinite
+from typing import TypeGuard
+from urllib.parse import urlsplit
+
+
+def _is_connection_limit(value: object) -> TypeGuard[int]:
+    """Narrow untrusted runtime input to an integer, excluding booleans."""
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def _validate_tls_verification(value: object) -> None:
+    """Reject untyped inputs that could accidentally disable TLS verification."""
+    if not isinstance(value, bool):
+        raise ValueError("verify must be a boolean")
+
+
+@dataclass(frozen=True, slots=True)
+class ClientConfig:
+    """Configure a CKAN endpoint, timeouts in seconds, and connection pool limits.
+
+    ``site_url`` can include a deployment prefix. TLS verification is enabled and
+    redirects are deliberately disabled. ``api_token`` is excluded from repr.
+    """
+
+    site_url: str = "https://datos.gob.cl"
+    action_path: str = "/api/3/action"
+    api_token: str | None = field(default=None, repr=False)
+    user_agent: str = "chile-open-data-sdk/0.1.0"
+    connect_timeout: float = 5.0
+    read_timeout: float = 30.0
+    write_timeout: float = 30.0
+    pool_timeout: float = 5.0
+    max_connections: int = 100
+    max_keepalive_connections: int = 20
+    verify: bool = True
+
+    def __post_init__(self) -> None:
+        """Reject ambiguous endpoints and invalid settings without echoing credentials."""
+        try:
+            url = urlsplit(self.site_url)
+            valid = (
+                url.scheme in {"http", "https"}
+                and bool(url.hostname)
+                and url.username is None
+                and url.password is None
+                and not url.query
+                and not url.fragment
+                and url.port != 0
+                and not any(c.isspace() or ord(c) < 32 for c in self.site_url)
+                and "\\" not in self.site_url
+                and all(p not in {".", ".."} for p in url.path.split("/"))
+                and "%" not in url.path
+            )
+        except ValueError:
+            valid = False
+        if not valid:
+            raise ValueError(
+                "site_url must be an HTTP(S) URL without credentials, query or fragment"
+            )
+        if not re.fullmatch(r"/(?:[A-Za-z0-9_-]+/)*[A-Za-z0-9_-]+/?", self.action_path):
+            raise ValueError("action_path must contain only absolute path segments")
+        object.__setattr__(self, "site_url", self.site_url.rstrip("/"))
+        object.__setattr__(self, "action_path", self.action_path.rstrip("/"))
+        for value in (
+            self.connect_timeout,
+            self.read_timeout,
+            self.write_timeout,
+            self.pool_timeout,
+        ):
+            if isinstance(value, bool) or not isfinite(value) or value <= 0:
+                raise ValueError("Timeouts must be finite positive seconds")
+        if (
+            not _is_connection_limit(self.max_connections)
+            or self.max_connections < 1
+            or not _is_connection_limit(self.max_keepalive_connections)
+            or not 0 <= self.max_keepalive_connections <= self.max_connections
+        ):
+            raise ValueError("Connection limits must be integers with 0 <= keepalive <= maximum")
+        for header_value in (self.user_agent, self.api_token):
+            if header_value is not None and (
+                not header_value or any(ord(c) < 32 or ord(c) > 126 for c in header_value)
+            ):
+                raise ValueError("Header values must be nonempty printable ASCII")
+        _validate_tls_verification(self.verify)
+
+    @property
+    def action_url(self) -> str:
+        """Return the normalized Action API base URL."""
+        return self.site_url + self.action_path

chile_open_data_sdk/errors.py

@@ -0,0 +1,66 @@
+"""SDK exceptions with safe action context; raw requests and responses are not retained."""
+
+from chile_open_data_sdk.types import JSONValue
+
+
+class ChileOpenDataError(Exception):
+    """Base exception for SDK runtime failures."""
+
+
+class CKANError(ChileOpenDataError):
+    """CKAN failure with sanitized diagnostic context."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        action: str,
+        status_code: int | None = None,
+        error_type: str | None = None,
+        details: JSONValue = None,
+    ) -> None:
+        super().__init__(message)
+        self.action = action
+        self.status_code = status_code
+        self.error_type = error_type
+        self.details = details
+
+
+class CKANAPIError(CKANError):
+    """CKAN returned success=false."""
+
+
+class CKANProtocolError(CKANError):
+    """The response was not a valid CKAN JSON envelope."""
+
+
+class CKANHTTPError(CKANError):
+    """An HTTP response was unsuccessful, including redirects."""
+
+
+class CKANAuthenticationError(CKANAPIError, CKANHTTPError):
+    """Authentication is required or failed."""
+
+
+class CKANAuthorizationError(CKANAPIError, CKANHTTPError):
+    """The server denied permission."""
+
+
+class CKANNotFoundError(CKANAPIError, CKANHTTPError):
+    """The requested action or entity was not found."""
+
+
+class CKANValidationError(CKANAPIError, CKANHTTPError):
+    """The server rejected the action parameters."""
+
+
+class CKANRateLimitError(CKANAPIError, CKANHTTPError):
+    """The server rate limited the request; it was not retried."""
+
+
+class CKANTimeoutError(CKANError):
+    """A connect, read, write, or pool timeout occurred."""
+
+
+class CKANConnectionError(CKANError):
+    """HTTPX could not complete the request."""

chile_open_data_sdk/types.py

@@ -0,0 +1,5 @@
+"""Shared JSON types for schema-independent CKAN action data."""
+
+from typing import TypeAlias
+
+JSONValue: TypeAlias = bool | int | float | str | list["JSONValue"] | dict[str, "JSONValue"] | None

chile_open_data_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: chile-open-data-sdk
+Version: 0.1.0
+Summary: An unofficial, typed Python SDK for Chile's datos.gob.cl and CKAN Action API
+Keywords: chile,open-data,ckan,sdk
+Author: Eli-ezer Reuven Ramirez Ruiz
+Author-email: Eli-ezer Reuven Ramirez Ruiz <ramirez.ruiz.eliezer.reuven@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.12.0,<3
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/ezer-mackenzie/chile-open-data-sdk
+Project-URL: Issues, https://github.com/ezer-mackenzie/chile-open-data-sdk/issues
+Description-Content-Type: text/markdown
+
+# Chile Open Data SDK
+
+An unofficial, typed Python SDK for Chile's **datos.gob.cl**, with a reusable
+CKAN Action API core. This community project is **not an official SDK of the
+Government of Chile or the maintainers of datos.gob.cl**.
+
+## v0.1.0 scope
+
+This first release provides a synchronous client, validated configuration,
+connection pooling, JSON action calls, token authentication, and structured errors.
+It is an alpha foundation with a deliberately small public API.
+
+Typed dataset services, DataStore wrappers, pagination, async clients, downloads,
+and pandas/Polars integrations are planned for later milestones; they are not
+available in v0.1.0. Generic actions can already query catalog and DataStore
+endpoints when the server supports them.
+
+## Installation
+
+Python 3.11 or later is required. Before publication, install from a local checkout:
+
+```console
+uv sync --locked
+```
+
+Or build and install the wheel with a standard Python installer:
+
+```console
+uv build
+python -m pip install dist/chile_open_data_sdk-0.1.0-py3-none-any.whl
+```
+
+After v0.1.0 is published, installation will be:
+
+```console
+python -m pip install chile-open-data-sdk==0.1.0
+```
+
+The distribution is `chile-open-data-sdk`; the import is `chile_open_data_sdk`.
+
+## Quick start
+
+```python
+from chile_open_data_sdk import ChileOpenDataClient
+
+with ChileOpenDataClient() as client:
+    result = client.actions.call("package_search", {"q": "transport", "rows": 5})
+    datasets = result.get("results") if isinstance(result, dict) else None
+    if isinstance(datasets, list):
+        for dataset in datasets:
+            if isinstance(dataset, dict):
+                print(dataset.get("title"))
+```
+
+The default endpoint is `https://datos.gob.cl/api/3/action`. Calls return the
+unwrapped JSON `result`, preserving additional server fields. Availability and
+metadata quality depend on the upstream portal.
+
+## Another CKAN site
+
+```python
+from chile_open_data_sdk import CKANClient
+
+with CKANClient(site_url="https://demo.ckan.org") as client:
+    print(client.actions.call("package_list", {"limit": 5}))
+```
+
+## Authentication and errors
+
+Credentials are explicit and are sent only in the `Authorization` header. The
+constructor does not read environment credentials. Your application can do so:
+
+```python
+import os
+
+from chile_open_data_sdk import ChileOpenDataClient
+from chile_open_data_sdk.errors import CKANError
+
+try:
+    with ChileOpenDataClient(api_token=os.environ.get("CHILE_OPEN_DATA_API_TOKEN")) as client:
+        result = client.actions.call("package_list", {"limit": 5})
+except CKANError as error:
+    print(error.action, error.status_code, error.error_type)
+```
+
+Generic calls use JSON POST and **never retry automatically**, including read
+operations. They can execute writes: the caller chooses the action and the server
+enforces permissions. Redirects are not followed. Configuration and SDK error
+representations exclude the configured token; do not log raw payloads or credentials.
+
+## Documentation
+
+- [Getting started](docs/getting-started.md)
+- [Generic actions and querying examples](docs/actions.md)
+- [Configuration and authentication](docs/configuration.md)
+- [Error handling](docs/errors.md)
+- [Public API reference](docs/api.md)
+- [Development tools and benchmarks](docs/development.md)
+- [Architecture](docs/architecture.md)
+- [Compatibility and limitations](docs/compatibility.md)
+- [Roadmap](docs/roadmap.md)
+- [Release process](docs/releasing.md)
+- [v0.1.0 release notes](docs/release-notes.md)
+- [Changelog](CHANGELOG.md)
+
+Build the documentation locally with `uv run --group docs mkdocs build --strict`,
+or preview with `uv run --group docs mkdocs serve`. No hosted documentation URL
+is claimed until deployment is configured.
+
+## Development
+
+```console
+uv sync --locked --group docs
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src
+uv run basedpyright
+uv run pytest
+uv run --group docs mkdocs build --strict
+uv build
+uv run python scripts/check_artifacts.py
+```
+
+Normal tests use mocked HTTP; live portal tests are opt-in. See
+[Contributing](CONTRIBUTING.md) and [Security](SECURITY.md).
+
+Existing CKAN clients such as [ckanapi](https://github.com/ckan/ckanapi) serve the
+community already. This project's direction is Chile-first defaults, modern
+Python typing, and progressively richer sync/async workflows.
+
+## License
+
+[MIT](LICENSE.md). Portal datasets may have their own licenses; the SDK's license
+does not determine permission to use upstream data.

chile_open_data_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+chile_open_data_sdk/__init__.py,sha256=cZM8N04lEAF5LKohv6Y4gncfJHxvkxaQPN-GSv_xYCo,337
+chile_open_data_sdk/_internal/__init__.py,sha256=-aV_bdzUpMEuUpWP6np8AckdhNg8nVPLRcpaYpCryMo,58
+chile_open_data_sdk/_internal/responses.py,sha256=hqlm6ZmJ7VNJfRK6eUZ5taS35TEXEik_2uF028aWjYY,3826
+chile_open_data_sdk/client.py,sha256=V192S_Eddr2aaA7WHVTr2Sbo_37X3DsbKQ_P6zUbitM,5284
+chile_open_data_sdk/config.py,sha256=2RCatEv9bIZt2PR72SpYo4PJm-DqDDvGsAYTVd7Ad7I,3845
+chile_open_data_sdk/errors.py,sha256=MESVxHjzupP6x6jyj_4YoYBk5AgzUO-CCyZhIVnRaL0,1726
+chile_open_data_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chile_open_data_sdk/types.py,sha256=VIkGbsOPuQVQWvUHuDVExFMUNfxgnZmmmTsG9YX2_0g,196
+chile_open_data_sdk-0.1.0.dist-info/licenses/LICENSE.md,sha256=_52YphtXeFMUcoxi_K3XL3uasy7QqRl_0nbFfBfTHrM,1084
+chile_open_data_sdk-0.1.0.dist-info/WHEEL,sha256=-i9oRNYVXXZJUIYl5zclLIg6onEb0NLibTX34uln84w,81
+chile_open_data_sdk-0.1.0.dist-info/METADATA,sha256=05V1qBuynEMfh9-ZGCs22-wC8AukImFx0sAXQNvDWHs,5462
+chile_open_data_sdk-0.1.0.dist-info/RECORD,,

chile_open_data_sdk-0.1.0.dist-info/WHEEL

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

chile_open_data_sdk-0.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Eli-ezer Reuven Ramirez Ruiz
+
+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.