periplus-python-sdk 0.7.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

periplus_python_sdk-0.8.0.dist-info/METADATA

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: periplus-python-sdk
+Version: 0.8.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
+Requires-Dist: sqlalchemy<3,>=2.0
+Provides-Extra: notebook
+Requires-Dist: marimo[sql]>=0.24.1; extra == "notebook"
+Dynamic: license-file
+
+# Periplus Python SDK
+
+Read-only access to the public ClickHouse corpus through the Periplus HTTP API.
+Install the SDK from the same checkout as your deployment:
+
+```sh
+python -m pip install ./packages/periplus-python-sdk
+```
+
+```python
+from periplus_sdk import Client
+
+with Client("http://localhost:8080") as client:
+    result = client.execute(
+        "SELECT capture_id, url FROM public_v1.captures LIMIT ?", [10]
+    )
+    print(result.columns, result.rows)
+```
+
+Use `PERIPLUS_PUBLIC_URL` to omit the URL argument. No database credentials or
+service token are needed for the public gateway. `AsyncClient` provides async
+methods. `prepare` validates/explains SQL; `execute` returns typed columns, rows,
+truncation and query metadata; `helpers` describes the installed public views.
+
+The public schema is `public_v1`. HTML joins use `document_id` plus node index;
+`document_id` identifies retained bytes and their HTML interpretation. Raw-byte hashes stay internal.
+There is one query endpoint, with no experimental fallback. Client errors preserve
+server categories and do not automatically retry executed queries.
+
+For notebook/SQLAlchemy integration:
+
+```python
+from periplus_sdk import sql_api
+from sqlalchemy import text
+
+engine = sql_api.create_engine(base_url="http://localhost:8080")
+with engine.connect() as connection:
+    print(connection.execute(text("SELECT url FROM public_v1.captures LIMIT 5")).all())
+engine.dispose()
+```
+
+Marimo discovers the five public views through the helper catalogue. Column
+reflection uses `SELECT * ... LIMIT 0` to retrieve native types without reading
+corpus rows; no `SHOW`, `DESCRIBE`, or system-table access is required.
+
+The DB-API connection advertises the ClickHouse dialect and converts native
+nullable integer, decimal, date and datetime types. Nested types retain JSON wire
+values. It is read-only: there are no client transactions or writable sessions.
+Streaming cursors expose incomplete/truncated results explicitly; configure
+`allow_partial` only when partial results suit the application.
+
+See [the public schema](../../docs/SCHEMA.md) and [query boundary](../../docs/QUERY.md).

periplus_python_sdk-0.8.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+periplus_python_sdk-0.8.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+periplus_python_sdk-0.8.0.dist-info/licenses/NOTICE,sha256=bhbYSqcUB3U_P1-XzloiT81JGniqoYaRLxNkQ1Pm9MQ,52
+periplus_sdk/__init__.py,sha256=WimXYlPB6tCimBO4VSwhcp00dwSL87jMmMuQ4-kINfM,546
+periplus_sdk/client.py,sha256=trcsOL4hnpDByMr8wZ9iz2vzxQWCW60vSYTmpqCj1Gs,7745
+periplus_sdk/dbapi.py,sha256=yDrL2CV7tI3Pawp9hN2czFYqrbXF8ret0Jk4VHRHoYg,12014
+periplus_sdk/errors.py,sha256=rB1n-v8Hc2tu2dtHivz-MlqsCoRC5pTcWogTfM7SMLw,855
+periplus_sdk/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+periplus_sdk/sql_api.py,sha256=vRQXzBIcJOUg_eZzzRs7cpE3xygxK5Jo7YfYWN4NxBg,1868
+periplus_sdk/sqlalchemy.py,sha256=e9j4nI_JQ5EDwMOK6WawX1W_QrOnaY3Wa8LchIIJJio,5567
+periplus_sdk/stream.py,sha256=7gOYOMpfeB7NcxQgWjJ6f5NvymYTWhYbPkVdCijSlP8,5218
+periplus_sdk/types.py,sha256=yh_xHwn6TwC45r8eWhxtlrz0w86M5lvhmPOS3QJbXiU,1253
+periplus_python_sdk-0.8.0.dist-info/METADATA,sha256=7A_Jpwq8NJpskMpwQORGPhx-xbMHn_nehsqslBb_6c8,2730
+periplus_python_sdk-0.8.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+periplus_python_sdk-0.8.0.dist-info/entry_points.txt,sha256=Pr14L_7AhLinq-4qDxB4awFVubrvR1BEfkaFVRpdCbU,73
+periplus_python_sdk-0.8.0.dist-info/top_level.txt,sha256=o41t5TzwgoxzSmbKoP6olWW1FyEAGWVYTjeoKadBK40,13
+periplus_python_sdk-0.8.0.dist-info/RECORD,,

