periplus-python-sdk 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

periplus_python_sdk-0.5.0.dist-info/METADATA

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: periplus-python-sdk
+Version: 0.5.0
+Summary: Read-only Python client for the public Periplus query API
+License-Expression: Apache-2.0
+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
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic<3,>=2.12
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy<3,>=2.0; extra == "sqlalchemy"
+Provides-Extra: notebook
+Requires-Dist: sqlalchemy<3,>=2.0; extra == "notebook"
+Requires-Dist: marimo[sql]>=0.24.1; extra == "notebook"
+Dynamic: license-file
+
+# 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 capture_id FROM public_v1.capture 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()`.
+
+## Marimo SQL cells and schema browser
+
+Install the notebook integration from PyPI:
+
+```sh
+uv add "periplus-python-sdk[notebook]>=0.5.0"
+```
+
+In a Python setup cell, create a SQLAlchemy engine:
+
+```python
+from sqlalchemy import create_engine
+
+pp = create_engine(
+    "periplus:///public_v1",
+    connect_args={"base_url": "https://periplus.dev", "mode": "stable"},
+)
+```
+
+Add a SQL cell, select **pp** in its connection dropdown, and enter:
+
+```sql
+SELECT capture_id, requested_url
+FROM public_v1.capture
+LIMIT 10
+```
+
+Marimo displays the result as a table. Expand **pp → public_v1** in Data Sources
+to discover views and expand a view to load its columns for SQL completion.
+Discovery uses bounded `SHOW TABLES` and `DESCRIBE` through the same public API;
+no internal catalogue or storage credentials are used. Truncated discovery fails
+explicitly rather than displaying a silently incomplete schema. To eagerly load
+schemas and views, enable their discovery in marimo's Packages & Data settings.
+Column discovery is on demand by default, to avoid many public API requests.
+
+The Python equivalent of a SQL cell is:
+
+```python
+import marimo as mo
+
+captures = mo.sql(
+    "SELECT capture_id FROM public_v1.capture LIMIT 10",
+    engine=pp,
+)
+```
+
+Set `mode="experimental"` in `connect_args` for the experimental service. The URL
+path names the public schema; the HTTPS endpoint belongs in `base_url` (or set
+`PERIPLUS_PUBLIC_URL`). Run `pp.dispose()` when finished. This is a read-only
+SQLAlchemy dialect for textual SQL and reflection, not a writable ORM backend.
+Each statement has its own server snapshot; SQLAlchemy transaction blocks do not
+provide a shared snapshot or rollback. The adapter makes no transaction requests.
+
+A complete notebook is in `examples/notebook.py`. The integration is tested with
+marimo 0.24.1 and SQLAlchemy 2.x. For SQLAlchemy without marimo, install the
+`sqlalchemy` extra instead of `notebook`.
+
+## DB-API connection
+
+For SQL cells without schema browsing, or standard cursor-based Python code:
+
+```python
+from periplus_sdk import connect
+
+with connect("https://periplus.dev", mode="stable") as connection:
+    with connection.cursor() as cursor:
+        cursor.execute("SELECT capture_id FROM public_v1.capture LIMIT ?", [10])
+        print(cursor.description)
+        print(cursor.fetchall())
+        print(cursor.result.source_snapshot)
+```
+
+Connections expose `cursor`, `execute`, `close`, and context managers. Cursors
+support `execute`, `fetchone`, `fetchmany`, `fetchall`, iteration, and close.
+Use positional `?` parameters. Decimal and temporal parameters are sent as
+strings; use explicit SQL casts. Binary and nested parameters are not supported
+by this adapter. Fetching only consumes the bounded result already received;
+it never issues pagination or retries. Connections/cursors are not thread-shared.
+`commit()` is a no-op; `rollback()` and `executemany()` are unsupported.
+
+`cursor.result` preserves the original query response. `connection.last_result`
+also retains it after marimo closes a cursor; a new execution clears it first.
+Truncation emits `periplus_sdk.dbapi.TruncationWarning` and sets `rowcount` to -1.
+DB-API failures use the standard exception hierarchy in `periplus_sdk.dbapi`;
+HTTP errors retain `status_code`, `code`, and `retry_after_seconds`.
+
+Scalar integer, floating-point, decimal, date, time, timestamp and BLOB results
+are decoded to Python values. UUIDs remain strings. Nested/other SQL types keep
+their JSON wire representation; out-of-range dates/timestamps remain strings.
+Temporal precision is limited to what the server JSON transport preserves.
+The cursor preserves duplicate column names, but dataframe libraries/marimo may
+not: use unique SQL aliases. Dataframe inference can lose types for empty or
+all-null results; `cursor.description` retains the SQL type names.
+
+## Stable and experimental APIs
+
+Both clients accept `mode="stable"` (the default) or `mode="experimental"` at initialization:
+
+```python
+with Client("https://periplus.dev", mode="experimental") as client:
+    result = client.execute("SELECT capture_id FROM public_v1.capture LIMIT 1")
+    print(result.query_mode, result.compiler_version, result.optimizations)
+```
+
+The selected mode applies to preparation, execution, and helper discovery. Experimental
+requests use the public application's `/api/query/experimental/` routes. There is no
+automatic fallback to stable if the experimental service is unavailable.
+`AsyncClient` accepts the same option. Invalid modes raise `ConfigurationError`.
+
+## Preparation and helpers
+
+```python
+with Client("http://localhost:8080") as client:
+    prepared = client.prepare("SELECT capture_id FROM public_v1.capture 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 capture_id FROM public_v1.capture 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 the public-v1 client from PyPI:
+
+```sh
+python -m pip install "periplus-python-sdk>=0.5.0"
+```
+
+Version 0.5.0 supports the current public-v1 contract. For production, configure
+`PERIPLUS_PUBLIC_URL=https://periplus.dev`; no API token is required.
+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.5.0` is released with:
+
+```sh
+git tag periplus-python-sdk-v0.5.0
+git push origin periplus-python-sdk-v0.5.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.
+
+## Public v1
+
+Install the updated SDK from PyPI with `python -m pip install "periplus-python-sdk>=0.5.0"`. The previously published 0.2.0 release predates this contract. `prepare` and `execute` accept keyword-only `schema_version="public_v1"` (the default); responses preserve `schema_version` separately from `source_snapshot`. Unavailable versions are rejected by the server.
+
+## License
+
+Copyright (c) 2026 Ekku Leivonen (elei.io). Licensed under [Apache-2.0](LICENSE);
+see [NOTICE](NOTICE). The server and other repository packages have separate
+licensing described in the root LICENSING.md.

