periplus-python-sdk 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

{periplus_python_sdk-0.5.0.dist-info → periplus_python_sdk-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: periplus-python-sdk
-Version: 0.5.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,10 +11,8 @@ License-File: LICENSE
 License-File: NOTICE
 Requires-Dist: httpx>=0.28
 Requires-Dist: pydantic<3,>=2.12
-Provides-Extra: sqlalchemy
-Requires-Dist: sqlalchemy<3,>=2.0; extra == "sqlalchemy"
+Requires-Dist: sqlalchemy<3,>=2.0
 Provides-Extra: notebook
-Requires-Dist: sqlalchemy<3,>=2.0; extra == "notebook"
 Requires-Dist: marimo[sql]>=0.24.1; extra == "notebook"
 Dynamic: license-file
 
@@ -45,18 +43,15 @@ The client reuses HTTP connections; close it with a context manager or `close()`
 Install the notebook integration from PyPI:
 
 ```sh
-uv add "periplus-python-sdk[notebook]>=0.5.0"
+uv add "periplus-python-sdk[notebook]>=0.6.0"
 ```
 
 In a Python setup cell, create a SQLAlchemy engine:
 
 ```python
-from sqlalchemy import create_engine
+from periplus_sdk import sql_api
 
-pp = create_engine(
-    "periplus:///public_v1",
-    connect_args={"base_url": "https://periplus.dev", "mode": "stable"},
-)
+pp = sql_api.create_engine("https://periplus.dev", mode="stable")
 ```
 
 Add a SQL cell, select **pp** in its connection dropdown, and enter:
@@ -86,16 +81,18 @@ captures = mo.sql(
 )
 ```
 
-Set `mode="experimental"` in `connect_args` for the experimental service. The URL
-path names the public schema; the HTTPS endpoint belongs in `base_url` (or set
-`PERIPLUS_PUBLIC_URL`). Run `pp.dispose()` when finished. This is a read-only
+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. For SQLAlchemy without marimo, install the
-`sqlalchemy` extra instead of `notebook`.
+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
 
@@ -199,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.5.0"
+python -m pip install "periplus-python-sdk>=0.6.0"
 ```
 
-Version 0.5.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:
 
@@ -214,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.5.0` is released with:
+in `pyproject.toml`; for example, version `0.6.0` is released with:
 
 ```sh
-git tag periplus-python-sdk-v0.5.0
-git push origin periplus-python-sdk-v0.5.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
@@ -228,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.5.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.5.0.dist-info → periplus_python_sdk-0.6.0.dist-info}/RECORD

@@ -1,14 +1,15 @@
-periplus_python_sdk-0.5.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-periplus_python_sdk-0.5.0.dist-info/licenses/NOTICE,sha256=bhbYSqcUB3U_P1-XzloiT81JGniqoYaRLxNkQ1Pm9MQ,52
+periplus_python_sdk-0.6.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+periplus_python_sdk-0.6.0.dist-info/licenses/NOTICE,sha256=bhbYSqcUB3U_P1-XzloiT81JGniqoYaRLxNkQ1Pm9MQ,52
 periplus_sdk/__init__.py,sha256=WimXYlPB6tCimBO4VSwhcp00dwSL87jMmMuQ4-kINfM,546
 periplus_sdk/client.py,sha256=ZwMmVJKNF-FrGh_qwiQ5myhu8XJodb_96ohkqK47yDA,6557
 periplus_sdk/dbapi.py,sha256=lK9ZROaMKXm26wvC7DCKywm3qwSvqeHa7zkktnJVP80,11244
 periplus_sdk/errors.py,sha256=rB1n-v8Hc2tu2dtHivz-MlqsCoRC5pTcWogTfM7SMLw,855
 periplus_sdk/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+periplus_sdk/sql_api.py,sha256=iBJt6hK_m84bDMBRZUDNwz20gi07gAxqWpm-NWWsqSo,850
 periplus_sdk/sqlalchemy.py,sha256=axFpEMnMP9uSxbsxzVNSUHNh41q2NruSX8W_5E8F59Q,4877
 periplus_sdk/types.py,sha256=PTdJO6BYTY97dBd3HMEZ52k6P9s0cMvidjpnc8zUpy4,1045
-periplus_python_sdk-0.5.0.dist-info/METADATA,sha256=-3wrgS0gK18Kf6UGV9jrVu2rhm2K51q6ScgZUyiOB7U,10091
-periplus_python_sdk-0.5.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-periplus_python_sdk-0.5.0.dist-info/entry_points.txt,sha256=Pr14L_7AhLinq-4qDxB4awFVubrvR1BEfkaFVRpdCbU,73
-periplus_python_sdk-0.5.0.dist-info/top_level.txt,sha256=o41t5TzwgoxzSmbKoP6olWW1FyEAGWVYTjeoKadBK40,13
-periplus_python_sdk-0.5.0.dist-info/RECORD,,
+periplus_python_sdk-0.6.0.dist-info/METADATA,sha256=UBcdaDmCCo0O0ISVlljy947LFFQIawX36y4dOioN4mo,10199
+periplus_python_sdk-0.6.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+periplus_python_sdk-0.6.0.dist-info/entry_points.txt,sha256=Pr14L_7AhLinq-4qDxB4awFVubrvR1BEfkaFVRpdCbU,73
+periplus_python_sdk-0.6.0.dist-info/top_level.txt,sha256=o41t5TzwgoxzSmbKoP6olWW1FyEAGWVYTjeoKadBK40,13
+periplus_python_sdk-0.6.0.dist-info/RECORD,,

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},
+    )