periplus_sdk/client.py

@@ -79,10 +79,11 @@ 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 = 620, 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/"
+    def __init__(self, base_url: str | None = None, *, timeout: float = 620, mode: Literal["stable"] = "stable"):
+        if mode not in {"stable"}:
+            raise ConfigurationError("Only the stable public catalogue is available.")
+        self.schema_version = "public_v1"
+        self._query_path = "api/query/"
         self._http = httpx.Client(**_options(base_url, timeout))
 
     def __enter__(self) -> Client:
@@ -101,19 +102,19 @@ class Client:
             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, *, schema_version: str = "public_v1") -> PreparedQuery:
-        return self._request("POST", "prep", PreparedQuery, json=_payload(sql, parameters, schema_version))
+    def prepare(self, sql: str, parameters: Sequence[JsonValue] | None = None, *, schema_version: str | None = None) -> PreparedQuery:
+        return self._request("POST", "prep", PreparedQuery, json=_payload(sql, parameters, schema_version if schema_version is not None else self.schema_version))
 
-    def execute(self, sql: str, parameters: Sequence[JsonValue] | None = None, *, schema_version: str = "public_v1") -> QueryResult:
-        return self._request("POST", "exec", QueryResult, json=_payload(sql, parameters, schema_version))
+    def execute(self, sql: str, parameters: Sequence[JsonValue] | None = None, *, schema_version: str | None = None) -> QueryResult:
+        return self._request("POST", "exec", QueryResult, json=_payload(sql, parameters, schema_version if schema_version is not None else self.schema_version))
 
     def stream(self, sql: str, parameters: Sequence[JsonValue] | None = None, *,
-               schema_version: str = "public_v1", allow_partial: bool = False):
+               schema_version: str | None = None, allow_partial: bool = False):
         """Stream batches from one snapshot; use as a context manager for early exit."""
         from .stream import MEDIA_TYPE, QueryStream
         try:
             request = self._http.build_request("POST", self._query_path + "exec",
-                headers={"accept": MEDIA_TYPE}, json=_payload(sql, parameters, schema_version))
+                headers={"accept": MEDIA_TYPE}, json=_payload(sql, parameters, schema_version if schema_version is not None else self.schema_version))
             response = self._http.send(request, stream=True)
             try:
                 if not response.is_success:
@@ -133,10 +134,11 @@ class Client:
 class AsyncClient:
     """Reusable asynchronous public query client. Use an async with block."""
 
-    def __init__(self, base_url: str | None = None, *, timeout: float = 620, 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/"
+    def __init__(self, base_url: str | None = None, *, timeout: float = 620, mode: Literal["stable"] = "stable"):
+        if mode not in {"stable"}:
+            raise ConfigurationError("Only the stable public catalogue is available.")
+        self.schema_version = "public_v1"
+        self._query_path = "api/query/"
         self._http = httpx.AsyncClient(**_options(base_url, timeout))
 
     async def __aenter__(self) -> AsyncClient:
@@ -155,11 +157,11 @@ class AsyncClient:
             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, *, schema_version: str = "public_v1") -> PreparedQuery:
-        return await self._request("POST", "prep", PreparedQuery, json=_payload(sql, parameters, schema_version))
+    async def prepare(self, sql: str, parameters: Sequence[JsonValue] | None = None, *, schema_version: str | None = None) -> PreparedQuery:
+        return await self._request("POST", "prep", PreparedQuery, json=_payload(sql, parameters, schema_version if schema_version is not None else self.schema_version))
 