periplus_python_sdk-0.5.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+periplus_python_sdk-0.5.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+periplus_python_sdk-0.5.0.dist-info/licenses/NOTICE,sha256=bhbYSqcUB3U_P1-XzloiT81JGniqoYaRLxNkQ1Pm9MQ,52
+periplus_sdk/__init__.py,sha256=WimXYlPB6tCimBO4VSwhcp00dwSL87jMmMuQ4-kINfM,546
+periplus_sdk/client.py,sha256=ZwMmVJKNF-FrGh_qwiQ5myhu8XJodb_96ohkqK47yDA,6557
+periplus_sdk/dbapi.py,sha256=lK9ZROaMKXm26wvC7DCKywm3qwSvqeHa7zkktnJVP80,11244
+periplus_sdk/errors.py,sha256=rB1n-v8Hc2tu2dtHivz-MlqsCoRC5pTcWogTfM7SMLw,855
+periplus_sdk/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+periplus_sdk/sqlalchemy.py,sha256=axFpEMnMP9uSxbsxzVNSUHNh41q2NruSX8W_5E8F59Q,4877
+periplus_sdk/types.py,sha256=PTdJO6BYTY97dBd3HMEZ52k6P9s0cMvidjpnc8zUpy4,1045
+periplus_python_sdk-0.5.0.dist-info/METADATA,sha256=-3wrgS0gK18Kf6UGV9jrVu2rhm2K51q6ScgZUyiOB7U,10091
+periplus_python_sdk-0.5.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+periplus_python_sdk-0.5.0.dist-info/entry_points.txt,sha256=Pr14L_7AhLinq-4qDxB4awFVubrvR1BEfkaFVRpdCbU,73
+periplus_python_sdk-0.5.0.dist-info/top_level.txt,sha256=o41t5TzwgoxzSmbKoP6olWW1FyEAGWVYTjeoKadBK40,13
+periplus_python_sdk-0.5.0.dist-info/RECORD,,

