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

{periplus_python_sdk-0.7.0 → periplus_python_sdk-0.8.0}/src/periplus_sdk/dbapi.py

@@ -86,54 +86,47 @@ def TimestampFromTicks(ticks: float) -> datetime:
     return datetime.fromtimestamp(ticks)
 
 
-_INTEGER_TYPES = {"TINYINT", "SMALLINT", "INTEGER", "BIGINT", "HUGEINT", "UTINYINT",
-                  "USMALLINT", "UINTEGER", "UBIGINT", "UHUGEINT", "BIGNUM"}
-_FLOAT_TYPES = {"FLOAT", "DOUBLE", "REAL"}
-_TIME_TYPES = {"TIME", "TIME WITH TIME ZONE", "TIMETZ"}
-_TIMESTAMP_TYPES = {"TIMESTAMP", "TIMESTAMP_S", "TIMESTAMP_MS", "TIMESTAMP_NS",
-                    "TIMESTAMP WITH TIME ZONE", "TIMESTAMPTZ"}
+_INTEGER_TYPES = {f'{prefix}Int{bits}' for prefix in ('', 'U') for bits in (8,16,32,64,128,256)}
+_FLOAT_TYPES = {'Float32', 'Float64'}
+
+
+def _base_type(value: str) -> str:
+    while value.startswith(('Nullable(', 'LowCardinality(')):
+        value = value[value.index('(')+1:-1]
+    return value
 
 
 class _TypeCategory:
-    def __init__(self, names: set[str], prefix: str = ""):
-        self.names, self.prefix = names, prefix
+    def __init__(self, names: set[str], prefixes: tuple[str, ...] = ()):
+        self.names, self.prefixes = names, prefixes
 
     def __eq__(self, other: object) -> bool:
-        return isinstance(other, str) and (other in self.names or bool(self.prefix and other.startswith(self.prefix)))
+        if not isinstance(other, str):return False
+        value = _base_type(other)
+        return value in self.names or value.startswith(self.prefixes)
 
 
-STRING = _TypeCategory({"VARCHAR", "UUID", "JSON", "ENUM"})
-BINARY = _TypeCategory({"BLOB"})
-NUMBER = _TypeCategory(_INTEGER_TYPES | _FLOAT_TYPES | {"BOOLEAN"}, "DECIMAL(")
-DATETIME = _TypeCategory({"DATE"} | _TIME_TYPES | _TIMESTAMP_TYPES)
+STRING = _TypeCategory({'String','UUID','JSON'}, ('FixedString(', 'Enum'))
+BINARY = _TypeCategory(set())
+NUMBER = _TypeCategory(_INTEGER_TYPES | _FLOAT_TYPES | {'Bool'}, ('Decimal',))
+DATETIME = _TypeCategory({'Date','Date32'}, ('DateTime','Time'))
 ROWID = _TypeCategory(set())
 
 
 def _value(value: Any, sql_type: str) -> Any:
-    if value is None:
-        return None
-    if sql_type in _INTEGER_TYPES:
-        return int(value)
-    if sql_type in _FLOAT_TYPES:
-        return float(value)
-    if sql_type.startswith("DECIMAL("):
-        return Decimal(str(value))
-    # Preserve infinities and out-of-range dates rather than clipping them.
-    if sql_type == "DATE":
-        try:
-            return date.fromisoformat(value)
-        except ValueError:
-            return value
-    if sql_type in _TIME_TYPES:
-        return time.fromisoformat(value)
-    if sql_type in _TIMESTAMP_TYPES:
-        try:
-            return datetime.fromisoformat(value)
-        except ValueError:
-            return value
-    if sql_type == "BLOB":
-        return base64.b64decode(value, validate=True)
-    # UUIDs remain strings, and nested/other types retain their JSON wire values.
+    if value is None:return None
+    sql_type = _base_type(sql_type)
+    if sql_type in _INTEGER_TYPES:return int(value)
+    if sql_type in _FLOAT_TYPES:return float(value)
+    if sql_type.startswith('Decimal'):return Decimal(str(value))
+    if sql_type == 'Bool':return value in (True, 1, '1', 'true')
+    if sql_type in ('Date','Date32'):
+        try:return date.fromisoformat(value)
+        except ValueError:return value
+    if sql_type.startswith('DateTime'):
+        try:return datetime.fromisoformat(value)
+        except ValueError:return value
+    if sql_type.startswith('Time'):return time.fromisoformat(value)
     return value
 
 
