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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: periplus-python-sdk
-Version: 0.4.0
+Version: 0.6.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
@@ -11,6 +11,9 @@ 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
@@ -35,6 +38,99 @@ For a hosted deployment, replace the URL with its public HTTPS origin. Alternati
 `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.6.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 → 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=140` 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.6.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. Binary and nested parameters are not supported
+by this adapter. Fetching only consumes the bounded result already received;
+it never issues pagination or retries. Connections/cursors are not thread-shared.
+`commit()` is a no-op; `rollback()` and `executemany()` are unsupported.
+
+`cursor.result` preserves the original query response. `connection.last_result`
+also retains it after marimo closes a cursor; a new execution clears it first.
+Truncation emits `periplus_sdk.dbapi.TruncationWarning` and sets `rowcount` to -1.
+DB-API failures use the standard exception hierarchy in `periplus_sdk.dbapi`;
+HTTP errors retain `status_code`, `code`, and `retry_after_seconds`.
+
+Scalar integer, floating-point, decimal, date, time, timestamp and BLOB results
+are decoded to Python values. UUIDs remain strings. Nested/other SQL types keep
+their JSON wire representation; out-of-range dates/timestamps remain strings.
+Temporal precision is limited to what the server JSON transport preserves.
+The cursor preserves duplicate column names, but dataframe libraries/marimo may
+not: use unique SQL aliases. Dataframe inference can lose types for empty or
+all-null results; `cursor.description` retains the SQL type names.
+
 ## Stable and experimental APIs
 
 Both clients accept `mode="stable"` (the default) or `mode="experimental"` at initialization:
@@ -100,10 +196,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.4.0"
+python -m pip install "periplus-python-sdk>=0.6.0"
 ```
 
-Version 0.4.0 supports the current public-v1 contract. For production, configure
+Version 0.6.0 supports the current public-v1 contract. For production, configure
 `PERIPLUS_PUBLIC_URL=https://periplus.dev`; no API token is required.
 Run the installed package against an available public app:
 
@@ -115,11 +211,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.4.0` is released with:
+in `pyproject.toml`; for example, version `0.6.0` is released with:
 
 ```sh
-git tag periplus-python-sdk-v0.4.0
-git push origin periplus-python-sdk-v0.4.0
+git tag periplus-python-sdk-v0.6.0
+git push origin periplus-python-sdk-v0.6.0
 ```
 
 PyPI publishing uses Trusted Publishing rather than a stored API token. The
@@ -129,7 +225,7 @@ 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.4.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.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.
 
 ## License
 

{periplus_python_sdk-0.4.0 → periplus_python_sdk-0.6.0}/README.md

@@ -20,6 +20,99 @@ For a hosted deployment, replace the URL with its public HTTPS origin. Alternati
 `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.6.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 → 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=140` 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.6.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. Binary and nested parameters are not supported
+by this adapter. Fetching only consumes the bounded result already received;
+it never issues pagination or retries. Connections/cursors are not thread-shared.
+`commit()` is a no-op; `rollback()` and `executemany()` are unsupported.
+
+`cursor.result` preserves the original query response. `connection.last_result`
+also retains it after marimo closes a cursor; a new execution clears it first.
+Truncation emits `periplus_sdk.dbapi.TruncationWarning` and sets `rowcount` to -1.
+DB-API failures use the standard exception hierarchy in `periplus_sdk.dbapi`;
+HTTP errors retain `status_code`, `code`, and `retry_after_seconds`.
+
+Scalar integer, floating-point, decimal, date, time, timestamp and BLOB results
+are decoded to Python values. UUIDs remain strings. Nested/other SQL types keep
+their JSON wire representation; out-of-range dates/timestamps remain strings.
+Temporal precision is limited to what the server JSON transport preserves.
+The cursor preserves duplicate column names, but dataframe libraries/marimo may
+not: use unique SQL aliases. Dataframe inference can lose types for empty or
+all-null results; `cursor.description` retains the SQL type names.
+
 ## Stable and experimental APIs
 
 Both clients accept `mode="stable"` (the default) or `mode="experimental"` at initialization:
@@ -85,10 +178,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.4.0"
+python -m pip install "periplus-python-sdk>=0.6.0"
 ```
 
