chile-open-data-sdk 0.1.0__tar.gz

chile_open_data_sdk-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: Ruff lint
+        entry: uv run --locked ruff check .
+        language: system
+        pass_filenames: false
+        always_run: true
+      - id: ruff-format
+        name: Ruff format check
+        entry: uv run --locked ruff format --check .
+        language: system
+        pass_filenames: false
+        always_run: true
+      - id: mypy
+        name: Mypy strict
+        entry: uv run --locked mypy src
+        language: system
+        pass_filenames: false
+        always_run: true
+      - id: basedpyright
+        name: BasedPyright strict
+        entry: uv run --locked basedpyright
+        language: system
+        pass_filenames: false
+        always_run: true
+      - id: pytest
+        name: Offline tests and coverage
+        entry: uv run --locked pytest
+        language: system
+        pass_filenames: false
+        always_run: true

chile_open_data_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes are documented here. Versions before 1.0 may evolve their
+public API; compatibility changes will be recorded explicitly.
+
+## Unreleased
+
+### Changed
+
+- Rename the import package from `chile_open_data` to `chile_open_data_sdk` before
+  publication. Update imports, documentation, CI, coverage, and artifact validation.
+  The distribution remains `chile-open-data-sdk`; class names and behavior are unchanged.
+  No compatibility alias is provided. The original local v0.1.0 tag is preserved.
+
+### Added
+
+- Optional BenchCore 1.x integration for Python 3.12+, with two explicitly selected
+  CPU benchmarks, JSON report persistence, and a manual reports workflow. SDK and
+  default development support remain Python 3.11+.
+
+- Strict BasedPyright checks shared with Pyright/Pylance, enforced in CI.
+- Local pre-commit hooks for Ruff, formatting, mypy, BasedPyright, and offline tests.
+- Hypothesis property tests for arbitrary JSON results and immutable secret redaction.
+- Optional pytest-benchmark group with network-free response and redaction benchmarks.
+- Additional Ruff rules for security, comprehensions, logging, datetime usage, and debugging.
+
+### Fixed
+
+- Restore PyPI Trusted Publishing on published non-prerelease GitHub Releases and
+  manual dispatch with a required existing tag. Verify tag/version/commit identity
+  and run uv quality, documentation, and build checks before the isolated OIDC upload.
+
+- Remove unnecessary-isinstance diagnostics by separating runtime validation of
+  untyped configuration values from the typed configuration model.
+- Make response assignment and quick-start JSON narrowing explicit for static analyzers.
+
+These changes follow the local v0.1.0 checkpoint; the existing tag is not moved.
+
+## 0.1.0
+
+Initial foundation release, prepared locally; publication is a separate step.
+
+### Added
+
+- Reusable synchronous `CKANClient` and Chile-first `ChileOpenDataClient`.
+- Frozen typed configuration, granular timeouts, connection limits, TLS verification.
+- Generic JSON Action API calls with unwrapped recursive JSON results.
+- Pydantic v2 envelope validation and structured HTTP, CKAN, and transport errors.
+- Explicit Authorization token support and recursive diagnostic redaction.
+- Deterministic contract tests and an opt-in read-only portal test.
+- English usage guides, generated API reference, policies, roadmap, and release notes.
+- uv lockfile, typed package marker, Python 3.11–3.14 CI, build and artifact checks.
+
+### Changed
+
+- Replace the empty `chile_open_data_sdk` import skeleton with `chile_open_data`.
+- Replace Poetry packaging with uv/uv_build and lower required Python from 3.14 to 3.11.
+- Replace the inherited publishing workflow with manual artifact preparation.
+
+### Security
+
+- Disable redirects, environment credentials/proxies, and automatic request replay.
+- Exclude configured tokens and raw HTTP response bodies from SDK diagnostics.

chile_open_data_sdk-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,12 @@
+# Code of conduct
+
+We welcome contributors with different backgrounds and experience levels. Be
+respectful, explain technical disagreements constructively, and give others room
+to learn. Harassment, threats, discrimination, unwanted personal attention, and
+publication of private information are not acceptable.
+
+These expectations apply to project issues, pull requests, reviews, and other
+project spaces. Report concerns privately to the maintainer at
+ramirez.ruiz.eliezer.reuven@gmail.com. The maintainer may remove harmful content,
+limit participation, or exclude participants to protect the community. Reports
+will be handled with care for the privacy of those involved.

