periplus-python-sdk 0.2.0__tar.gz

periplus_python_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: periplus-python-sdk
+Version: 0.2.0
+Summary: Read-only Python client for the public Periplus query API
+Project-URL: Repository, https://github.com/elei-io/periplus
+Project-URL: Issues, https://github.com/elei-io/periplus/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic<3,>=2.12
+
+# Periplus Python SDK
+
+A read-only client for the public Periplus query API. Python 3.11 or later.
+Configure the **public web application URL**, not the internal query or control service.
+No API token, DuckDB installation or lake credentials are needed.
+
+```python
+from periplus_sdk import Client
+
+with Client("http://localhost:8080") as client:
+    result = client.execute(
+        "SELECT observation_id FROM web.observation LIMIT ?", [10]
+    )
+    print(result.columns, result.types)
+    print(result.rows)
+    print(result.source_snapshot, result.truncated)
+```
+
+For a hosted deployment, replace the URL with its public HTTPS origin. Alternatively set
+`PERIPLUS_PUBLIC_URL` and use `Client()`. An optional URL path prefix is preserved.
+The client reuses HTTP connections; close it with a context manager or `close()`.
+
+## Preparation and helpers
+
+```python
+with Client("http://localhost:8080") as client:
+    prepared = client.prepare("SELECT observation_id FROM web.observation LIMIT ?", [10])
+    print(prepared.diagnostics, prepared.plan)
+    result = client.execute(prepared.sql, prepared.parameters)
+    helpers = client.helpers()
+    print(helpers.catalogue_version, helpers.helpers)
+```
+
+Preparation validates and explains without executing the analytical query. Execution independently
+validates and prepares; a prior preparation never authorizes SQL. Linting, diagnostics and future
+SQL optimizations belong to the server. The SDK sends SQL unchanged.
+
+## Async use
+
+```python
+from periplus_sdk import AsyncClient
+
+async def observations():
+    async with AsyncClient("http://localhost:8080") as client:
+        return await client.execute("SELECT observation_id FROM web.observation LIMIT 10")
+```
+
+Use `aclose()` when managing an async client's lifetime explicitly.
+
+## Permissions, results and errors
+
+- The same public SQL feature switch, shared rate budget, namespace validation and read-only
+  execution apply as in the public web workspace. The SDK provides no writes, crawling,
+  administrative controls or direct lake attachment.
+- Results retain `query_id`, SQL, parameters, diagnostics, plan, columns, SQL types, JSON rows,
+  elapsed milliseconds, `source_snapshot` and `truncated`. Decimals and large integers remain
+  strings exactly as returned by the server. Duplicate column names are preserved.
+- Operator-configured execution limits default to 1,000 rows, an 8 MiB result budget and a
+  20-second server deadline. Always inspect `truncated`. The SDK does not silently fetch more rows or retry.
+- `ApiError` exposes `status_code`, safe `code`, and `retry_after_seconds` when supplied.
+  `TransportError` means HTTP failed; `ResponseError` means a malformed successful response.
+  The client timeout defaults to 140 seconds and can be set with `timeout=`. A timeout or local
+  cancellation does not guarantee server cancellation. Redirects are not followed automatically.
+- Preparation and execution are attributed to `sdk` in the existing private query history.
+  Original SQL and parameters are retained for 30 days; result rows are not stored. Recording is
+  best-effort and can be lost during outages or backpressure. This label is not a user identity.
+
+## Installation and verification
+
+Install from PyPI:
+
+```sh
+python -m pip install periplus-python-sdk==0.2.0
+```
+
+For local development: `python -m pip install ./packages/periplus-python-sdk`.
+Run the installed package against an available public app:
+
+```sh
+PERIPLUS_PUBLIC_URL=http://localhost:8080 python packages/periplus-python-sdk/examples/smoke.py
+```
+
+## Releasing
+
+Repository CI publishes immutable releases from tags named
+`periplus-python-sdk-v<version>`. The tag must exactly match the static version
+in `pyproject.toml`; for example, version `0.2.0` is released with:
+
+```sh
+git tag periplus-python-sdk-v0.2.0
+git push origin periplus-python-sdk-v0.2.0
+```
+
+PyPI publishing uses Trusted Publishing rather than a stored API token. The
+PyPI publisher must be configured for GitHub owner `elei-io`, repository
+`periplus`, workflow `python-sdk-release.yml`, and environment `pypi`. Protect
+that GitHub environment with required reviewers before the first release.