periplus_python_sdk-0.5.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[sqlalchemy.dialects]
+periplus = periplus_sdk.sqlalchemy:PeriplusDialect

periplus_sdk/__init__.py

@@ -1,8 +1,9 @@
 """Read-only Python clients for the public Periplus query API."""
+from .dbapi import connect
 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",
+__all__ = ["connect", "AsyncClient", "Client", "ApiError", "ConfigurationError", "PeriplusError",
            "ResponseError", "TransportError", "Diagnostic", "PreparedQuery", "QueryHelper",
            "QueryHelpers", "QueryResult"]

periplus_sdk/client.py

@@ -6,7 +6,7 @@ from datetime import UTC, datetime
 from email.utils import parsedate_to_datetime
 import math
 import os
-from typing import TypeVar
+from typing import Literal, TypeVar
 
 import httpx
 from pydantic import BaseModel, JsonValue, ValidationError
@@ -79,7 +79,10 @@ def _payload(sql: str, parameters: Sequence[JsonValue] | None, schema_version: s
 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):
+    def __init__(self, base_url: str | None = None, *, timeout: float = 140, mode: Literal["stable", "experimental"] = "stable"):
+        if mode not in {"stable", "experimental"}:
+            raise ConfigurationError("mode must be stable or experimental.")
+        self._query_path = "api/query/experimental/" if mode == "experimental" else "api/query/"
         self._http = httpx.Client(**_options(base_url, timeout))
 
     def __enter__(self) -> Client:
@@ -93,7 +96,7 @@ class Client:
 
     def _request(self, method: str, path: str, model: type[Model], **kwargs) -> Model:
         try:
-            response = self._http.request(method, "api/query/" + path, **kwargs)
+            response = self._http.request(method, self._query_path + path, **kwargs)
         except httpx.RequestError:
             raise TransportError("Could not complete the public query request.") from None
         return _decode(response, model)
@@ -111,7 +114,10 @@ class Client:
 class AsyncClient:
     """Reusable asynchronous public query client. Use an async with block."""
 
-    def __init__(self, base_url: str | None = None, *, timeout: float = 140):
+    def __init__(self, base_url: str | None = None, *, timeout: float = 140, mode: Literal["stable", "experimental"] = "stable"):
+        if mode not in {"stable", "experimental"}:
+            raise ConfigurationError("mode must be stable or experimental.")
+        self._query_path = "api/query/experimental/" if mode == "experimental" else "api/query/"
         self._http = httpx.AsyncClient(**_options(base_url, timeout))
 
     async def __aenter__(self) -> AsyncClient:
@@ -125,7 +131,7 @@ class AsyncClient:
 
     async def _request(self, method: str, path: str, model: type[Model], **kwargs) -> Model:
         try:
-            response = await self._http.request(method, "api/query/" + path, **kwargs)
+            response = await self._http.request(method, self._query_path + path, **kwargs)
         except httpx.RequestError:
             raise TransportError("Could not complete the public query request.") from None
         return _decode(response, model)

periplus_sdk/dbapi.py