chile_open_data_sdk-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing
+
+Thank you for helping improve this unofficial community SDK. Keep repository
+code, documentation, examples, and commit messages in English. Spanish is allowed
+in upstream data and examples demonstrating Chilean data.
+
+## Set up
+
+Install Python 3.11+ and uv, clone the repository, then run:
+
+```console
+uv sync --locked --group docs
+```
+
+Use `uv add`, `uv add --dev`, or `uv add --group docs` to change dependencies.
+Never hand-edit `uv.lock`. Runtime dependencies should be justified by features;
+optional integrations must remain optional. No global Python tooling is required.
+
+## Validate before each commit
+
+```console
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src
+uv run basedpyright
+uv run pytest
+```
+
+For documentation and packaging changes, also run:
+
+```console
+uv run --group docs mkdocs build --strict
+uv build
+uv run python scripts/check_artifacts.py
+```
+
+Tests use HTTPX MockTransport by default and enforce 90% branch-aware coverage.
+Add behavior-focused tests for public changes and credential-sensitive paths.
+Never test writes against production. To explicitly enable public read tests:
+
+```powershell
+$env:CHILE_OPEN_DATA_LIVE_TESTS = "1"
+uv run pytest tests/integration --no-cov
+```
+
+On POSIX shells use `CHILE_OPEN_DATA_LIVE_TESTS=1 uv run pytest tests/integration --no-cov`.
+Live availability is not a normal pull-request requirement.
+
+## Local hooks and extended tests
+
+Ruff handles both linting and formatting. Mypy checks the SDK in strict mode;
+BasedPyright also checks SDK code, examples, and packaging scripts, using a shared
+`pyrightconfig.json` understood by Pyright/Pylance. Select the project's `.venv`
+interpreter in your editor. The unnecessary-isinstance diagnostic stays enabled.
+
+Install the repository-local hooks after syncing the environment:
+
+```console
+uv run pre-commit install
+uv run pre-commit run --all-files
+```
+
+Hooks run the locked uv tools, including offline tests, before commits. They check
+formatting without modifying files. Format explicitly with `uv run ruff format .`.
+Hypothesis property tests run as part of normal pytest. Benchmarks are opt-in:
+
+```console
+uv run --group benchmark pytest benchmarks --no-cov --benchmark-only
+```
+
+BenchCore reports are also available on Python 3.12+:
+
+```console
+uv run --group benchcore pytest benchmarks/benchcore_cases.py --no-cov --benchcore-save=.benchcore
+```
+
+See [Development tools](docs/development.md) for scope, rationale, and commands.
+
+## Changes and review
+
+Keep changes coherent and follow the roadmap. Describe the problem, resulting
+behavior, compatibility impact, and validation in pull requests. Update docs and
+CHANGELOG for user-visible changes. Use Conventional Commits such as
+`feat(core): ...`, `fix(actions): ...`, and `docs(api): ...`.
+
+Do not manufacture release history, rewrite user commits, or force-push. For
+agent-assisted changes, include an approved `Co-authored-by` identity; never
+invent one. Public API stability begins at 1.0, not at this alpha milestone.
+
+Report security issues through [SECURITY.md](SECURITY.md). Participation follows
+[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

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

chile_open_data_sdk-0.1.0/PKG-INFO

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

@@ -0,0 +1,134 @@
+# 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/SECURITY.md

@@ -0,0 +1,29 @@
+# Security policy
+
+## Supported versions
+
+Security fixes target the latest released version. v0.1.0 is the initial alpha;
+there are no older supported release lines or service-level guarantees.
+
+## Reporting a vulnerability
+
+Report vulnerabilities privately to the maintainer at
+ramirez.ruiz.eliezer.reuven@gmail.com. Include the affected version, reproduction
+steps, and impact using synthetic credentials. Do not put tokens, private data,
+or exploit details in public issues. Coordinate disclosure with the maintainer;
+no response-time commitment is currently offered.
+
+## Credential handling
+
+Use HTTPS and explicit CKAN tokens with the minimum necessary permissions.
+Never commit `.env` files or tokens. Revoke and rotate exposed credentials at the
+issuing CKAN site. Removing a token from a later commit does not revoke it.
+
+The SDK excludes tokens from configuration repr, redacts SDK error context,
+disables redirects, and does not retry generic actions. It cannot protect tokens
+that applications print directly or sensitive data returned in successful results.
+Custom transports and application logging remain the caller's responsibility.
+
+Generic actions can mutate data. A network timeout does not prove that a write
+failed; inspect server state before retrying. Use local/staging CKAN instances for
+write tests. The library does not execute or download resource files in v0.1.0.

chile_open_data_sdk-0.1.0/benchmarks/benchcore_cases.py

@@ -0,0 +1,33 @@
+"""Explicitly selected BenchCore measurements; excluded from normal test discovery."""
+
+import httpx
+import pytest
+from benchcore.core.models import BenchmarkConfig
+from benchcore.integrations.pytest import BenchCoreFixture
+
+from chile_open_data_sdk._internal.responses import parse_response, redact
+from chile_open_data_sdk.types import JSONValue
+
+
+@pytest.mark.benchcore(
+    name="parse-datastore-page[rows=1000]",
+    config=BenchmarkConfig(rounds=20, warmup_rounds=2, iterations=10),
+)
+def test_parse_datastore_page(benchcore: BenchCoreFixture) -> None:
+    records = [{"_id": i, "region": "Metropolitana", "value": i / 10} for i in range(1000)]
+    response = httpx.Response(200, json={"success": True, "result": {"records": records}})
+    result = benchcore(parse_response, response, "datastore_search", None)
+    assert result.value == {"records": records}
+
+
+@pytest.mark.benchcore(
+    name="redact-diagnostics[entries=100]",
+    config=BenchmarkConfig(rounds=20, warmup_rounds=2, iterations=10),
+)
+def test_redact_nested_diagnostics(benchcore: BenchCoreFixture) -> None:
+    token = "sdk_secret_benchcore_fixture"
+    payload: JSONValue = {
+        "errors": [{"message": "echo " + token, "api_token": token} for _ in range(100)]
+    }
+    result = benchcore(redact, payload, token)
+    assert token not in repr(result.value)

chile_open_data_sdk-0.1.0/benchmarks/test_responses.py

@@ -0,0 +1,23 @@
+"""Opt-in CPU benchmarks; no network calls or timing assertions."""
+
+import httpx
+from pytest_benchmark.fixture import BenchmarkFixture
+
+from chile_open_data_sdk._internal.responses import parse_response, redact
+from chile_open_data_sdk.types import JSONValue
+
+
+def test_parse_datastore_page(benchmark: BenchmarkFixture) -> None:
+    records = [{"_id": i, "region": "Metropolitana", "value": i / 10} for i in range(1000)]
+    response = httpx.Response(200, json={"success": True, "result": {"records": records}})
+    result = benchmark(parse_response, response, "datastore_search", None)
+    assert result == {"records": records}
+
+
+def test_redact_nested_diagnostics(benchmark: BenchmarkFixture) -> None:
+    token = "sdk_secret_benchmark_fixture"
+    payload: JSONValue = {
+        "errors": [{"message": "echo " + token, "api_token": token} for _ in range(100)]
+    }
+    result = benchmark(redact, payload, token)
+    assert token not in repr(result)

chile_open_data_sdk-0.1.0/docs/actions.md

@@ -0,0 +1,70 @@
+# Generic actions
+
+`client.actions.call(action, data=None)` sends a JSON object in an HTTP POST to
+`<site_url><action_path>/<action>`. Parameters are not transformed into a custom
+query language. Nested mappings, lists, booleans, and null are encoded as JSON.
+Action names must start with an ASCII letter and contain only ASCII letters,
+digits, and underscores. Files and multipart uploads are not supported.
+
+The return type is `JSONValue`: null, boolean, integer, float, string, list, or
+string-keyed dictionary, recursively. Parameters must also be JSON-compatible,
+with finite numeric values. Unknown CKAN result fields are preserved.
+
+## Catalog queries available through the generic API
+
+```python
+from chile_open_data_sdk import ChileOpenDataClient
+
+with ChileOpenDataClient() as client:
+    names = client.actions.call("package_list", {"limit": 5})
+    search = client.actions.call(
+        "package_search",
+        {
+            "q": "transport",
+            "fq": "res_format:CSV",
+            "rows": 5,
+            "start": 0,
+        },
+    )
+    organizations = client.actions.call("organization_list", {"limit": 5})
+```
+
+`package_show` and `resource_show` accept an `id` parameter supplied by your
+application. The names and capabilities of actions depend on the CKAN server and
+its plugins. Prefer the planned typed services when they become available.
+
+## DataStore examples
+
+The following assumes an existing client and a resource ID obtained from dataset
+metadata. These are generic calls, not the future typed DataStore service:
+
+```python
+result = client.actions.call(
+    "datastore_search",
+    {
+        "resource_id": resource_id,
+        "filters": {"region": "Metropolitana"},
+        "fields": ["region"],
+        "limit": 10,
+        "offset": 0,
+    },
+)
+```
+
+Field names and filter values must match the resource. `datastore_search_sql` can
+be called with `{"sql": sql}` if enabled upstream. SQL is caller-provided: never
+build it from untrusted input without proper validation. The SDK does not sanitize
+SQL or implement an ORM. DataStore availability is not guaranteed.
+
+## Writes, pagination, and retry policy
+
+The generic escape hatch can invoke authenticated write actions. There is no
+read-only allowlist or write confirmation in the SDK. CKAN enforces authorization.
+Never use production writes as connectivity tests.
+
+Every call makes one attempt. A timeout can occur after a write was applied; do
+not blindly repeat it. Pagination is manual in v0.1.0: set `start`/`rows` or
+`offset`/`limit` as appropriate. No background or unbounded fetching occurs.
+
+Protocol references: [CKAN Action API](https://docs.ckan.org/en/2.11/api/) and
+[DataStore API](https://docs.ckan.org/en/2.11/maintaining/datastore.html).

chile_open_data_sdk-0.1.0/docs/api.md

@@ -0,0 +1,16 @@
+# API reference
+
+The supported top-level exports are `CKANClient`, `ChileOpenDataClient`,
+`ClientConfig`, `JSONValue`, and `__version__`. Exceptions live in
+`chile_open_data_sdk.errors`. `ActionService` is accessed through `client.actions`;
+applications normally do not instantiate it directly. `_internal` is private.
+
+::: chile_open_data_sdk.client.CKANClient
+
+::: chile_open_data_sdk.client.ChileOpenDataClient
+
+::: chile_open_data_sdk.client.ActionService
+
+::: chile_open_data_sdk.config.ClientConfig
+
+::: chile_open_data_sdk.errors