@@ -152,16 +145,16 @@ def _parameter(value: Any) -> Any:
 class Connection:
     """Marimo-discoverable, read-only connection; commit is a no-op."""
 
-    dialect = "duckdb"
+    dialect = "clickhouse"
 
     def __init__(self, base_url: str | None = None, *, timeout: float = 620,
-                 mode: Literal["stable", "experimental"] = "stable",
-                 schema_version: str = "public_v1", allow_partial: bool = False):
+                 mode: Literal["stable"] = "stable",
+                 schema_version: str | None = None, allow_partial: bool = False):
         try:
             self._client = Client(base_url, timeout=timeout, mode=mode)
         except ConfigurationError as exc:
             raise InterfaceError(str(exc)) from exc
-        self.schema_version = schema_version
+        self.schema_version = schema_version if schema_version is not None else ("public_v1")
         self.allow_partial = allow_partial
         self._cursors = set()
         self.closed = False
@@ -210,8 +203,8 @@ class Connection:
 
 
 def connect(base_url: str | None = None, *, timeout: float = 620,
-            mode: Literal["stable", "experimental"] = "stable",
-            schema_version: str = "public_v1", allow_partial: bool = False) -> Connection:
+            mode: Literal["stable"] = "stable",
+            schema_version: str | None = None, allow_partial: bool = False) -> Connection:
     return Connection(base_url, timeout=timeout, mode=mode, schema_version=schema_version, allow_partial=allow_partial)
 
 

{periplus_python_sdk-0.7.0 → periplus_python_sdk-0.8.0}/src/periplus_sdk/sql_api.py

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

{periplus_python_sdk-0.7.0 → periplus_python_sdk-0.8.0}/src/periplus_sdk/sqlalchemy.py

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

{periplus_python_sdk-0.7.0 → periplus_python_sdk-0.8.0}/src/periplus_sdk/stream.py

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

{periplus_python_sdk-0.7.0 → periplus_python_sdk-0.8.0}/src/periplus_sdk/types.py

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

{periplus_python_sdk-0.7.0 → periplus_python_sdk-0.8.0}/tests/test_client.py

@@ -8,7 +8,7 @@ import httpx
 from periplus_sdk import AsyncClient, Client, ApiError, ConfigurationError, ResponseError, TransportError
 
 PREP = dict(query_mode='stable', compiler_version='public-query-v8:stable', optimizations=[], schema_version='public_v1', query_id='q', sql='SELECT ? AS n', parameters=[1], diagnostics=[], plan='plan')