@@ -0,0 +1,324 @@
+"""Read-only DB-API 2.0 connection over the public query API.
+
+Each execute is an independent server snapshot. Fetching consumes a bounded local
+result, never a remote cursor. Connections and cursors must not be shared by threads.
+"""
+from __future__ import annotations
+
+import base64
+import builtins
+from collections.abc import Sequence
+from datetime import date, datetime, time
+from decimal import Decimal
+from typing import Any, Literal
+import warnings
+
+from .client import Client
+from .errors import ApiError, ConfigurationError, PeriplusError, ResponseError, TransportError
+from .types import QueryResult
+
+apilevel = "2.0"
+threadsafety = 1
+paramstyle = "qmark"
+
+
+class Warning(builtins.Warning):
+    """DB-API warning."""
+
+
+class TruncationWarning(Warning):
+    """The server returned only part of the query result."""
+
+
+class Error(PeriplusError):
+    """Base DB-API error; API failures preserve their safe error attributes."""
+
+    def __init__(self, message: str, *, status_code: int | None = None,
+                 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
+
+
+class InterfaceError(Error):
+    """Invalid connection or wire response."""
+
+
+class DatabaseError(Error):
+    """Query failure."""
+
+
+class DataError(DatabaseError):
+    """A value cannot be represented."""
+
+
+class OperationalError(DatabaseError):
+    """Service, policy or transport failure."""
+
+
+class IntegrityError(DatabaseError):
+    """Integrity constraint failure."""
+
+
+class InternalError(DatabaseError):
+    """Internal query failure."""
+
+
+class ProgrammingError(DatabaseError):
+    """Invalid SQL, parameters or cursor use."""
+
+
+class NotSupportedError(DatabaseError):
+    """Operation is outside the read-only query contract."""
+
+
+Date = date
+Time = time
+Timestamp = datetime
+Binary = bytes
+
+
+def DateFromTicks(ticks: float) -> date:
+    return datetime.fromtimestamp(ticks).date()
+
+
+def TimeFromTicks(ticks: float) -> time:
+    return datetime.fromtimestamp(ticks).time()
+
+
+def TimestampFromTicks(ticks: float) -> datetime:
+    return datetime.fromtimestamp(ticks)
+
+
+_INTEGER_TYPES = {"TINYINT", "SMALLINT", "INTEGER", "BIGINT", "HUGEINT", "UTINYINT",
+                  "USMALLINT", "UINTEGER", "UBIGINT", "UHUGEINT", "BIGNUM"}
+_FLOAT_TYPES = {"FLOAT", "DOUBLE", "REAL"}
+_TIME_TYPES = {"TIME", "TIME WITH TIME ZONE", "TIMETZ"}
+_TIMESTAMP_TYPES = {"TIMESTAMP", "TIMESTAMP_S", "TIMESTAMP_MS", "TIMESTAMP_NS",
+                    "TIMESTAMP WITH TIME ZONE", "TIMESTAMPTZ"}
+
+
+class _TypeCategory:
+    def __init__(self, names: set[str], prefix: str = ""):
+        self.names, self.prefix = names, prefix
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, str) and (other in self.names or bool(self.prefix and other.startswith(self.prefix)))
+
+
+STRING = _TypeCategory({"VARCHAR", "UUID", "JSON", "ENUM"})
+BINARY = _TypeCategory({"BLOB"})
+NUMBER = _TypeCategory(_INTEGER_TYPES | _FLOAT_TYPES | {"BOOLEAN"}, "DECIMAL(")
+DATETIME = _TypeCategory({"DATE"} | _TIME_TYPES | _TIMESTAMP_TYPES)
+ROWID = _TypeCategory(set())
+
+
+def _value(value: Any, sql_type: str) -> Any:
+    if value is None:
+        return None
+    if sql_type in _INTEGER_TYPES:
+        return int(value)
+    if sql_type in _FLOAT_TYPES:
+        return float(value)
+    if sql_type.startswith("DECIMAL("):
+        return Decimal(str(value))
+    # Preserve infinities and out-of-range dates rather than clipping them.
+    if sql_type == "DATE":
+        try:
+            return date.fromisoformat(value)
+        except ValueError:
+            return value
+    if sql_type in _TIME_TYPES:
+        return time.fromisoformat(value)
+    if sql_type in _TIMESTAMP_TYPES:
+        try:
+            return datetime.fromisoformat(value)
+        except ValueError:
+            return value
+    if sql_type == "BLOB":
+        return base64.b64decode(value, validate=True)
+    # UUIDs remain strings, and nested/other types retain their JSON wire values.
+    return value
+
+
+def _parameter(value: Any) -> Any:
+    if value is None or isinstance(value, (str, bool, int, float)):
+        return value
+    if isinstance(value, (Decimal, date, time)):
+        return str(value) if isinstance(value, Decimal) else value.isoformat()
+    raise ProgrammingError("Parameters must be scalar JSON values, Decimal, date, time or datetime; use explicit SQL casts for typed strings.")
+
+
+class Connection:
+    """Marimo-discoverable, read-only connection; commit is a no-op."""
+
+    dialect = "duckdb"
+
+    def __init__(self, base_url: str | None = None, *, timeout: float = 140,
+                 mode: Literal["stable", "experimental"] = "stable",
+                 schema_version: str = "public_v1"):
+        try:
+            self._client = Client(base_url, timeout=timeout, mode=mode)
+        except ConfigurationError as exc:
+            raise InterfaceError(str(exc)) from exc
+        self.schema_version = schema_version
+        self.closed = False
+        self.last_result: QueryResult | None = None
+
+    def _check(self) -> None:
+        if self.closed:
+            raise InterfaceError("Connection is closed.")
+
+    def cursor(self) -> Cursor:
+        self._check()
+        return Cursor(self)
+
+    def execute(self, operation: str, parameters: Sequence[Any] | None = None) -> Cursor:
+        cursor = self.cursor()
+        try:
+            return cursor.execute(operation, parameters)
+        except BaseException:
+            cursor.close()
+            raise
+
+    def commit(self) -> None:
+        """No-op: each read executes in its own server transaction."""
+        self._check()
+
+    def rollback(self) -> None:
+        self._check()
+        raise NotSupportedError("Periplus has no client transactions to roll back.")
+
+    def close(self) -> None:
+        if not self.closed:
+            self._client.close()
+            self.closed = True
+            self.last_result = None
+
+    def __enter__(self) -> Connection:
+        self._check()
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+def connect(base_url: str | None = None, *, timeout: float = 140,
+            mode: Literal["stable", "experimental"] = "stable",
+            schema_version: str = "public_v1") -> Connection:
+    return Connection(base_url, timeout=timeout, mode=mode, schema_version=schema_version)
+
+
+class Cursor:
+    """A buffered result. Metadata stays on result after rows are consumed."""
+
+    arraysize = 1
+
+    def __init__(self, connection: Connection):
+        self.connection = connection
+        self.closed = False
+        self.result: QueryResult | None = None
+        self.description: list[tuple[Any, ...]] | None = None
+        self.rowcount = -1
+        self._rows: list[tuple[Any, ...]] = []
+        self._position = 0
+
+    def _check(self, *, result: bool = False) -> None:
+        self.connection._check()
+        if self.closed:
+            raise InterfaceError("Cursor is closed.")
+        if result and self.result is None:
+            raise ProgrammingError("Execute a query before fetching rows.")
+
+    def execute(self, operation: str, parameters: Sequence[Any] | None = None) -> Cursor:
+        self._check()
+        self.result, self.description, self.rowcount = None, None, -1
+        self._rows, self._position = [], 0
+        self.connection.last_result = None
+        if not isinstance(operation, str):
+            raise ProgrammingError("SQL must be a string.")
+        if parameters is not None and (not isinstance(parameters, Sequence) or isinstance(parameters, (str, bytes))):
+            raise ProgrammingError("Use a positional parameter sequence with ? placeholders.")
+        values = [_parameter(v) for v in parameters] if parameters is not None else []
+        try:
+            result = self.connection._client.execute(operation, values, schema_version=self.connection.schema_version)
+        except ApiError as exc:
+            error = ProgrammingError if exc.code == "sql_invalid" else OperationalError
+            raise error(str(exc), status_code=exc.status_code, code=exc.code,
+                        retry_after_seconds=exc.retry_after_seconds) from exc
+        except TransportError as exc:
+            raise OperationalError(str(exc)) from exc
+        except ResponseError as exc:
+            raise InterfaceError(str(exc)) from exc
+        if len(result.columns) != len(result.types) or any(len(r) != len(result.columns) for r in result.rows):
+            raise InterfaceError("Query columns, types and rows have inconsistent widths.")
+        try:
+            rows = [tuple(_value(v, t) for v, t in zip(row, result.types, strict=True)) for row in result.rows]
+        except (ValueError, TypeError, ArithmeticError) as exc:
+            raise DataError("Query value does not match its SQL type.") from exc
+        self.result = self.connection.last_result = result
+        self.description = [(name, kind, None, None, None, None, None)
+                            for name, kind in zip(result.columns, result.types, strict=True)]
+        self._rows = rows
+        self.rowcount = -1 if result.truncated else len(rows)
+        if result.truncated:
+            warnings.warn(f"Periplus returned a truncated result ({len(rows)} rows); inspect connection.last_result or cursor.result. Fetching does not retrieve additional rows.",
+                          TruncationWarning, stacklevel=2)
+        return self
+
+    def fetchone(self) -> tuple[Any, ...] | None:
+        self._check(result=True)
+        if self._position == len(self._rows):
+            return None
+        row = self._rows[self._position]
+        self._position += 1
+        return row
+
+    def fetchmany(self, size: int | None = None) -> list[tuple[Any, ...]]:
+        self._check(result=True)
+        size = self.arraysize if size is None else size
+        if not isinstance(size, int) or size < 0:
+            raise ProgrammingError("Fetch size must be a non-negative integer.")
+        end = min(self._position + size, len(self._rows))
+        rows = self._rows[self._position:end]
+        self._position = end
+        return rows
+
+    def fetchall(self) -> list[tuple[Any, ...]]:
+        self._check(result=True)
+        return self.fetchmany(len(self._rows) - self._position)
+
+    def executemany(self, operation: str, seq_of_parameters: Any) -> None:
+        self._check()
+        raise NotSupportedError("Batch execution is not supported by the read-only query API.")
+
+    def setinputsizes(self, sizes: Any) -> None:
+        self._check()
+
+    def setoutputsize(self, size: int, column: int | None = None) -> None:
+        self._check()
+
+    def close(self) -> None:
+        self.closed = True
+        self._rows = []
+        self.result = None
+        self.description = None
+        self.rowcount = -1
+
+    def __iter__(self) -> Cursor:
+        self._check(result=True)
+        return self
+
+    def __next__(self) -> tuple[Any, ...]:
+        row = self.fetchone()
+        if row is None:
+            raise StopIteration
+        return row
+
+    def __enter__(self) -> Cursor:
+        self._check()
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