periplus_python_sdk-0.2.0/README.md

@@ -0,0 +1,97 @@
+# Periplus Python SDK
+
+A read-only client for the public Periplus query API. Python 3.11 or later.
+Configure the **public web application URL**, not the internal query or control service.
+No API token, DuckDB installation or lake credentials are needed.
+
+```python
+from periplus_sdk import Client
+
+with Client("http://localhost:8080") as client:
+    result = client.execute(
+        "SELECT observation_id FROM web.observation LIMIT ?", [10]
+    )
+    print(result.columns, result.types)
+    print(result.rows)
+    print(result.source_snapshot, result.truncated)
+```
+
+For a hosted deployment, replace the URL with its public HTTPS origin. Alternatively set
+`PERIPLUS_PUBLIC_URL` and use `Client()`. An optional URL path prefix is preserved.
+The client reuses HTTP connections; close it with a context manager or `close()`.
+
+## Preparation and helpers
+
+```python
+with Client("http://localhost:8080") as client:
+    prepared = client.prepare("SELECT observation_id FROM web.observation LIMIT ?", [10])
+    print(prepared.diagnostics, prepared.plan)
+    result = client.execute(prepared.sql, prepared.parameters)
+    helpers = client.helpers()
+    print(helpers.catalogue_version, helpers.helpers)
+```
+
+Preparation validates and explains without executing the analytical query. Execution independently
+validates and prepares; a prior preparation never authorizes SQL. Linting, diagnostics and future
+SQL optimizations belong to the server. The SDK sends SQL unchanged.
+
+## Async use
+
+```python
+from periplus_sdk import AsyncClient
+
+async def observations():
+    async with AsyncClient("http://localhost:8080") as client:
+        return await client.execute("SELECT observation_id FROM web.observation LIMIT 10")
+```
+
+Use `aclose()` when managing an async client's lifetime explicitly.
+
+## Permissions, results and errors
+
+- The same public SQL feature switch, shared rate budget, namespace validation and read-only
+  execution apply as in the public web workspace. The SDK provides no writes, crawling,
+  administrative controls or direct lake attachment.
+- Results retain `query_id`, SQL, parameters, diagnostics, plan, columns, SQL types, JSON rows,
+  elapsed milliseconds, `source_snapshot` and `truncated`. Decimals and large integers remain
+  strings exactly as returned by the server. Duplicate column names are preserved.
+- Operator-configured execution limits default to 1,000 rows, an 8 MiB result budget and a
+  20-second server deadline. Always inspect `truncated`. The SDK does not silently fetch more rows or retry.
+- `ApiError` exposes `status_code`, safe `code`, and `retry_after_seconds` when supplied.
+  `TransportError` means HTTP failed; `ResponseError` means a malformed successful response.
+  The client timeout defaults to 140 seconds and can be set with `timeout=`. A timeout or local
+  cancellation does not guarantee server cancellation. Redirects are not followed automatically.
+- Preparation and execution are attributed to `sdk` in the existing private query history.
+  Original SQL and parameters are retained for 30 days; result rows are not stored. Recording is
+  best-effort and can be lost during outages or backpressure. This label is not a user identity.
+
+## Installation and verification
+
+Install from PyPI:
+
+```sh
+python -m pip install periplus-python-sdk==0.2.0
+```
+
+For local development: `python -m pip install ./packages/periplus-python-sdk`.
+Run the installed package against an available public app:
+
+```sh
+PERIPLUS_PUBLIC_URL=http://localhost:8080 python packages/periplus-python-sdk/examples/smoke.py
+```
+
+## Releasing
+
+Repository CI publishes immutable releases from tags named
+`periplus-python-sdk-v<version>`. The tag must exactly match the static version
+in `pyproject.toml`; for example, version `0.2.0` is released with:
+
+```sh
+git tag periplus-python-sdk-v0.2.0
+git push origin periplus-python-sdk-v0.2.0
+```
+
+PyPI publishing uses Trusted Publishing rather than a stored API token. The
+PyPI publisher must be configured for GitHub owner `elei-io`, repository
+`periplus`, workflow `python-sdk-release.yml`, and environment `pypi`. Protect
+that GitHub environment with required reviewers before the first release.