-RESULT = dict(**PREP, columns=['n', 'n'], types=['BIGINT', 'DECIMAL(20,2)'],
+RESULT = dict(**PREP, columns=['n', 'n'], types=['Int64', 'Decimal(20,2)'],
               rows=[['9007199254740993', '123.45']], truncated=True, elapsed_ms=1.2, source_snapshot=4, row_count=1, result_bytes=32)
 
 
@@ -40,7 +40,7 @@ class ClientTests(unittest.TestCase):
             self.assertNotIn('authorization', request.headers)
             self.assertEqual(request.headers['x-periplus-query-source'], 'sdk')
             if request.url.path.endswith('helpers'):
-                return httpx.Response(200, json={'catalogue_version': '1.0.0', 'helpers': []})
+                return httpx.Response(200, json={'catalogue_version': '1.0.0', 'helpers': [], 'relations': [], 'schema_version': 'public_v1'})
             self.assertEqual(json.loads(request.content), {'sql': PREP['sql'], 'parameters': [1], 'schema_version': 'public_v1'})
             return httpx.Response(200, json=RESULT if request.url.path.endswith('exec') else PREP)
         with patch.dict(os.environ, {'PERIPLUS_QUERY_API_TOKEN': 'secret', 'PERIPLUS_API_TOKEN': 'admin'}):
@@ -54,24 +54,6 @@ class ClientTests(unittest.TestCase):
             self.assertEqual(client.helpers().catalogue_version, '1.0.0')
         self.assertEqual([r.url.path for r in requests], ['/prefix/api/query/prep', '/prefix/api/query/exec', '/prefix/api/query/helpers'])
 
-    def test_experimental_routes_and_metadata(self):
-        paths = []
-        def handler(request):
-            paths.append(request.url.path)
-            if request.url.path.endswith('helpers'):
-                return httpx.Response(200, json={'catalogue_version': '1.0.0', 'helpers': []})
-            payload = dict(RESULT if request.url.path.endswith('exec') else PREP,
-                           query_mode='experimental', compiler_version='public-query-v8:experimental',
-                           optimizations=['content_scope'])
-            return httpx.Response(200, json=payload)
-        with self.client(handler, mode='experimental') as client:
-            prepared = client.prepare('SELECT 1')
-            self.assertEqual(prepared.query_mode, 'experimental')
-            self.assertEqual(prepared.compiler_version, 'public-query-v8:experimental')
-            self.assertEqual(client.execute('SELECT 1').optimizations, ['content_scope'])
-            client.helpers()
-        self.assertEqual(paths, ['/prefix/api/query/experimental/' + p for p in ['prep', 'exec', 'helpers']])
-
     def test_invalid_mode(self):
         for factory in (Client, AsyncClient):
             with self.assertRaises(ConfigurationError):
@@ -132,15 +114,16 @@ class AsyncClientTests(unittest.IsolatedAsyncioTestCase):
         def handler(request):
             calls.append(request)
             if request.url.path.endswith('helpers'):
-                return httpx.Response(200, json={'catalogue_version': '1.0.0', 'helpers': []})
+                return httpx.Response(200, json={'catalogue_version': '1.0.0', 'helpers': [], 'relations': [], 'schema_version': 'public_v1'})
             return httpx.Response(200, json=RESULT if request.url.path.endswith('exec') else PREP)
         with patch('periplus_sdk.client.httpx.AsyncClient', side_effect=lambda **kw:
                    factory(**kw, transport=httpx.MockTransport(handler))):
-            async with AsyncClient('https://public.example/prefix/', mode='experimental') as client:
+            async with AsyncClient('https://public.example/prefix/', mode='stable') as client:
                 self.assertEqual((await client.prepare('SELECT ?', [1])).parameters, [1])
                 self.assertEqual((await client.execute('SELECT ?', [1])).rows, RESULT['rows'])
                 self.assertEqual((await client.helpers()).catalogue_version, '1.0.0')
         self.assertTrue(client._http.is_closed)
         self.assertEqual(len(calls), 3)
-        self.assertEqual([r.url.path for r in calls], ['/prefix/api/query/experimental/' + p for p in ['prep', 'exec', 'helpers']])
+        self.assertEqual([r.url.path for r in calls], ['/prefix/api/query/' + p for p in ['prep', 'exec', 'helpers']])
         self.assertTrue(all(r.headers['x-periplus-query-source'] == 'sdk' for r in calls))
+        self.assertTrue(all(json.loads(r.content)['schema_version'] == 'public_v1' for r in calls if r.method == 'POST'))

{periplus_python_sdk-0.7.0 → periplus_python_sdk-0.8.0}/tests/test_dbapi.py

@@ -34,7 +34,7 @@ class DBAPITests(unittest.TestCase):
         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.description[1][1], 'Decimal(20,2)')
         self.assertEqual(cur.fetchmany(0), [])
         self.assertEqual(cur.fetchone(), (9007199254740993, Decimal('123.45')))
         self.assertIsNone(cur.fetchone())
@@ -48,7 +48,7 @@ class DBAPITests(unittest.TestCase):
         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]])))
+        c = self.connection(lambda r: httpx.Response(200, json=response(columns=['n'], types=['Int32'], rows=[[1],[2],[3]])))
         cur = c.execute('SELECT 1')
         cur.arraysize = 2
         self.assertEqual(cur.fetchmany(), [(1,), (2,)])
@@ -66,12 +66,12 @@ class DBAPITests(unittest.TestCase):
         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'],
+                types=['Date','Time','DateTime64(6)','String','Float64','Int64','String'],
                 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')
+        c = self.connection(handler, mode='stable')
+        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'),'aGk=',float('inf'),None,'9007199254740993'))
+        self.assertEqual(requests[0].url.path, '/prefix/api/query/exec')
         self.assertEqual(requests[0].headers['x-periplus-query-source'], 'sdk')
 
     def test_truncation_and_lifecycle(self):