-Version 0.4.0 supports the current public-v1 contract. For production, configure
+Version 0.6.0 supports the current public-v1 contract. For production, configure
 `PERIPLUS_PUBLIC_URL=https://periplus.dev`; no API token is required.
 Run the installed package against an available public app:
 
@@ -100,11 +193,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.4.0` is released with:
+in `pyproject.toml`; for example, version `0.6.0` is released with:
 
 ```sh
-git tag periplus-python-sdk-v0.4.0
-git push origin periplus-python-sdk-v0.4.0
+git tag periplus-python-sdk-v0.6.0
+git push origin periplus-python-sdk-v0.6.0
 ```
 
 PyPI publishing uses Trusted Publishing rather than a stored API token. The
@@ -114,7 +207,7 @@ 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.4.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.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.
 
 ## License
 

{periplus_python_sdk-0.4.0 → periplus_python_sdk-0.6.0}/pyproject.toml

@@ -2,15 +2,22 @@
 license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICE"]
 name = "periplus-python-sdk"
-version = "0.4.0"
+version = "0.6.0"
 description = "Read-only Python client for the public Periplus query API"
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
     "httpx>=0.28",
     "pydantic>=2.12,<3",
+    "sqlalchemy>=2.0,<3",
 ]
 
+[project.optional-dependencies]
+notebook = ["marimo[sql]>=0.24.1"]
+
+[project.entry-points."sqlalchemy.dialects"]
+periplus = "periplus_sdk.sqlalchemy:PeriplusDialect"
+
 [project.urls]
 Repository = "https://github.com/elei-io/periplus"
 Issues = "https://github.com/elei-io/periplus/issues"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: periplus-python-sdk
-Version: 0.4.0
+Version: 0.6.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
@@ -11,6 +11,9 @@ 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
@@ -35,6 +38,99 @@ For a hosted deployment, replace the URL with its public HTTPS origin. Alternati
 `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.6.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 → 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=140` 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.6.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. Binary and nested parameters are not supported
+by this adapter. Fetching only consumes the bounded result already received;
+it never issues pagination or retries. Connections/cursors are not thread-shared.
+`commit()` is a no-op; `rollback()` and `executemany()` are unsupported.
+
+`cursor.result` preserves the original query response. `connection.last_result`
+also retains it after marimo closes a cursor; a new execution clears it first.
+Truncation emits `periplus_sdk.dbapi.TruncationWarning` and sets `rowcount` to -1.
+DB-API failures use the standard exception hierarchy in `periplus_sdk.dbapi`;
+HTTP errors retain `status_code`, `code`, and `retry_after_seconds`.
+
+Scalar integer, floating-point, decimal, date, time, timestamp and BLOB results
+are decoded to Python values. UUIDs remain strings. Nested/other SQL types keep
+their JSON wire representation; out-of-range dates/timestamps remain strings.
+Temporal precision is limited to what the server JSON transport preserves.
+The cursor preserves duplicate column names, but dataframe libraries/marimo may
+not: use unique SQL aliases. Dataframe inference can lose types for empty or
+all-null results; `cursor.description` retains the SQL type names.
+
 ## Stable and experimental APIs
 
 Both clients accept `mode="stable"` (the default) or `mode="experimental"` at initialization:
@@ -100,10 +196,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.4.0"
+python -m pip install "periplus-python-sdk>=0.6.0"
 ```
 
-Version 0.4.0 supports the current public-v1 contract. For production, configure
+Version 0.6.0 supports the current public-v1 contract. For production, configure
 `PERIPLUS_PUBLIC_URL=https://periplus.dev`; no API token is required.
 Run the installed package against an available public app:
 