-    async def execute(self, sql: str, parameters: Sequence[JsonValue] | None = None, *, schema_version: str = "public_v1") -> QueryResult:
-        return await self._request("POST", "exec", QueryResult, json=_payload(sql, parameters, schema_version))
+    async def execute(self, sql: str, parameters: Sequence[JsonValue] | None = None, *, schema_version: str | None = None) -> QueryResult:
+        return await self._request("POST", "exec", QueryResult, json=_payload(sql, parameters, schema_version if schema_version is not None else self.schema_version))
 
     async def helpers(self) -> QueryHelpers:
         return await self._request("GET", "helpers", QueryHelpers)

periplus_sdk/dbapi.py

@@ -86,54 +86,47 @@ 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"}
+_INTEGER_TYPES = {f'{prefix}Int{bits}' for prefix in ('', 'U') for bits in (8,16,32,64,128,256)}
+_FLOAT_TYPES = {'Float32', 'Float64'}
+
+
+def _base_type(value: str) -> str:
+    while value.startswith(('Nullable(', 'LowCardinality(')):
+        value = value[value.index('(')+1:-1]
+    return value
 
 
 class _TypeCategory:
-    def __init__(self, names: set[str], prefix: str = ""):
-        self.names, self.prefix = names, prefix
+    def __init__(self, names: set[str], prefixes: tuple[str, ...] = ()):
+        self.names, self.prefixes = names, prefixes
 
     def __eq__(self, other: object) -> bool:
-        return isinstance(other, str) and (other in self.names or bool(self.prefix and other.startswith(self.prefix)))
+        if not isinstance(other, str):return False
+        value = _base_type(other)
+        return value in self.names or value.startswith(self.prefixes)
 
 
-STRING = _TypeCategory({"VARCHAR", "UUID", "JSON", "ENUM"})
-BINARY = _TypeCategory({"BLOB"})
-NUMBER = _TypeCategory(_INTEGER_TYPES | _FLOAT_TYPES | {"BOOLEAN"}, "DECIMAL(")
-DATETIME = _TypeCategory({"DATE"} | _TIME_TYPES | _TIMESTAMP_TYPES)
+STRING = _TypeCategory({'String','UUID','JSON'}, ('FixedString(', 'Enum'))
+BINARY = _TypeCategory(set())
+NUMBER = _TypeCategory(_INTEGER_TYPES | _FLOAT_TYPES | {'Bool'}, ('Decimal',))
+DATETIME = _TypeCategory({'Date','Date32'}, ('DateTime','Time'))
 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.
+    if value is None:return None
+    sql_type = _base_type(sql_type)
+    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))
+    if sql_type == 'Bool':return value in (True, 1, '1', 'true')
+    if sql_type in ('Date','Date32'):
+        try:return date.fromisoformat(value)
+        except ValueError:return value
+    if sql_type.startswith('DateTime'):
+        try:return datetime.fromisoformat(value)
+        except ValueError:return value
+    if sql_type.startswith('Time'):return time.fromisoformat(value)
     return value
 
 
@@ -152,16 +145,16 @@ def _parameter(value: Any) -> Any:
 class Connection:
     """Marimo-discoverable, read-only connection; commit is a no-op."""
 
-    dialect = "duckdb"
+    dialect = "clickhouse"
 
     def __init__(self, base_url: str | None = None, *, timeout: float = 620,
-                 mode: Literal["stable", "experimental"] = "stable",
-                 schema_version: str = "public_v1", allow_partial: bool = False):
+                 mode: Literal["stable"] = "stable",
+                 schema_version: str | None = None, allow_partial: bool = False):
         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.schema_version = schema_version if schema_version is not None else ("public_v1")
         self.allow_partial = allow_partial
         self._cursors = set()
         self.closed = False
@@ -210,8 +203,8 @@ class Connection:
 
 
 def connect(base_url: str | None = None, *, timeout: float = 620,
-            mode: Literal["stable", "experimental"] = "stable",
-            schema_version: str = "public_v1", allow_partial: bool = False) -> Connection:
+            mode: Literal["stable"] = "stable",
+            schema_version: str | None = None, allow_partial: bool = False) -> Connection:
     return Connection(base_url, timeout=timeout, mode=mode, schema_version=schema_version, allow_partial=allow_partial)
 
 