periplus_python_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "periplus-python-sdk"
+version = "0.2.0"
+description = "Read-only Python client for the public Periplus query API"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.28",
+    "pydantic>=2.12,<3",
+]
+
+[project.urls]
+Repository = "https://github.com/elei-io/periplus"
+Issues = "https://github.com/elei-io/periplus/issues"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+periplus_sdk = ["py.typed"]

periplus_python_sdk-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

periplus_python_sdk-0.2.0/src/periplus_python_sdk.egg-info/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: periplus-python-sdk
+Version: 0.2.0
+Summary: Read-only Python client for the public Periplus query API
+Project-URL: Repository, https://github.com/elei-io/periplus
+Project-URL: Issues, https://github.com/elei-io/periplus/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic<3,>=2.12
+
+# Periplus Python SDK
+
+A read-only client for the public Periplus query API. Python 3.11 or later.
+Configure the **public web application URL**, not the internal query or control service.
+No API token, DuckDB installation or lake credentials are needed.
+
+```python
+from periplus_sdk import Client
+
+with Client("http://localhost:8080") as client:
+    result = client.execute(
+        "SELECT observation_id FROM web.observation LIMIT ?", [10]
+    )
+    print(result.columns, result.types)
+    print(result.rows)
+    print(result.source_snapshot, result.truncated)
+```
+
+For a hosted deployment, replace the URL with its public HTTPS origin. Alternatively set
+`PERIPLUS_PUBLIC_URL` and use `Client()`. An optional URL path prefix is preserved.
+The client reuses HTTP connections; close it with a context manager or `close()`.
+
+## Preparation and helpers
+
+```python
+with Client("http://localhost:8080") as client:
+    prepared = client.prepare("SELECT observation_id FROM web.observation LIMIT ?", [10])
+    print(prepared.diagnostics, prepared.plan)
+    result = client.execute(prepared.sql, prepared.parameters)
+    helpers = client.helpers()
+    print(helpers.catalogue_version, helpers.helpers)
+```
+
+Preparation validates and explains without executing the analytical query. Execution independently
+validates and prepares; a prior preparation never authorizes SQL. Linting, diagnostics and future
+SQL optimizations belong to the server. The SDK sends SQL unchanged.
+
+## Async use
+
+```python
+from periplus_sdk import AsyncClient
+
+async def observations():
+    async with AsyncClient("http://localhost:8080") as client:
+        return await client.execute("SELECT observation_id FROM web.observation LIMIT 10")
+```
+
+Use `aclose()` when managing an async client's lifetime explicitly.
+
+## Permissions, results and errors
+
+- The same public SQL feature switch, shared rate budget, namespace validation and read-only
+  execution apply as in the public web workspace. The SDK provides no writes, crawling,
+  administrative controls or direct lake attachment.
+- Results retain `query_id`, SQL, parameters, diagnostics, plan, columns, SQL types, JSON rows,
+  elapsed milliseconds, `source_snapshot` and `truncated`. Decimals and large integers remain
+  strings exactly as returned by the server. Duplicate column names are preserved.
+- Operator-configured execution limits default to 1,000 rows, an 8 MiB result budget and a
+  20-second server deadline. Always inspect `truncated`. The SDK does not silently fetch more rows or retry.
+- `ApiError` exposes `status_code`, safe `code`, and `retry_after_seconds` when supplied.
+  `TransportError` means HTTP failed; `ResponseError` means a malformed successful response.
+  The client timeout defaults to 140 seconds and can be set with `timeout=`. A timeout or local
+  cancellation does not guarantee server cancellation. Redirects are not followed automatically.
+- Preparation and execution are attributed to `sdk` in the existing private query history.
+  Original SQL and parameters are retained for 30 days; result rows are not stored. Recording is
+  best-effort and can be lost during outages or backpressure. This label is not a user identity.
+
+## Installation and verification
+
+Install from PyPI:
+
+```sh
+python -m pip install periplus-python-sdk==0.2.0
+```
+
+For local development: `python -m pip install ./packages/periplus-python-sdk`.
+Run the installed package against an available public app:
+
+```sh
+PERIPLUS_PUBLIC_URL=http://localhost:8080 python packages/periplus-python-sdk/examples/smoke.py
+```
+
+## Releasing
+
+Repository CI publishes immutable releases from tags named
+`periplus-python-sdk-v<version>`. The tag must exactly match the static version
+in `pyproject.toml`; for example, version `0.2.0` is released with:
+
+```sh
+git tag periplus-python-sdk-v0.2.0
+git push origin periplus-python-sdk-v0.2.0
+```
+
+PyPI publishing uses Trusted Publishing rather than a stored API token. The
+PyPI publisher must be configured for GitHub owner `elei-io`, repository
+`periplus`, workflow `python-sdk-release.yml`, and environment `pypi`. Protect
+that GitHub environment with required reviewers before the first release.

