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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: periplus-python-sdk
-Version: 0.3.0
+Version: 0.4.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
@@ -35,6 +35,21 @@ 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()`.
 
+## Stable and experimental APIs
+
+Both clients accept `mode="stable"` (the default) or `mode="experimental"` at initialization:
+
+```python
+with Client("https://periplus.dev", mode="experimental") as client:
+    result = client.execute("SELECT capture_id FROM public_v1.capture LIMIT 1")
+    print(result.query_mode, result.compiler_version, result.optimizations)
+```
+
+The selected mode applies to preparation, execution, and helper discovery. Experimental
+requests use the public application's `/api/query/experimental/` routes. There is no
+automatic fallback to stable if the experimental service is unavailable.
+`AsyncClient` accepts the same option. Invalid modes raise `ConfigurationError`.
+
 ## Preparation and helpers
 
 ```python
@@ -85,10 +100,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.3.0"
+python -m pip install "periplus-python-sdk>=0.4.0"
 ```
 
-Version 0.3.0 supports the current public-v1 contract. For production, configure
+Version 0.4.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 +115,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.3.0` is released with:
+in `pyproject.toml`; for example, version `0.4.0` is released with:
 
 ```sh
-git tag periplus-python-sdk-v0.3.0
-git push origin periplus-python-sdk-v0.3.0
+git tag periplus-python-sdk-v0.4.0
+git push origin periplus-python-sdk-v0.4.0
 ```
 
 PyPI publishing uses Trusted Publishing rather than a stored API token. The
@@ -114,7 +129,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.3.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.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.
 
 ## License
 

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

@@ -20,6 +20,21 @@ 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()`.
 
+## Stable and experimental APIs
+
+Both clients accept `mode="stable"` (the default) or `mode="experimental"` at initialization:
+
+```python
+with Client("https://periplus.dev", mode="experimental") as client:
+    result = client.execute("SELECT capture_id FROM public_v1.capture LIMIT 1")
+    print(result.query_mode, result.compiler_version, result.optimizations)
+```
+
+The selected mode applies to preparation, execution, and helper discovery. Experimental
+requests use the public application's `/api/query/experimental/` routes. There is no
+automatic fallback to stable if the experimental service is unavailable.
+`AsyncClient` accepts the same option. Invalid modes raise `ConfigurationError`.
+
 ## Preparation and helpers
 
 ```python
@@ -70,10 +85,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.3.0"
+python -m pip install "periplus-python-sdk>=0.4.0"
 ```
 
-Version 0.3.0 supports the current public-v1 contract. For production, configure
+Version 0.4.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:
 
@@ -85,11 +100,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.3.0` is released with:
+in `pyproject.toml`; for example, version `0.4.0` is released with:
 
 ```sh
-git tag periplus-python-sdk-v0.3.0
-git push origin periplus-python-sdk-v0.3.0
+git tag periplus-python-sdk-v0.4.0
+git push origin periplus-python-sdk-v0.4.0
 ```
 
 PyPI publishing uses Trusted Publishing rather than a stored API token. The
@@ -99,7 +114,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.3.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.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.
 
 ## License
 

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: periplus-python-sdk
-Version: 0.3.0
+Version: 0.4.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
@@ -35,6 +35,21 @@ 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()`.
 
+## Stable and experimental APIs
+
+Both clients accept `mode="stable"` (the default) or `mode="experimental"` at initialization:
+
+```python
+with Client("https://periplus.dev", mode="experimental") as client:
+    result = client.execute("SELECT capture_id FROM public_v1.capture LIMIT 1")
+    print(result.query_mode, result.compiler_version, result.optimizations)
+```
+
+The selected mode applies to preparation, execution, and helper discovery. Experimental
+requests use the public application's `/api/query/experimental/` routes. There is no
+automatic fallback to stable if the experimental service is unavailable.
+`AsyncClient` accepts the same option. Invalid modes raise `ConfigurationError`.
+
 ## Preparation and helpers
 
 ```python
@@ -85,10 +100,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.3.0"
+python -m pip install "periplus-python-sdk>=0.4.0"
 ```
 
-Version 0.3.0 supports the current public-v1 contract. For production, configure
+Version 0.4.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 +115,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.3.0` is released with:
+in `pyproject.toml`; for example, version `0.4.0` is released with:
 
 ```sh
-git tag periplus-python-sdk-v0.3.0
-git push origin periplus-python-sdk-v0.3.0
+git tag periplus-python-sdk-v0.4.0
+git push origin periplus-python-sdk-v0.4.0
 ```
 
 PyPI publishing uses Trusted Publishing rather than a stored API token. The
