periplus-python-sdk 0.6.0__tar.gz → 0.7.0__tar.gz

{periplus_python_sdk-0.6.0/src/periplus_python_sdk.egg-info → periplus_python_sdk-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: periplus-python-sdk
-Version: 0.6.0
+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
@@ -43,7 +43,7 @@ The client reuses HTTP connections; close it with a context manager or `close()`
 Install the notebook integration from PyPI:
 
 ```sh
-uv add "periplus-python-sdk[notebook]>=0.6.0"
+uv add "periplus-python-sdk[notebook]>=0.7.0"
 ```
 
 In a Python setup cell, create a SQLAlchemy engine:
@@ -62,7 +62,7 @@ FROM public_v1.capture
 LIMIT 10
 ```
 
-Marimo displays the result as a table. Expand **pp → public_v1** in Data Sources
+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
@@ -82,7 +82,7 @@ captures = mo.sql(
 ```
 
 Set `mode="experimental"` for the experimental service. Omit the URL to use
-`PERIPLUS_PUBLIC_URL`. Optional `timeout=140` and `schema_version="public_v1"`
+`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
@@ -90,7 +90,7 @@ 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.6.0"`.
+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.
 
@@ -112,14 +112,17 @@ with connect("https://periplus.dev", mode="stable") as connection:
 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.
+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 the original query response. `connection.last_result`
+`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 emits `periplus_sdk.dbapi.TruncationWarning` and sets `rowcount` to -1.
+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`.
 
@@ -185,7 +188,7 @@ Use `aclose()` when managing an async client's lifetime explicitly.
   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
+  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
@@ -196,10 +199,10 @@ Use `aclose()` when managing an async client's lifetime explicitly.
 Install the public-v1 client from PyPI:
 
 ```sh
-python -m pip install "periplus-python-sdk>=0.6.0"
+python -m pip install "periplus-python-sdk>=0.7.0"
 ```
 
-Version 0.6.0 supports the current public-v1 contract. For production, configure
+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:
 
@@ -211,11 +214,11 @@ PERIPLUS_PUBLIC_URL=http://localhost:8080 python packages/periplus-python-sdk/ex
 
 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.6.0` is released with:
+in `pyproject.toml`; for example, version `0.7.0` is released with:
 
 ```sh
-git tag periplus-python-sdk-v0.6.0
-git push origin periplus-python-sdk-v0.6.0
+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
@@ -225,10 +228,74 @@ 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.6.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.
+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.6.0 → periplus_python_sdk-0.7.0}/README.md

@@ -25,7 +25,7 @@ The client reuses HTTP connections; close it with a context manager or `close()`
 Install the notebook integration from PyPI:
 
 ```sh
-uv add "periplus-python-sdk[notebook]>=0.6.0"
+uv add "periplus-python-sdk[notebook]>=0.7.0"
 ```
 
 In a Python setup cell, create a SQLAlchemy engine:
@@ -44,7 +44,7 @@ FROM public_v1.capture
 LIMIT 10
 ```
 
-Marimo displays the result as a table. Expand **pp → public_v1** in Data Sources
+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
@@ -64,7 +64,7 @@ captures = mo.sql(
 ```
 
 Set `mode="experimental"` for the experimental service. Omit the URL to use
-`PERIPLUS_PUBLIC_URL`. Optional `timeout=140` and `schema_version="public_v1"`
+`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
@@ -72,7 +72,7 @@ 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.6.0"`.
+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.
 
@@ -94,14 +94,17 @@ with connect("https://periplus.dev", mode="stable") as connection:
 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.
+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 the original query response. `connection.last_result`
+`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 emits `periplus_sdk.dbapi.TruncationWarning` and sets `rowcount` to -1.
+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`.
 
@@ -167,7 +170,7 @@ Use `aclose()` when managing an async client's lifetime explicitly.
   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
+  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
@@ -178,10 +181,10 @@ Use `aclose()` when managing an async client's lifetime explicitly.
 Install the public-v1 client from PyPI:
 
 ```sh
-python -m pip install "periplus-python-sdk>=0.6.0"
+python -m pip install "periplus-python-sdk>=0.7.0"
 ```
 
-Version 0.6.0 supports the current public-v1 contract. For production, configure
+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:
 
@@ -193,11 +196,11 @@ PERIPLUS_PUBLIC_URL=http://localhost:8080 python packages/periplus-python-sdk/ex
 
 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.6.0` is released with:
+in `pyproject.toml`; for example, version `0.7.0` is released with:
 
 ```sh
-git tag periplus-python-sdk-v0.6.0
-git push origin periplus-python-sdk-v0.6.0
+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
@@ -207,10 +210,74 @@ 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.6.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.
+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.6.0 → periplus_python_sdk-0.7.0}/pyproject.toml

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

{periplus_python_sdk-0.6.0 → periplus_python_sdk-0.7.0/src/periplus_python_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: periplus-python-sdk
-Version: 0.6.0
+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
@@ -43,7 +43,7 @@ The client reuses HTTP connections; close it with a context manager or `close()`
 Install the notebook integration from PyPI:
 
 ```sh
-uv add "periplus-python-sdk[notebook]>=0.6.0"
+uv add "periplus-python-sdk[notebook]>=0.7.0"
 ```
 
 In a Python setup cell, create a SQLAlchemy engine:
@@ -62,7 +62,7 @@ FROM public_v1.capture
 LIMIT 10
 ```
 
-Marimo displays the result as a table. Expand **pp → public_v1** in Data Sources
+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
@@ -82,7 +82,7 @@ captures = mo.sql(
 ```
 
 Set `mode="experimental"` for the experimental service. Omit the URL to use
-`PERIPLUS_PUBLIC_URL`. Optional `timeout=140` and `schema_version="public_v1"`
+`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
@@ -90,7 +90,7 @@ 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.6.0"`.
+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.
 
@@ -112,14 +112,17 @@ with connect("https://periplus.dev", mode="stable") as connection:
 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.
+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 the original query response. `connection.last_result`
+`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 emits `periplus_sdk.dbapi.TruncationWarning` and sets `rowcount` to -1.
+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`.
 
@@ -185,7 +188,7 @@ Use `aclose()` when managing an async client's lifetime explicitly.
   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
+  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
@@ -196,10 +199,10 @@ Use `aclose()` when managing an async client's lifetime explicitly.
 Install the public-v1 client from PyPI:
 
 ```sh
-python -m pip install "periplus-python-sdk>=0.6.0"
+python -m pip install "periplus-python-sdk>=0.7.0"
 ```
 
-Version 0.6.0 supports the current public-v1 contract. For production, configure
+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:
 
@@ -211,11 +214,11 @@ PERIPLUS_PUBLIC_URL=http://localhost:8080 python packages/periplus-python-sdk/ex
 
 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.6.0` is released with:
+in `pyproject.toml`; for example, version `0.7.0` is released with:
 
 ```sh
-git tag periplus-python-sdk-v0.6.0
-git push origin periplus-python-sdk-v0.6.0
+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
@@ -225,10 +228,74 @@ 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.6.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.
+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.6.0 → periplus_python_sdk-0.7.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.0 → periplus_python_sdk-0.7.0}/src/periplus_sdk/client.py

@@ -79,7 +79,7 @@ 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"):
+    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/"
@@ -107,6 +107,25 @@ class Client:
     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 stream(self, sql: str, parameters: Sequence[JsonValue] | None = None, *,
+               schema_version: str = "public_v1", 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))
+            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,7 +133,7 @@ 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"):
+    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/"