periplus_python_sdk-0.2.0/src/periplus_python_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/periplus_python_sdk.egg-info/PKG-INFO
+src/periplus_python_sdk.egg-info/SOURCES.txt
+src/periplus_python_sdk.egg-info/dependency_links.txt
+src/periplus_python_sdk.egg-info/requires.txt
+src/periplus_python_sdk.egg-info/top_level.txt
+src/periplus_sdk/__init__.py
+src/periplus_sdk/client.py
+src/periplus_sdk/errors.py
+src/periplus_sdk/py.typed
+src/periplus_sdk/types.py
+tests/test_client.py

periplus_python_sdk-0.2.0/src/periplus_python_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

periplus_python_sdk-0.2.0/src/periplus_python_sdk.egg-info/requires.txt

@@ -0,0 +1,2 @@
+httpx>=0.28
+pydantic<3,>=2.12

periplus_python_sdk-0.2.0/src/periplus_python_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+periplus_sdk

periplus_python_sdk-0.2.0/src/periplus_sdk/__init__.py

@@ -0,0 +1,8 @@
+"""Read-only Python clients for the public Periplus query API."""
+from .client import AsyncClient, Client
+from .errors import ApiError, ConfigurationError, PeriplusError, ResponseError, TransportError
+from .types import Diagnostic, PreparedQuery, QueryHelper, QueryHelpers, QueryResult
+
+__all__ = ["AsyncClient", "Client", "ApiError", "ConfigurationError", "PeriplusError",
+           "ResponseError", "TransportError", "Diagnostic", "PreparedQuery", "QueryHelper",
+           "QueryHelpers", "QueryResult"]

periplus_python_sdk-0.2.0/src/periplus_sdk/client.py

