periplus-python-sdk 0.6.1__tar.gz → 0.8.0__tar.gz

periplus_python_sdk-0.8.0/PKG-INFO

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

@@ -0,0 +1,52 @@
+# 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.6.1 → periplus_python_sdk-0.8.0}/pyproject.toml

@@ -2,7 +2,7 @@
 license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICE"]
 name = "periplus-python-sdk"
-version = "0.6.1"
+version = "0.8.0"
 description = "Read-only Python client for the public Periplus query API"
 readme = "README.md"
 requires-python = ">=3.11"

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

@@ -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.6.1 → periplus_python_sdk-0.8.0}/src/periplus_python_sdk.egg-info/SOURCES.txt

@@ -15,8 +15,10 @@ src/periplus_sdk/errors.py
 src/periplus_sdk/py.typed
 src/periplus_sdk/sql_api.py
 src/periplus_sdk/sqlalchemy.py
+src/periplus_sdk/stream.py
 src/periplus_sdk/types.py
 tests/test_client.py
 tests/test_dbapi.py
 tests/test_notebook.py
-tests/test_sql_api.py
+tests/test_sql_api.py
+tests/test_stream.py

{periplus_python_sdk-0.6.1 → periplus_python_sdk-0.8.0}/src/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 = 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/"
+    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,11 +102,30 @@ 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 | 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 if schema_version is not None else self.schema_version))
+            response = self._http.send(request, stream=True)
+            try:
+                if not response.is_success:
+                    response.read()
+                    _decode(response, QueryResult)
+                return QueryStream(response, allow_partial=allow_partial)
+            except BaseException:
+                response.close()
+                raise
+        except httpx.RequestError:
+            raise TransportError("Could not open the public query stream.") from None
 
     def helpers(self) -> QueryHelpers:
         return self._request("GET", "helpers", QueryHelpers)
@@ -114,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 = 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/"
+    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:
@@ -136,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_python_sdk-0.6.1 → periplus_python_sdk-0.8.0}/src/periplus_sdk/dbapi.py

@@ -1,7 +1,7 @@
 """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.
+Each execute is an independent server snapshot. Fetching consumes a bounded stream.
+Connections and cursors must not be shared by threads.
 """
 from __future__ import annotations
 
@@ -11,11 +11,10 @@ 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
+from .stream import StreamResult
 
 apilevel = "2.0"
 threadsafety = 1