periplus_sdk/sqlalchemy.py

@@ -0,0 +1,139 @@
+"""SQLAlchemy dialect for public Periplus queries and bounded reflection."""
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import exc, types
+from sqlalchemy.engine import default
+from sqlalchemy.engine.reflection import cache
+from sqlalchemy.sql.compiler import IdentifierPreparer
+
+from . import dbapi
+
+
+class SQLType(types.UserDefinedType):
+    """Preserve DuckDB type names, including nested types, during reflection."""
+
+    cache_ok = True
+
+    def __init__(self, name: str):
+        self.name = name
+
+    def get_col_spec(self, **kw: Any) -> str:
+        return self.name
+
+    @property
+    def python_type(self) -> type:
+        if self.name in dbapi._INTEGER_TYPES:
+            return int
+        if self.name in dbapi._FLOAT_TYPES:
+            return float
+        if self.name == "BOOLEAN":
+            return bool
+        if self.name.startswith("DECIMAL("):
+            return dbapi.Decimal
+        if self.name == "DATE":
+            return dbapi.date
+        if self.name in dbapi._TIMESTAMP_TYPES:
+            return dbapi.datetime
+        if self.name in dbapi._TIME_TYPES:
+            return dbapi.time
+        if self.name == "BLOB":
+            return bytes
+        return str
+
+
+class PeriplusDialect(default.DefaultDialect):
+    # The server speaks DuckDB SQL; this enables the correct notebook SQL dialect.
+    name = "duckdb"
+    driver = "periplus"
+    supports_statement_cache = False
+    supports_sane_rowcount = False
+    supports_sane_multi_rowcount = False
+    supports_native_decimal = True
+    default_paramstyle = "qmark"
+    preparer = IdentifierPreparer
+
+    @classmethod
+    def import_dbapi(cls):
+        return dbapi
+
+    def create_connect_args(self, url):
+        if url.username or url.password or url.host or url.port:
+            raise exc.ArgumentError("Use periplus:///public_v1 with base_url and mode in connect_args.")
+        if url.query:
+            raise exc.ArgumentError("Pass connection options in connect_args, not URL query parameters.")
+        return [], {"schema_version": url.database or "public_v1"}
+
+    def initialize(self, connection):
+        self.default_schema_name = connection.connection.dbapi_connection.schema_version
+
+    def do_rollback(self, dbapi_connection):
+        # SQLAlchemy resets pooled connections this way. There is no remote
+        # transaction: each read already completed in its own server snapshot.
+        pass
+
+    def do_begin(self, dbapi_connection):
+        pass
+
+    def do_commit(self, dbapi_connection):
+        dbapi_connection.commit()
+
+    def _schema(self, connection, schema):
+        current = connection.connection.dbapi_connection.schema_version
+        if schema is not None and schema != current:
+            raise exc.InvalidRequestError(f"Only the configured public schema {current!r} is available.")
+        return current
+
+    @cache
+    def get_schema_names(self, connection, **kw):
+        return [self._schema(connection, None)]
+
+    def _complete(self, result):
+        raw = result.cursor.result
+        if raw.truncated:
+            result.close()
+            raise exc.InvalidRequestError("Catalogue discovery was truncated by public query limits; refusing an incomplete schema.")
+        try:
+            return result.fetchall()
+        finally:
+            result.close()
+
+    @cache
+    def get_view_names(self, connection, schema=None, **kw):
+        schema = self._schema(connection, schema)
+        result = connection.exec_driver_sql(f"SHOW TABLES FROM {self.identifier_preparer.quote_identifier(schema)}")
+        return [row[0] for row in self._complete(result)]
+
+    @cache
+    def get_table_names(self, connection, schema=None, **kw):
+        self._schema(connection, schema)
+        # All queryable public catalogue relations are views.
+        return []
+
+    @cache
+    def has_table(self, connection, table_name, schema=None, **kw):
+        return table_name in self.get_view_names(connection, schema)
+
+    @cache
+    def get_columns(self, connection, table_name, schema=None, **kw):
+        schema = self._schema(connection, schema)
+        quote = self.identifier_preparer.quote_identifier
+        result = connection.exec_driver_sql(f"DESCRIBE {quote(schema)}.{quote(table_name)}")
+        return [{"name": row[0], "type": SQLType(row[1]), "nullable": row[2] != "NO",
+                 "default": row[4]} for row in self._complete(result)]
+
+    @cache
+    def get_pk_constraint(self, connection, table_name, schema=None, **kw):
+        self._schema(connection, schema)
+        return {"name": None, "constrained_columns": []}
+
+    @cache
+    def get_foreign_keys(self, connection, table_name, schema=None, **kw):
+        self._schema(connection, schema)
+        return []
+
+    @cache
+    def get_indexes(self, connection, table_name, schema=None, **kw):
+        self._schema(connection, schema)
+        return []

