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

{periplus_python_sdk-0.5.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.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 → periplus_python_sdk-0.6.0}/README.md

@@ -25,18 +25,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:
@@ -66,16 +63,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
 
@@ -179,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.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:
 
@@ -194,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.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
@@ -208,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.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 → periplus_python_sdk-0.6.0}/pyproject.toml

@@ -2,18 +2,18 @@
 license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICE"]
 name = "periplus-python-sdk"
-version = "0.5.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]
-sqlalchemy = ["sqlalchemy>=2.0,<3"]
-notebook = ["sqlalchemy>=2.0,<3", "marimo[sql]>=0.24.1"]
+notebook = ["marimo[sql]>=0.24.1"]
 
 [project.entry-points."sqlalchemy.dialects"]
 periplus = "periplus_sdk.sqlalchemy:PeriplusDialect"

{periplus_python_sdk-0.5.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.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 → periplus_python_sdk-0.6.0}/src/periplus_python_sdk.egg-info/SOURCES.txt

@@ -13,8 +13,10 @@ 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_dbapi.py
-tests/test_notebook.py
+tests/test_notebook.py
+tests/test_sql_api.py

{periplus_python_sdk-0.5.0 → periplus_python_sdk-0.6.0}/src/periplus_python_sdk.egg-info/requires.txt

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

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.5.0 → periplus_python_sdk-0.6.0}/tests/test_notebook.py

@@ -9,7 +9,7 @@ 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 sqlalchemy import create_engine
+        from periplus_sdk import sql_api
         factory = httpx.Client
         self.requests = []
         def handler(request):
@@ -27,7 +27,7 @@ class NotebookTests(unittest.TestCase):
         patcher = patch('periplus_sdk.client.httpx.Client', side_effect=lambda **kw: factory(**kw,transport=httpx.MockTransport(handler)))
         patcher.start()
         self.addCleanup(patcher.stop)
-        engine = create_engine('periplus:///public_v1',connect_args={'base_url':'https://public.example'})
+        engine = sql_api.create_engine('https://public.example')
         self.addCleanup(engine.dispose)
         return engine
 

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()