@@ -26,10 +25,6 @@ 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."""
 
@@ -91,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
 
 
@@ -147,24 +135,30 @@ def _parameter(value: Any) -> Any:
         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.")
+    if isinstance(value, (list, tuple)):
+        if any(isinstance(item, (list, tuple, dict)) for item in value):
+            raise ProgrammingError("Collection parameters must be one-dimensional lists of scalar values.")
+        return [_parameter(item) for item in value]
+    raise ProgrammingError("Parameters must be scalar values or scalar lists; use explicit SQL casts for typed values.")
 
 
 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 = 140,
-                 mode: Literal["stable", "experimental"] = "stable",
-                 schema_version: str = "public_v1"):
+    def __init__(self, base_url: str | None = None, *, timeout: float = 620,
+                 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
-        self.last_result: QueryResult | None = None
+        self.last_result: StreamResult | None = None
 
     def _check(self) -> None:
         if self.closed:
@@ -172,7 +166,9 @@ class Connection:
 
     def cursor(self) -> Cursor:
         self._check()
-        return Cursor(self)
+        cursor = Cursor(self)
+        self._cursors.add(cursor)
+        return cursor
 
     def execute(self, operation: str, parameters: Sequence[Any] | None = None) -> Cursor:
         cursor = self.cursor()
@@ -192,6 +188,8 @@ class Connection:
 
     def close(self) -> None:
         if not self.closed:
+            for cursor in list(self._cursors):
+                cursor.close()
             self._client.close()
             self.closed = True
             self.last_result = None
@@ -204,25 +202,26 @@ class Connection:
         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)
+def connect(base_url: str | None = None, *, timeout: float = 620,
+            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)
 
 
 class Cursor:
-    """A buffered result. Metadata stays on result after rows are consumed."""
+    """Incremental cursor. Metadata stays available without retaining consumed rows."""
 
     arraysize = 1
 
     def __init__(self, connection: Connection):
         self.connection = connection
         self.closed = False
-        self.result: QueryResult | None = None
+        self.result: StreamResult | None = None
         self.description: list[tuple[Any, ...]] | None = None
         self.rowcount = -1
         self._rows: list[tuple[Any, ...]] = []
         self._position = 0
+        self._stream = None
 
     def _check(self, *, result: bool = False) -> None:
         self.connection._check()
@@ -233,6 +232,9 @@ class Cursor:
 
     def execute(self, operation: str, parameters: Sequence[Any] | None = None) -> Cursor:
         self._check()
+        if self._stream is not None:
+            self._stream.close()
+        self._stream = None
         self.result, self.description, self.rowcount = None, None, -1
         self._rows, self._position = [], 0
         self.connection.last_result = None
@@ -242,7 +244,9 @@ class Cursor:
             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)
+            self._stream = self.connection._client.stream(operation, values, schema_version=self.connection.schema_version,
+                                                          allow_partial=self.connection.allow_partial)
+            result = self._stream.result
         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,
@@ -251,26 +255,37 @@ class Cursor:
             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 _batch(self):
+        try:
+            batch = next(self._stream)
+            self._rows = [tuple(_value(v, t) for v, t in zip(row, self.result.types, strict=True)) for row in batch]
+            self._position = 0
+            return True
+        except StopIteration:
+            self.rowcount = -1 if self.result.truncated else self.result.row_count
+            self._rows, self._position = [], 0
+            return False
+        except ApiError as exc:
+            raise OperationalError(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
+        except (ValueError, TypeError, ArithmeticError) as exc:
+            self._stream.close()
+            raise DataError("Query value does not match its SQL type.") from exc
+
     def fetchone(self) -> tuple[Any, ...] | None:
         self._check(result=True)
-        if self._position == len(self._rows):
-            return None
+        while self._position == len(self._rows):
+            if not self._batch():
+                return None
         row = self._rows[self._position]
         self._position += 1
         return row
@@ -280,14 +295,17 @@ class Cursor:
         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
+        rows = []
+        for _ in range(size):
+            row = self.fetchone()
+            if row is None:
+                break
+            rows.append(row)
         return rows
 
     def fetchall(self) -> list[tuple[Any, ...]]:
         self._check(result=True)
-        return self.fetchmany(len(self._rows) - self._position)
+        return list(self)
 
     def executemany(self, operation: str, seq_of_parameters: Any) -> None:
         self._check()
@@ -300,6 +318,9 @@ class Cursor:
         self._check()
 
     def close(self) -> None:
+        if self._stream is not None:
+            self._stream.close()
+        self.connection._cursors.discard(self)
         self.closed = True
         self._rows = []
         self.result = None

periplus_python_sdk-0.8.0/src/periplus_sdk/sql_api.py

@@ -0,0 +1,47 @@
+"""Notebook-friendly SQL engine over the public Periplus query API."""
+from __future__ import annotations
+
+from typing import Literal
+
+from sqlalchemy import create_engine as _create_engine, event
+from sqlalchemy.engine import Engine, URL
+
+
+def create_engine(
+    base_url: str | None = None,
+    *,
+    mode: Literal["stable"] = "stable",
+    timeout: float = 620,
+    schema_version: str | None = None,
+    allow_partial: bool = False,
+) -> Engine:
+    """Create a SQLAlchemy engine recognized by marimo and other SQL tools.
+
+    The public URL defaults to PERIPLUS_PUBLIC_URL. Connections are opened lazily;
+    dispose the engine when finished. Each query uses an independent server snapshot.
+    """
+    engine = _create_engine(
+        URL.create("periplus", database="periplus"),
+        connect_args={"base_url": base_url, "mode": mode, "timeout": timeout, "schema_version": schema_version, "allow_partial": allow_partial},
+    )
+
+    event.listen(engine, "before_execute", _parameters, retval=True)
+    return engine
+
+
+def _parameters(connection, clauseelement, multiparams, params, execution_options):
+    bindings = execution_options.get("periplus_parameters", {})
+    if bindings and not multiparams:
+        names = clauseelement.compile().params
+        params = {**{name: value for name, value in bindings.items() if name in names}, **params}
+    return clauseelement, multiparams, params
+
+
+def bind(engine: Engine, **parameters) -> Engine:
+    """Create a marimo-discoverable engine with named SQL parameters for this cell.
+
+    Uses the original engine's pool. No query, upload, or server state is created.
+    Write :name placeholders in SQL cells; lists can be CAST(:ids AS VARCHAR[]).
+    """
+    from .dbapi import _parameter
+    return engine.execution_options(periplus_parameters={name: _parameter(value) for name, value in parameters.items()})