periplus_sdk/types.py

@@ -1,4 +1,6 @@
 """Public query wire types; SQL types and JSON values are preserved."""
+from typing import Literal
+
 from pydantic import BaseModel, Field, JsonValue
 
 
@@ -9,6 +11,9 @@ class Diagnostic(BaseModel):
 
 
 class PreparedQuery(BaseModel):
+    query_mode: Literal["stable", "experimental"]
+    compiler_version: str
+    optimizations: list[str]
     schema_version: str
     query_id: str
     sql: str

periplus_python_sdk-0.3.0.dist-info/METADATA

@@ -1,123 +0,0 @@
-Metadata-Version: 2.4
-Name: periplus-python-sdk
-Version: 0.3.0
-Summary: Read-only Python client for the public Periplus query API
-License-Expression: Apache-2.0
-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
-License-File: LICENSE
-License-File: NOTICE
-Requires-Dist: httpx>=0.28
-Requires-Dist: pydantic<3,>=2.12
-Dynamic: license-file
-
-# 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 capture_id FROM public_v1.capture 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 capture_id FROM public_v1.capture 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 capture_id FROM public_v1.capture 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 the public-v1 client from PyPI:
-
-```sh
-python -m pip install "periplus-python-sdk>=0.3.0"
-```
-
-Version 0.3.0 supports the current public-v1 contract. For production, configure
-`PERIPLUS_PUBLIC_URL=https://periplus.dev`; no API token is required.
-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.3.0` is released with:
-
-```sh
-git tag periplus-python-sdk-v0.3.0
-git push origin periplus-python-sdk-v0.3.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.
-
-## Public v1
-
-Install the updated SDK from PyPI with `python -m pip install "periplus-python-sdk>=0.3.0"`. The previously published 0.2.0 release predates this contract. `prepare` and `execute` accept keyword-only `schema_version="public_v1"` (the default); responses preserve `schema_version` separately from `source_snapshot`. Unavailable versions are rejected by the server.
-
-## License
-
-Copyright (c) 2026 Ekku Leivonen (elei.io). Licensed under [Apache-2.0](LICENSE);
-see [NOTICE](NOTICE). The server and other repository packages have separate
-licensing described in the root LICENSING.md.