@@ -115,11 +211,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.4.0` is released with:
+in `pyproject.toml`; for example, version `0.6.0` is released with:
 
 ```sh
-git tag periplus-python-sdk-v0.4.0
-git push origin periplus-python-sdk-v0.4.0
+git tag periplus-python-sdk-v0.6.0
+git push origin periplus-python-sdk-v0.6.0
 ```
 
 PyPI publishing uses Trusted Publishing rather than a stored API token. The
@@ -129,7 +225,7 @@ 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.4.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.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.
 
 ## License
 

{periplus_python_sdk-0.4.0 → periplus_python_sdk-0.6.0}/src/periplus_python_sdk.egg-info/SOURCES.txt

@@ -5,11 +5,18 @@ pyproject.toml
 src/periplus_python_sdk.egg-info/PKG-INFO
 src/periplus_python_sdk.egg-info/SOURCES.txt
 src/periplus_python_sdk.egg-info/dependency_links.txt
+src/periplus_python_sdk.egg-info/entry_points.txt
 src/periplus_python_sdk.egg-info/requires.txt
 src/periplus_python_sdk.egg-info/top_level.txt
 src/periplus_sdk/__init__.py
 src/periplus_sdk/client.py
+src/periplus_sdk/dbapi.py
 src/periplus_sdk/errors.py
 src/periplus_sdk/py.typed
+src/periplus_sdk/sql_api.py
+src/periplus_sdk/sqlalchemy.py
 src/periplus_sdk/types.py
-tests/test_client.py
+tests/test_client.py
+tests/test_dbapi.py
+tests/test_notebook.py
+tests/test_sql_api.py

periplus_python_sdk-0.6.0/src/periplus_python_sdk.egg-info/entry_points.txt

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

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

@@ -0,0 +1,6 @@
+httpx>=0.28
+pydantic<3,>=2.12
+sqlalchemy<3,>=2.0
+
+[notebook]
+marimo[sql]>=0.24.1

{periplus_python_sdk-0.4.0 → periplus_python_sdk-0.6.0}/src/periplus_sdk/__init__.py

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

periplus_python_sdk-0.6.0/src/periplus_sdk/dbapi.py

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

periplus_python_sdk-0.6.0/src/periplus_sdk/sql_api.py

@@ -0,0 +1,25 @@
+"""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
+from sqlalchemy.engine import Engine, URL
+
+
+def create_engine(
+    base_url: str | None = None,
+    *,
+    mode: Literal["stable", "experimental"] = "stable",
+    timeout: float = 140,
+    schema_version: str = "public_v1",
+) -> 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.
+    """
+    return _create_engine(
+        URL.create("periplus", database=schema_version),
+        connect_args={"base_url": base_url, "mode": mode, "timeout": timeout},
+    )

periplus_python_sdk-0.6.0/src/periplus_sdk/sqlalchemy.py

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

periplus_python_sdk-0.6.0/tests/test_dbapi.py

@@ -0,0 +1,118 @@
+import unittest
+from datetime import date, datetime, time
+from decimal import Decimal
+from unittest.mock import patch
+
+import httpx
+
+from periplus_sdk import connect, dbapi
+from test_client import RESULT
+
+
+def response(**kw):
+    return dict(RESULT, truncated=False, **kw)
+
+
+class DBAPITests(unittest.TestCase):
+    def connection(self, handler=None, **options):
+        factory = httpx.Client
+        handler = handler or (lambda request: httpx.Response(200, json=response()))
+        with patch('periplus_sdk.client.httpx.Client', side_effect=lambda **kw:
+                   factory(**kw, transport=httpx.MockTransport(handler))):
+            c = connect('https://public.example/prefix', **options)
+        self.addCleanup(c.close)
+        return c
+
+    def test_cursor_consumption_description_and_metadata(self):
+        c = self.connection()
+        cur = c.cursor()
+        with self.assertRaises(dbapi.ProgrammingError):
+            cur.fetchone()
+        cur.execute('SELECT ? AS n', [1])
+        self.assertEqual(cur.rowcount, 1)
+        self.assertEqual([d[0] for d in cur.description], ['n', 'n'])
+        self.assertEqual(cur.description[1][1], 'DECIMAL(20,2)')
+        self.assertEqual(cur.fetchmany(0), [])
+        self.assertEqual(cur.fetchone(), (9007199254740993, Decimal('123.45')))
+        self.assertIsNone(cur.fetchone())
+        self.assertEqual(cur.fetchall(), [])
+        self.assertEqual(cur.result.source_snapshot, 4)
+        self.assertIs(c.last_result, cur.result)
+        cur.execute('SELECT 1')
+        self.assertEqual(list(cur), [(9007199254740993, Decimal('123.45'))])
+        other = c.execute('SELECT 1')
+        self.assertEqual(other.rowcount, 1)
+        self.assertEqual(cur.fetchall(), [])
+
+    def test_empty_and_fetchmany(self):
+        c = self.connection(lambda r: httpx.Response(200, json=response(columns=['n'], types=['INTEGER'], rows=[[1],[2],[3]])))
+        cur = c.execute('SELECT 1')
+        cur.arraysize = 2
+        self.assertEqual(cur.fetchmany(), [(1,), (2,)])
+        self.assertEqual(cur.fetchmany(10), [(3,)])
+        with self.assertRaises(dbapi.ProgrammingError):
+            cur.fetchmany(-1)
+        c = self.connection(lambda r: httpx.Response(200, json=response(rows=[])))
+        cur = c.execute('SELECT 1 WHERE false')
+        self.assertEqual(cur.rowcount, 0)
+        self.assertEqual(len(cur.description), 2)
+        self.assertEqual(cur.fetchall(), [])
+
+    def test_modes_parameters_and_scalar_decoding(self):
+        requests = []
+        def handler(r):
+            requests.append(r)
+            return httpx.Response(200, json=response(columns=['d','t','ts','b','f','n','s'],
+                types=['DATE','TIME','TIMESTAMP WITH TIME ZONE','BLOB','DOUBLE','BIGINT','VARCHAR'],
+                rows=[['2026-09-11','12:34:56','2026-09-11T12:34:56+00:00','aGk=','inf',None,'9007199254740993']]))
+        c = self.connection(handler, mode='experimental')
+        row = c.execute('SELECT CAST(? AS DATE)', [date(2026,9,11)]).fetchone()
+        self.assertEqual(row, (date(2026,9,11),time(12,34,56),datetime.fromisoformat('2026-09-11T12:34:56+00:00'),b'hi',float('inf'),None,'9007199254740993'))
+        self.assertEqual(requests[0].url.path, '/prefix/api/query/experimental/exec')
+        self.assertEqual(requests[0].headers['x-periplus-query-source'], 'sdk')
+
+    def test_truncation_and_lifecycle(self):
+        c = self.connection(lambda r: httpx.Response(200,json=RESULT))
+        with self.assertWarns(dbapi.TruncationWarning):
+            cur = c.execute('SELECT 1')
+        self.assertEqual(cur.rowcount, -1)
+        self.assertTrue(c.last_result.truncated)
+        c.commit()
+        with self.assertRaises(dbapi.NotSupportedError):
+            c.rollback()
+        with self.assertRaises(dbapi.NotSupportedError):
+            cur.executemany('SELECT 1', [])
+        cur.close()
+        with self.assertRaises(dbapi.InterfaceError):
+            cur.fetchall()
+        c.close()
+        c.close()
+        with self.assertRaises(dbapi.InterfaceError):
+            c.cursor()
+
+    def test_failures_reset_results_and_preserve_errors(self):
+        calls = []
+        def handler(r):
+            calls.append(r)
+            return httpx.Response(200,json=response()) if len(calls)==1 else httpx.Response(429,json={'code':'service_busy','detail':'Busy'},headers={'Retry-After':'2'})
+        c = self.connection(handler)
+        cur = c.execute('SELECT 1')
+        with self.assertRaises(dbapi.OperationalError) as e:
+            cur.execute('SELECT 1')
+        self.assertEqual(e.exception.status_code,429)
+        self.assertEqual(e.exception.retry_after_seconds,2)
+        self.assertEqual(e.exception.code,'service_busy')
+        self.assertIsNone(c.last_result)
+        self.assertIsNone(cur.description)
+        self.assertEqual(len(calls),2)
+        with self.assertRaises(dbapi.ProgrammingError):
+            cur.fetchall()
+        for params in ({'n':1},'bad',[object()]):
+            with self.assertRaises(dbapi.ProgrammingError):
+                cur.execute('SELECT ?',params)
+        self.assertEqual(len(calls),2)
+
+    def test_malformed_rows(self):
+        c=self.connection(lambda r:httpx.Response(200,json=response(rows=[[1]])))
+        with self.assertRaises(dbapi.InterfaceError):
+            c.execute('SELECT 1')

periplus_python_sdk-0.6.0/tests/test_notebook.py

@@ -0,0 +1,87 @@
+"""Optional integration tests; release CI installs the notebook extra."""
+import importlib.util
+import unittest
+from unittest.mock import patch
+import httpx
+from test_client import RESULT
+
+
+@unittest.skipUnless(importlib.util.find_spec('sqlalchemy') and importlib.util.find_spec('marimo'), 'notebook extra required')
+class NotebookTests(unittest.TestCase):
+    def engine(self, *, truncated=False):
+        from periplus_sdk import sql_api
+        factory = httpx.Client
+        self.requests = []
+        def handler(request):
+            import json
+            sql = json.loads(request.content)['sql']
+            self.requests.append(sql)
+            columns, types, rows = ['n'], ['INTEGER'], [[42]]
+            if sql.startswith('SHOW TABLES'):
+                columns, types, rows = ['name'], ['VARCHAR'], [['capture']]
+            if sql.startswith('DESCRIBE'):
+                columns = ['column_name','column_type','null','key','default','extra']
+                types = ['VARCHAR']*6
+                rows = [['capture_id','UUID','NO',None,None,None],['captured_at','TIMESTAMP WITH TIME ZONE','YES',None,None,None]]
+            return httpx.Response(200,json=dict(RESULT,columns=columns,types=types,rows=rows,truncated=truncated))
+        patcher = patch('periplus_sdk.client.httpx.Client', side_effect=lambda **kw: factory(**kw,transport=httpx.MockTransport(handler)))
+        patcher.start()
+        self.addCleanup(patcher.stop)
+        engine = sql_api.create_engine('https://public.example')
+        self.addCleanup(engine.dispose)
+        return engine
+
+    def test_reflection_and_repeated_queries(self):
+        from sqlalchemy import inspect, text
+        engine=self.engine()
+        inspector=inspect(engine)
+        self.assertEqual(inspector.get_schema_names(),['public_v1'])
+        self.assertEqual(inspector.get_table_names(),[])
+        self.assertEqual(inspector.get_view_names(),['capture'])
+        self.assertTrue(inspector.has_table('capture'))
+        columns=inspector.get_columns('capture')
+        self.assertEqual(columns[0]['name'],'capture_id')
+        self.assertEqual(str(columns[1]['type']),'TIMESTAMP WITH TIME ZONE')
+        self.assertEqual(inspector.get_pk_constraint('capture')['constrained_columns'],[])
+        for _ in range(2):
+            with engine.connect() as c:
+                self.assertEqual(c.execute(text('SELECT :n AS n'),{'n':42}).fetchall(),[(42,)])
+        self.assertFalse(any('ROLLBACK' in s or 'BEGIN' in s for s in self.requests))
+
+    def test_marimo_discovery_schema_browser_and_sql_cell(self):
+        import marimo as mo
+        from marimo._sql.get_engines import get_engines_from_variables
+        engine=self.engine()
+        found=get_engines_from_variables([('pp',engine)])
+        self.assertEqual(len(found),1)
+        adapter=found[0][1]
+        databases=adapter.get_databases(include_schemas=True,include_tables=True,include_table_details=True)
+        self.assertEqual(databases[0].schemas[0].name,'public_v1')
+        table=databases[0].schemas[0].tables[0]
+        self.assertEqual(table.name,'capture')
+        self.assertEqual([c.name for c in table.columns],['capture_id','captured_at'])
+        df=mo.sql('SELECT 42 AS n',engine=engine,output=False)
+        self.assertEqual(df.rows(),[(42,)])
+
+    def test_dbapi_discovery(self):
+        from periplus_sdk import connect
+        from marimo._sql.engines.dbapi import DBAPIEngine
+        with connect('https://public.example') as c:
+            self.assertTrue(DBAPIEngine.is_compatible(c))
+
+    def test_truncated_discovery_is_not_silently_partial(self):
+        from sqlalchemy import inspect, exc
+        from periplus_sdk.dbapi import TruncationWarning
+        engine=self.engine(truncated=True)
+        with self.assertWarns(TruncationWarning):
+            with self.assertRaises(exc.InvalidRequestError):
+                inspect(engine).get_view_names()
+
+    def test_reflection_quotes_identifiers_and_rejects_private_schemas(self):
+        from sqlalchemy import inspect, exc
+        engine=self.engine()
+        inspector=inspect(engine)
+        inspector.get_columns('odd"name')
+        self.assertIn('DESCRIBE "public_v1"."odd""name"',self.requests)
+        with self.assertRaises(exc.InvalidRequestError):
+            inspector.get_columns('visits',schema='ingest')

periplus_python_sdk-0.6.0/tests/test_sql_api.py

@@ -0,0 +1,38 @@
+import json
+import os
+import unittest
+from unittest.mock import patch
+
+import httpx
+from sqlalchemy import inspect, text
+from sqlalchemy.engine import Engine
+from periplus_sdk import sql_api
+from test_client import RESULT
+
+
+class SQLApiTests(unittest.TestCase):
+    def test_engine_options_environment_and_queries(self):
+        factory = httpx.Client
+        for mode in ('stable', 'experimental'):
+            requests = []
+            def handler(request):
+                requests.append(request)
+                return httpx.Response(200, json=dict(RESULT, columns=['n'], types=['INTEGER'], rows=[[42]], truncated=False))
+            with self.subTest(mode=mode), patch.dict(os.environ, {'PERIPLUS_PUBLIC_URL':'https://public.example/prefix'}), patch(
+                'periplus_sdk.client.httpx.Client',
+                side_effect=lambda **kw: factory(**kw, transport=httpx.MockTransport(handler)),
+            ):
+                engine = sql_api.create_engine(mode=mode, timeout=37)
+                self.assertIsInstance(engine, Engine)
+                self.assertEqual(requests, [])
+                try:
+                    self.assertEqual(inspect(engine).default_schema_name, 'public_v1')
+                    with engine.connect() as conn:
+                        self.assertEqual(conn.connection.dbapi_connection._client._http.timeout.read,37)
+                        self.assertEqual(conn.execute(text('SELECT :n AS n'), {'n':42}).fetchall(), [(42,)])
+                    suffix = 'experimental/' if mode == 'experimental' else ''
+                    self.assertEqual(requests[0].url.path, '/prefix/api/query/'+suffix+'exec')
+                    self.assertEqual(json.loads(requests[0].content)['parameters'], [42])
+                    self.assertEqual(json.loads(requests[0].content)['schema_version'], 'public_v1')
+                finally:
+                    engine.dispose()

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

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