@@ -0,0 +1,140 @@
+"""HTTP clients for the public application's existing /api/query routes."""
+from __future__ import annotations
+
+from collections.abc import Sequence
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+import math
+import os
+from typing import TypeVar
+
+import httpx
+from pydantic import BaseModel, JsonValue, ValidationError
+
+from .errors import ApiError, ConfigurationError, ResponseError, TransportError
+from .types import PreparedQuery, QueryHelpers, QueryResult
+
+Model = TypeVar("Model", bound=BaseModel)
+
+
+def _options(base_url: str | None, timeout: float) -> dict:
+    value = (base_url or os.environ.get("PERIPLUS_PUBLIC_URL", "")).strip()
+    try:
+        url = httpx.URL(value)
+    except httpx.InvalidURL:
+        raise ConfigurationError("Provide a valid public application URL.") from None
+    if url.scheme not in {"http", "https"} or not url.host or url.userinfo or url.query or url.fragment:
+        raise ConfigurationError("Provide an HTTP(S) public application URL without credentials, query or fragment.")
+    if not math.isfinite(timeout) or timeout <= 0:
+        raise ConfigurationError("timeout must be a positive finite number of seconds.")
+    return dict(base_url=str(url).rstrip("/") + "/", timeout=timeout,
+                headers={"x-periplus-query-source": "sdk", "accept": "application/json"},
+                follow_redirects=False)
+
+
+def _retry_after(value: str | None) -> float | None:
+    if value is None:
+        return None
+    try:
+        seconds = float(value)
+    except ValueError:
+        try:
+            moment = parsedate_to_datetime(value)
+            if moment.utcoffset() is None:
+                return None
+            seconds = (moment - datetime.now(UTC)).total_seconds()
+        except (ValueError, TypeError, OverflowError):
+            return None
+    return max(0, seconds) if math.isfinite(seconds) else None
+
+
+def _decode(response: httpx.Response, model: type[Model]) -> Model:
+    if not response.is_success:
+        code = None
+        message = f"Public query request failed (HTTP {response.status_code})."
+        try:
+            body = response.json()
+            if isinstance(body, dict):
+                detail = body.get("detail")
+                error = detail if isinstance(detail, dict) else body
+                code = error.get("code")
+                if isinstance(error.get("detail"), str):
+                    message = error["detail"]
+        except ValueError:
+            pass
+        raise ApiError(message, status_code=response.status_code,
+                       code=code if isinstance(code, str) else None,
+                       retry_after_seconds=_retry_after(response.headers.get("retry-after")))
+    try:
+        return model.model_validate(response.json())
+    except (ValueError, ValidationError):
+        raise ResponseError("Public query response did not match the expected contract.") from None
+
+
+def _payload(sql: str, parameters: Sequence[JsonValue] | None) -> dict:
+    # Server owns SQL validation, linting, preparation and optimization.
+    return {"sql": sql, "parameters": list(parameters) if parameters is not None else []}
+
+
+class Client:
+    """Reusable synchronous public query client. Close it or use a with block."""
+
+    def __init__(self, base_url: str | None = None, *, timeout: float = 140):
+        self._http = httpx.Client(**_options(base_url, timeout))
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _request(self, method: str, path: str, model: type[Model], **kwargs) -> Model:
+        try:
+            response = self._http.request(method, "api/query/" + path, **kwargs)
+        except httpx.RequestError:
+            raise TransportError("Could not complete the public query request.") from None
+        return _decode(response, model)
+
+    def prepare(self, sql: str, parameters: Sequence[JsonValue] | None = None) -> PreparedQuery:
+        return self._request("POST", "prep", PreparedQuery, json=_payload(sql, parameters))
+
+    def execute(self, sql: str, parameters: Sequence[JsonValue] | None = None) -> QueryResult:
+        return self._request("POST", "exec", QueryResult, json=_payload(sql, parameters))
+
+    def helpers(self) -> QueryHelpers:
+        return self._request("GET", "helpers", QueryHelpers)
+
+
+class AsyncClient:
+    """Reusable asynchronous public query client. Use an async with block."""
+
+    def __init__(self, base_url: str | None = None, *, timeout: float = 140):
+        self._http = httpx.AsyncClient(**_options(base_url, timeout))
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(self, *args):
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def _request(self, method: str, path: str, model: type[Model], **kwargs) -> Model:
+        try:
+            response = await self._http.request(method, "api/query/" + path, **kwargs)
+        except httpx.RequestError:
+            raise TransportError("Could not complete the public query request.") from None
+        return _decode(response, model)
+
+    async def prepare(self, sql: str, parameters: Sequence[JsonValue] | None = None) -> PreparedQuery:
+        return await self._request("POST", "prep", PreparedQuery, json=_payload(sql, parameters))
+
+    async def execute(self, sql: str, parameters: Sequence[JsonValue] | None = None) -> QueryResult:
+        return await self._request("POST", "exec", QueryResult, json=_payload(sql, parameters))
+
+    async def helpers(self) -> QueryHelpers:
+        return await self._request("GET", "helpers", QueryHelpers)

periplus_python_sdk-0.2.0/src/periplus_sdk/errors.py