periplus_python_sdk-0.3.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-periplus_python_sdk-0.3.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-periplus_python_sdk-0.3.0.dist-info/licenses/NOTICE,sha256=bhbYSqcUB3U_P1-XzloiT81JGniqoYaRLxNkQ1Pm9MQ,52
-periplus_sdk/__init__.py,sha256=bcJbEVnslFVfOdR74j7r8V1uap7pSD5KtNF2w-b01XY,508
-periplus_sdk/client.py,sha256=mZBBwR4pCAwylGATbXt2Rqj4YnzkaCpMF5LjoNWiTm8,5986
-periplus_sdk/errors.py,sha256=rB1n-v8Hc2tu2dtHivz-MlqsCoRC5pTcWogTfM7SMLw,855
-periplus_sdk/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-periplus_sdk/types.py,sha256=XmnrUsgOF7nqnPs7OZqqgZMXoAU95sYF8-mHq8_dolo,912
-periplus_python_sdk-0.3.0.dist-info/METADATA,sha256=8pGzaM_NZyFmJ3mppv00Imuov5PyWbM3Q-0eYM1WUpk,5323
-periplus_python_sdk-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-periplus_python_sdk-0.3.0.dist-info/top_level.txt,sha256=o41t5TzwgoxzSmbKoP6olWW1FyEAGWVYTjeoKadBK40,13
-periplus_python_sdk-0.3.0.dist-info/RECORD,,