@@ -114,7 +129,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.3.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.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.
 
 ## License
 

{periplus_python_sdk-0.3.0 → periplus_python_sdk-0.4.0}/src/periplus_sdk/client.py

@@ -6,7 +6,7 @@ from datetime import UTC, datetime
 from email.utils import parsedate_to_datetime
 import math
 import os
-from typing import TypeVar
+from typing import Literal, TypeVar
 
 import httpx
 from pydantic import BaseModel, JsonValue, ValidationError
@@ -79,7 +79,10 @@ 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):
+    def __init__(self, base_url: str | None = None, *, timeout: float = 140, mode: Literal["stable", "experimental"] = "stable"):
+        if mode not in {"stable", "experimental"}:
+            raise ConfigurationError("mode must be stable or experimental.")
+        self._query_path = "api/query/experimental/" if mode == "experimental" else "api/query/"
         self._http = httpx.Client(**_options(base_url, timeout))
 
     def __enter__(self) -> Client:
@@ -93,7 +96,7 @@ class Client:
 
     def _request(self, method: str, path: str, model: type[Model], **kwargs) -> Model:
         try:
-            response = self._http.request(method, "api/query/" + path, **kwargs)
+            response = self._http.request(method, self._query_path + path, **kwargs)
         except httpx.RequestError:
             raise TransportError("Could not complete the public query request.") from None
         return _decode(response, model)
@@ -111,7 +114,10 @@ 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):
+    def __init__(self, base_url: str | None = None, *, timeout: float = 140, mode: Literal["stable", "experimental"] = "stable"):
+        if mode not in {"stable", "experimental"}:
+            raise ConfigurationError("mode must be stable or experimental.")
+        self._query_path = "api/query/experimental/" if mode == "experimental" else "api/query/"
         self._http = httpx.AsyncClient(**_options(base_url, timeout))
 
     async def __aenter__(self) -> AsyncClient:
@@ -125,7 +131,7 @@ class AsyncClient:
 
     async def _request(self, method: str, path: str, model: type[Model], **kwargs) -> Model:
         try:
-            response = await self._http.request(method, "api/query/" + path, **kwargs)
+            response = await self._http.request(method, self._query_path + path, **kwargs)
         except httpx.RequestError:
             raise TransportError("Could not complete the public query request.") from None
         return _decode(response, model)

{periplus_python_sdk-0.3.0 → periplus_python_sdk-0.4.0}/src/periplus_sdk/types.py

@@ -1,4 +1,6 @@
 """Public query wire types; SQL types and JSON values are preserved."""
+from typing import Literal
+
 from pydantic import BaseModel, Field, JsonValue
 
 
@@ -9,6 +11,9 @@ class Diagnostic(BaseModel):
 
 
 class PreparedQuery(BaseModel):
+    query_mode: Literal["stable", "experimental"]
+    compiler_version: str
+    optimizations: list[str]
     schema_version: str
     query_id: str
     sql: str

{periplus_python_sdk-0.3.0 → periplus_python_sdk-0.4.0}/tests/test_client.py

@@ -7,17 +7,17 @@ import httpx
 
 from periplus_sdk import AsyncClient, Client, ApiError, ConfigurationError, ResponseError, TransportError
 
-PREP = dict(schema_version='public_v1', query_id='q', sql='SELECT ? AS n', parameters=[1], diagnostics=[], plan='plan')
+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)'],
               rows=[['9007199254740993', '123.45']], truncated=True, elapsed_ms=1.2, source_snapshot=4)
 
 
 class ClientTests(unittest.TestCase):
-    def client(self, handler):
+    def client(self, handler, **options):
         factory = httpx.Client
         with patch('periplus_sdk.client.httpx.Client', side_effect=lambda **kw:
                    factory(**kw, transport=httpx.MockTransport(handler))):
-            client = Client('https://public.example/prefix/')
+            client = Client('https://public.example/prefix/', **options)
         self.addCleanup(client.close)
         return client
 
@@ -42,6 +42,29 @@ 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):
+                factory('https://public.example', mode='unknown')
+
     def test_errors_preserve_categories_and_never_retry(self):
         for status, body, code in [(429, {'code': 'service_busy', 'detail': 'Busy'}, 'service_busy'),
                                    (403, {'code': 'feature_disabled', 'detail': 'Disabled'}, 'feature_disabled'),
@@ -101,10 +124,11 @@ class AsyncClientTests(unittest.IsolatedAsyncioTestCase):
             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') as client:
+            async with AsyncClient('https://public.example/prefix/', mode='experimental') 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.assertTrue(all(r.headers['x-periplus-query-source'] == 'sdk' for r in calls))