@@ -0,0 +1,28 @@
+"""Public query failures, including the server's safe error category."""
+
+
+class PeriplusError(Exception):
+    """Base SDK error."""
+
+
+class ConfigurationError(PeriplusError, ValueError):
+    """The public application URL or timeout is invalid."""
+
+
+class TransportError(PeriplusError):
+    """The public application could not be reached; no automatic retry occurs."""
+
+
+class ResponseError(PeriplusError):
+    """The public application returned an invalid response."""
+
+
+class ApiError(PeriplusError):
+    """A public gateway or query-service rejection."""
+
+    def __init__(self, message: str, *, status_code: int, code: str | None = None,
+                 retry_after_seconds: float | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.retry_after_seconds = retry_after_seconds

periplus_python_sdk-0.2.0/src/periplus_sdk/py.typed

@@ -0,0 +1 @@
+

periplus_python_sdk-0.2.0/src/periplus_sdk/types.py

@@ -0,0 +1,45 @@
+"""Public query wire types; SQL types and JSON values are preserved."""
+from pydantic import BaseModel, Field, JsonValue
+
+
+class Diagnostic(BaseModel):
+    severity: str
+    code: str
+    message: str
+
+
+class PreparedQuery(BaseModel):
+    query_id: str
+    sql: str
+    parameters: list[JsonValue]
+    diagnostics: list[Diagnostic]
+    plan: str
+
+
+class QueryResult(PreparedQuery):
+    columns: list[str]
+    types: list[str]
+    rows: list[list[JsonValue]]
+    truncated: bool
+    elapsed_ms: float
+    source_snapshot: int = Field(ge=0)
+
+
+class HelperField(BaseModel):
+    name: str
+    description: str
+
+
+class QueryHelper(BaseModel):
+    name: str
+    kind: str
+    description: str
+    parameters: list[HelperField]
+    columns: list[HelperField]
+    notes: list[str]
+    examples: list[str]
+
+
+class QueryHelpers(BaseModel):
+    catalogue_version: str
+    helpers: list[QueryHelper]

periplus_python_sdk-0.2.0/tests/test_client.py

@@ -0,0 +1,110 @@
+import json
+import os
+import unittest
+from unittest.mock import patch
+
+import httpx
+
+from periplus_sdk import AsyncClient, Client, ApiError, ConfigurationError, ResponseError, TransportError
+
+PREP = dict(query_id='q', sql='SELECT ? AS n', parameters=[1], diagnostics=[], plan='plan')
+RESULT = dict(**PREP, columns=['n', 'n'], types=['BIGINT', 'DECIMAL(20,2)'],
+              rows=[['9007199254740993', '123.45']], truncated=True, elapsed_ms=1.2, source_snapshot=4)
+
+
+class ClientTests(unittest.TestCase):
+    def client(self, handler):
+        factory = httpx.Client
+        with patch('periplus_sdk.client.httpx.Client', side_effect=lambda **kw:
+                   factory(**kw, transport=httpx.MockTransport(handler))):
+            client = Client('https://public.example/prefix/')
+        self.addCleanup(client.close)
+        return client
+
+    def test_public_routes_values_and_no_credentials(self):
+        requests = []
+        def handler(request):
+            requests.append(request)
+            self.assertNotIn('authorization', request.headers)
+            self.assertEqual(request.headers['x-periplus-query-source'], 'sdk')
+            if request.url.path.endswith('helpers'):
+                return httpx.Response(200, json={'catalogue_version': '3.0.0', 'helpers': []})
+            self.assertEqual(json.loads(request.content), {'sql': PREP['sql'], 'parameters': [1]})
+            return httpx.Response(200, json=RESULT if request.url.path.endswith('exec') else PREP)
+        with patch.dict(os.environ, {'PERIPLUS_QUERY_API_TOKEN': 'secret', 'PERIPLUS_API_TOKEN': 'admin'}):
+            client = self.client(handler)
+            self.assertEqual(client.prepare(PREP['sql'], [1]).plan, 'plan')
+            result = client.execute(PREP['sql'], [1])
+            self.assertEqual(result.rows, RESULT['rows'])
+            self.assertEqual(result.columns, ['n', 'n'])
+            self.assertTrue(result.truncated)
+            self.assertEqual(result.source_snapshot, 4)
+            self.assertEqual(client.helpers().catalogue_version, '3.0.0')
+        self.assertEqual([r.url.path for r in requests], ['/prefix/api/query/prep', '/prefix/api/query/exec', '/prefix/api/query/helpers'])
+
+    def test_errors_preserve_categories_and_never_retry(self):
+        for status, body, code in [(429, {'code': 'service_busy', 'detail': 'Busy'}, 'service_busy'),
+                                   (403, {'code': 'feature_disabled', 'detail': 'Disabled'}, 'feature_disabled'),
+                                   (503, {'detail': {'code': 'access_unavailable', 'detail': 'Offline'}}, 'access_unavailable'),
+                                   (422, {'detail': [{'msg': 'Invalid'}]}, None)]:
+            calls = []
+            def handler(request):
+                calls.append(request)
+                return httpx.Response(status, json=body, headers={'Retry-After': '2'})
+            with self.subTest(status=status), self.client(handler) as client:
+                with self.assertRaises(ApiError) as raised:
+                    client.execute('SELECT 1')
+                self.assertEqual(raised.exception.status_code, status)
+                self.assertEqual(raised.exception.code, code)
+                self.assertEqual(raised.exception.retry_after_seconds, 2)
+                self.assertEqual(len(calls), 1)
+
+    def test_malformed_response_redirect_and_transport_error(self):
+        for response in [httpx.Response(200, text='<html>'), httpx.Response(200, json={})]:
+            with self.client(lambda request: response) as client:
+                with self.assertRaises(ResponseError):
+                    client.execute('SELECT 1')
+        with self.client(lambda request: httpx.Response(302, headers={'Location': 'https://other.example'})) as client:
+            with self.assertRaises(ApiError):
+                client.helpers()
+        def fail(request):
+            raise httpx.ReadTimeout('contains sensitive origin', request=request)
+        with self.client(fail) as client:
+            with self.assertRaisesRegex(TransportError, 'Could not complete'):
+                client.execute('SELECT 1')
+
+    def test_configuration_and_removed_privileged_api(self):
+        for url in ['', 'postgres://host', 'https://user:secret@host', 'https://host/?token=secret', 'https://host/#a']:
+            with patch.dict(os.environ, {}, clear=True), self.subTest(url=url):
+                with self.assertRaises(ConfigurationError):
+                    Client(url)
+        for timeout in [0, -1, float('nan'), float('inf')]:
+            with self.assertRaises(ConfigurationError):
+                Client('https://public.example', timeout=timeout)
+        with patch.dict(os.environ, {'PERIPLUS_PUBLIC_URL': 'https://public.example'}):
+            with Client() as client:
+                self.assertEqual(str(client._http.base_url), 'https://public.example/')
+        import periplus_sdk
+        self.assertFalse(hasattr(periplus_sdk, 'conn'))
+        self.assertFalse(hasattr(periplus_sdk, 'collections'))
+        self.assertFalse(hasattr(periplus_sdk, 'frontier'))
+
+
+class AsyncClientTests(unittest.IsolatedAsyncioTestCase):
+    async def test_async_parity_and_close(self):
+        factory = httpx.AsyncClient
+        calls = []
+        def handler(request):
+            calls.append(request)
+            if request.url.path.endswith('helpers'):
+                return httpx.Response(200, json={'catalogue_version': '3.0.0', 'helpers': []})
+            return httpx.Response(200, json=RESULT if request.url.path.endswith('exec') else PREP)
+        with patch('periplus_sdk.client.httpx.AsyncClient', side_effect=lambda **kw:
+                   factory(**kw, transport=httpx.MockTransport(handler))):
+            async with AsyncClient('https://public.example') as client:
+                self.assertEqual((await client.prepare('SELECT ?', [1])).parameters, [1])
+                self.assertEqual((await client.execute('SELECT ?', [1])).rows, RESULT['rows'])
+                self.assertEqual((await client.helpers()).catalogue_version, '3.0.0')
+        self.assertTrue(client._http.is_closed)
+        self.assertEqual(len(calls), 3)
+        self.assertTrue(all(r.headers['x-periplus-query-source'] == 'sdk' for r in calls))