periplus_sdk/sql_api.py

@@ -10,9 +10,9 @@ from sqlalchemy.engine import Engine, URL
 def create_engine(
     base_url: str | None = None,
     *,
-    mode: Literal["stable", "experimental"] = "stable",
+    mode: Literal["stable"] = "stable",
     timeout: float = 620,
-    schema_version: str = "public_v1",
+    schema_version: str | None = None,
     allow_partial: bool = False,
 ) -> Engine:
     """Create a SQLAlchemy engine recognized by marimo and other SQL tools.

periplus_sdk/sqlalchemy.py

@@ -9,10 +9,11 @@ from sqlalchemy.engine.reflection import cache
 from sqlalchemy.sql.compiler import IdentifierPreparer
 
 from . import dbapi
+from .errors import ApiError, ResponseError, TransportError
 
 
 class SQLType(types.UserDefinedType):
-    """Preserve DuckDB type names, including nested types, during reflection."""
+    """Preserve ClickHouse type names, including nested types, during reflection."""
 
     cache_ok = True
 
@@ -24,28 +25,21 @@ class SQLType(types.UserDefinedType):
 
     @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
+        name = dbapi._base_type(self.name)
+        if name in dbapi._INTEGER_TYPES:return int
+        if name in dbapi._FLOAT_TYPES:return float
+        if name == 'Bool':return bool
+        if name.startswith('Decimal'):return dbapi.Decimal
+        if name in ('Date','Date32'):return dbapi.date
+        if name.startswith('DateTime'):return dbapi.datetime
+        if name.startswith('Time'):return dbapi.time
         return str
 
 
+
 class PeriplusDialect(default.DefaultDialect):
-    # The server speaks DuckDB SQL; this enables the correct notebook SQL dialect.
-    name = "duckdb"
+    # The server speaks ClickHouse SQL; this enables the correct notebook SQL dialect.
+    name = "clickhouse"
     driver = "periplus"
     supports_statement_cache = False
     supports_sane_rowcount = False
@@ -102,8 +96,15 @@ class PeriplusDialect(default.DefaultDialect):
     @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)]
+        try:
+            catalogue = connection.connection.dbapi_connection._client.helpers()
+        except (ApiError, ResponseError, TransportError) as error:
+            raise exc.InvalidRequestError(f"Public catalogue discovery failed: {error}") from error
+        if catalogue.schema_version != schema:
+            raise exc.InvalidRequestError("Public catalogue does not match the configured schema.")
+        prefix = f"{schema}."
+        return [relation.name.removeprefix(prefix) for relation in catalogue.relations
+                if relation.kind == "view" and relation.name.startswith(prefix)]
 
     @cache
     def get_table_names(self, connection, schema=None, **kw):
@@ -119,9 +120,15 @@ class PeriplusDialect(default.DefaultDialect):
     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)]
+        # A zero-row SELECT obtains native types through the supported public
+        # query contract, without scanning the view or requiring system access.
+        result = connection.exec_driver_sql(f"SELECT * FROM {quote(schema)}.{quote(table_name)} LIMIT 0")
+        metadata = result.cursor.result
+        self._complete(result)
+        return [{"name": name, "type": SQLType(kind),
+                 "nullable": kind.startswith("Nullable(") or kind.startswith("LowCardinality(Nullable("),
+                 "default": None}
+                for name, kind in zip(metadata.columns, metadata.types, strict=True)]
 
     @cache
     def get_pk_constraint(self, connection, table_name, schema=None, **kw):

periplus_sdk/stream.py

@@ -16,7 +16,7 @@ MEDIA_TYPE = "application/x-ndjson"
 class StreamResult(PreparedQuery):
     columns: list[str]
     types: list[str]
-    source_snapshot: int = Field(ge=0)
+    source_snapshot: int | None = Field(default=None, ge=0)
     limits: dict[str, int]
     complete: bool = False
     truncated: bool = False

periplus_sdk/types.py

@@ -11,7 +11,7 @@ class Diagnostic(BaseModel):
 
 
 class PreparedQuery(BaseModel):
-    query_mode: Literal["stable", "experimental"]
+    query_mode: Literal["stable"]
     compiler_version: str
     optimizations: list[str]
     schema_version: str
@@ -28,7 +28,7 @@ class QueryResult(PreparedQuery):
     rows: list[list[JsonValue]]
     truncated: bool
     elapsed_ms: float
-    source_snapshot: int = Field(ge=0)
+    source_snapshot: int | None = Field(default=None, ge=0)
     row_count: int = Field(ge=0)
     result_bytes: int = Field(ge=0)
     truncation_reason: Literal["max_rows", "max_result_bytes"] | None = None
@@ -51,4 +51,6 @@ class QueryHelper(BaseModel):
 
 class QueryHelpers(BaseModel):
     catalogue_version: str
+    schema_version: str
+    relations: list[QueryHelper]
     helpers: list[QueryHelper]

periplus_python_sdk-0.7.0.dist-info/METADATA

@@ -1,301 +0,0 @@
-Metadata-Version: 2.4
-Name: periplus-python-sdk
-Version: 0.7.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
-Requires-Dist: sqlalchemy<3,>=2.0
-Provides-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.7.0"
-```
-
-In a Python setup cell, create a SQLAlchemy engine:
-
-```python
-from periplus_sdk import sql_api
-
-pp = sql_api.create_engine("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 → periplus → 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"` for the experimental service. Omit the URL to use
-`PERIPLUS_PUBLIC_URL`. Optional `timeout=620` and `schema_version="public_v1"`
-arguments configure the client deadline and public schema. 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. SQLAlchemy is included in the standard SDK install; the `notebook` extra adds
-marimo. Existing marimo environments only need `uv add "periplus-python-sdk>=0.7.0"`.
-The returned object is a standard SQLAlchemy Engine, also usable with pandas and
-ordinary Python scripts. Engine creation is lazy; the first query opens a connection.
-
-## 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. One-dimensional lists/tuples of these scalar values are supported; use an explicit array cast
-for empty or typed lists. Binary, mappings, and nested collection parameters are unsupported. Fetching consumes incremental batches from one HTTP response and one source snapshot;
-it never issues pagination or retries. Close a cursor early to stop delivery. Connections/cursors are not thread-shared.
-`commit()` is a no-op; `rollback()` and `executemany()` are unsupported.
-
-`cursor.result` preserves stream metadata and completion information without retaining consumed rows. `connection.last_result`
-also retains it after marimo closes a cursor; a new execution clears it first.
-Truncation raises `OperationalError` with `code="result_limit"` when fetching reaches the terminal frame.
-`rowcount` stays -1 until completion, then reports the delivered count. `result.complete` means the
-terminal frame arrived; inspect `result.truncated` separately when opting into partial data.
-Use `allow_partial=True` on the engine or connection only when incomplete results are intentional.
-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 620 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.7.0"
-```
-
-Version 0.6.1 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.7.0` is released with:
-
-```sh
-git tag periplus-python-sdk-v0.7.0
-git push origin periplus-python-sdk-v0.7.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.7.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.
-
-## Python filtering back into marimo SQL
-
-The existing engine streams by default. For SQL → Python filtering → SQL, bind the
-filtered IDs to another engine variable; it shares the original connection pool and
-creates no server-side table or upload. Marimo discovers it like any other SQLAlchemy engine.
-
-```python
-pp = sql_api.create_engine("https://periplus.dev")
-
-# In a Python cell, after filtering your initial SQL dataframe:
-selected = sql_api.bind(pp, content_ids=qualified_pages["content_id"].to_list())
-
-# In the next SQL cell (engine: selected):
-raw_elements = mo.sql(
-    """
-    SELECT content_id, node_index, parent_index, tag,
-           trim(text_direct) AS text, attributes['class'] AS elem_class
-    FROM public_v1.html_element
-    WHERE content_id IN (SELECT unnest(CAST(:content_ids AS VARCHAR[])))
-      AND text_direct IS NOT NULL AND trim(text_direct) <> ''
-    """,
-    engine=selected,
-)
-```
-
-Keep SQL strings plain: `:content_ids` is a bound parameter, not an f-string.
-An empty list selects no elements; duplicate IDs do not multiply rows. Re-running the
-binding cell snapshots the new Python list into its engine options. Bindings only apply
-to matching SQL placeholders, so catalogue discovery remains available. Explicit
-SQLAlchemy execution parameters take precedence over engine bindings.
-
-Marimo collects the stream into a local dataframe, which must fit notebook memory.
-Its dataframe conversion currently infers types and may lose empty/all-null column
-information; the DB-API cursor always exposes server column names and SQL types.
-Initial SQL results and subsequent element results both reject truncation by default.
-Each separate SQL execution has its own snapshot; Python filtering does not pin the
-first query's snapshot across the round trip.
-
-## Consume batches without a dataframe
-
-```python
-with Client("https://periplus.dev") as client:
-    with client.stream("SELECT content_id FROM public_v1.prose") as stream:
-        for rows in stream:
-            process_batch(rows)
-        print(stream.result.row_count, stream.result.source_snapshot)
-        print(stream.result.limits)
-```
-
-Batches retain JSON wire values with SQL types in `stream.result.types`. DB-API fetching
-performs scalar Python decoding. The synchronous `Client.stream()` raises on truncation
-unless `allow_partial=True`; missing completion, malformed frames, timeouts, and broken
-connections always fail. Do not treat already-consumed batches as a complete dataset
-until iteration finishes successfully. Use context managers when stopping early.
-
-Admin Query limits controls requests (default 4 MiB, ceiling 16 MiB), parameter values
-(default 100,000, ceiling 1,000,000), results (ceiling 10 million rows and 1 GiB), and
-execution duration (ceiling 600 seconds). Parameter counting includes collection containers
-and their values. Existing result/duration defaults remain 1,000 rows, 8 MiB, and 20 seconds.
-Operators must raise these settings for larger workloads. No SDK parameter grants a larger
-server budget. Stream metadata includes effective limits; input rejections name the budget.
-Deploy the API, query service, public gateway and SDK together after applying Alembic
-revision `20260911_0016`. Ingress must permit the configured request size and stream duration.

periplus_python_sdk-0.7.0.dist-info/RECORD

@@ -1,16 +0,0 @@
-periplus_python_sdk-0.7.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-periplus_python_sdk-0.7.0.dist-info/licenses/NOTICE,sha256=bhbYSqcUB3U_P1-XzloiT81JGniqoYaRLxNkQ1Pm9MQ,52
-periplus_sdk/__init__.py,sha256=WimXYlPB6tCimBO4VSwhcp00dwSL87jMmMuQ4-kINfM,546
-periplus_sdk/client.py,sha256=bqIq2bmM_bnwf0ZnMN5kTXTctnEz7ITJUAfZohGsRIQ,7544
-periplus_sdk/dbapi.py,sha256=wyhtLfpgBZGxhC9rA53DNfQ7j8HegZkVp7mRq98bFSU,12256
-periplus_sdk/errors.py,sha256=rB1n-v8Hc2tu2dtHivz-MlqsCoRC5pTcWogTfM7SMLw,855
-periplus_sdk/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-periplus_sdk/sql_api.py,sha256=o5kLzwLim3VQ5oZfRyPUGCDr7RWmDidtktGLyBdkjQk,1884
-periplus_sdk/sqlalchemy.py,sha256=skyN2R5nIiWK55uBuxOHjeGRAPb8uPxm0f8nU0IIPqw,4836
-periplus_sdk/stream.py,sha256=pPXWikBWnOUZuHfBRXx08swBDMWJ4Gayx6azaz_wUCU,5197
-periplus_sdk/types.py,sha256=0eCwWev-Vrk0mRCIkot3Z_-dWWL3gpjljV4GyXEf8lk,1191
-periplus_python_sdk-0.7.0.dist-info/METADATA,sha256=6HTXHT4WnFKYbfB6MVc1Duxni8niJ3JQ7hP7w2GYkiA,14052
-periplus_python_sdk-0.7.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-periplus_python_sdk-0.7.0.dist-info/entry_points.txt,sha256=Pr14L_7AhLinq-4qDxB4awFVubrvR1BEfkaFVRpdCbU,73
-periplus_python_sdk-0.7.0.dist-info/top_level.txt,sha256=o41t5TzwgoxzSmbKoP6olWW1FyEAGWVYTjeoKadBK40,13
-periplus_python_sdk-0.7.0.dist-info/RECORD,,