periplus-python-sdk 0.8.0__tar.gz → 0.11.0__tar.gz

periplus_python_sdk-0.11.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: periplus-python-sdk
+Version: 0.11.0
+Summary: Typed Periplus platform client with SQL and notebook integration
+License-Expression: AGPL-3.0-only
+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: licensing/LICENSE
+License-File: licensing/NOTICE
+License-File: licensing/README.md
+License-File: licensing/THIRD_PARTY_NOTICES.md
+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
+
+Typed organization operations and SQL access through the Periplus HTTP API.
+The 0.11.0 platform interface requires the matching API release. It includes
+the source-snapshot metadata introduced in 0.10.0 alongside customer operations.
+Install from PyPI:
+
+```sh
+python -m pip install --upgrade periplus-python-sdk
+```
+
+```python
+from periplus_sdk import Client
+
+with Client("https://api.periplus.dev", api_key="ppl_…") as client:
+    result = client.execute(
+        "SELECT capture_id, url FROM public_v1.captures LIMIT ?", [10]
+    )
+    print(result.columns, result.rows)
+```
+
+The default origin is `https://api.periplus.dev`. Use `PERIPLUS_API_URL` to override it and `PERIPLUS_API_KEY` to
+supply your personal organization API key. A key with `organization:sql:exec`
+is required. Database usernames/passwords and anonymous access are not supported.
+Use HTTPS outside loopback development. Connect directly to the API origin,
+not the public marketing site.
+
+Version 0.9.0 requires personal API keys instead of database credentials. Create
+a key in the app's Settings → My API keys. It inherits your current access in
+that organization; SQL requires your membership to have `organization:sql:exec`.
+For local development, install `./clients/periplus-python-sdk` from the repository
+root and connect to `http://localhost:8000`.
+
+`AsyncClient` accepts the same options. `prepare` explains a SELECT; `execute`
+returns typed columns/rows for read-only queries. `schema()` returns
+visible tables, column types/descriptions and helper documentation. All SQL uses
+`POST /api/v1/sql`; schema discovery uses `GET /api/v1/schema`. ClickHouse enforces
+permissions. The SDK never retries automatically, including failed queries.
+
+Public HTML joins use `parse_id` and `node_index`; `document_id` identifies exact
+raw bytes. Public shorthand uses the `public_v1` schema.
+
+In 0.10.0, `result.source_snapshot` is a typed `SourceSnapshot` containing
+`layout_id` (UUID) and `publication_epoch` (integer), or `None` when no build-bound
+public corpus was read. Buffered, asynchronous, streamed and DB-API results share
+this contract. Compare both fields, not just the epoch. The identity describes
+the public corpus inputs, not any native staff/external inputs. It does not retain
+the data or request historical reads. This replaces the old nullable integer field;
+use this SDK version with the corresponding API release.
+
+For notebook/SQLAlchemy integration:
+
+```python
+from periplus_sdk import sql_api
+from sqlalchemy import text
+
+engine = sql_api.create_engine(base_url="http://localhost:8000", api_key="ppl_…")
+with engine.connect() as connection:
+    print(connection.execute(text("SELECT url FROM public_v1.captures LIMIT 5")).all())
+engine.dispose()
+```
+
+Marimo discovers accessible tables, views, typed columns and comments through the
+schema endpoint. Reflection does not execute SQL. One SQLAlchemy Inspector caches
+its metadata; call `inspector.clear_cache()` to refresh it. Missing metadata raises
+an error rather than presenting an apparently complete empty schema.
+
+The DB-API connection advertises the ClickHouse dialect and converts native
+nullable integer, decimal, date and datetime types. Nested types retain JSON wire
+values. Writes are not exposed through the query API. There are no client
+transactions; each statement is independent.
+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).
+
+## Organization resources
+
+The same key selects your organization and inherits your live membership access.
+`Client` and `AsyncClient` expose the same namespaces:
+
+| Namespace | Operations |
+| --- | --- |
+| `identity`, `availability` | `get` |
+| `discovery` | `create`, `get`, `list`, `iter`, `arrivals`, `cancel` |
+| `retention`, `monitoring` | `create`, `preview`, `activate`, `get`, `list`, `iter`, `members`, `update`, `pause`, `resume`, `delete` |
+| `saved_queries` | `create`, `get`, `list`, `iter`, `rename`, `delete` |
+| `members` | `list`, `update_role`, `remove` |
+| `invitations` | `list`, `create`, `cancel` |
+| `api_keys` | `create`, `list`, `iter`, `revoke` |
+| `usage` | `get` |
+| `query_history` | `list`, `iter`, `get`, `summary` |
+| `audit` | `list`, `iter` |
+
+```python
+from periplus_sdk import Client
+
+with Client() as client:
+    preview = client.retention.preview(
+        name="Research sources", days=90,
+        sql="SELECT capture_id FROM captures WHERE domain(url) = ?",
+        parameters=["example.com"],
+    )
+    print(preview.id, preview.capture_count, preview.sample)
+    # Review the selection before calling:
+    # active = client.retention.activate(preview)
+```
+
+SQL previews persist inactive, frozen selections; activation never reruns SQL.
+Explicit IDs/URLs passed to `create` activate immediately. Monitoring URLs must
+already be known in the corpus. Use `members` and its `next_cursor` for complete
+membership: policy detail contains a sample. Updates/deletion accept a fetched
+`Policy` or an ID with `expected_version`; conflicts are never retried.
+
+Paginated lists return `Page[T]` (`items`, `next_cursor`). Pass cursors unchanged
+or use `iter()`; membership/invitation lists are bounded snapshots instead.
+Offset-based lists can shift during concurrent changes. Query history and arrivals
+use keyset cursors. UTC usage ranges have an exclusive end date, at most 93 days.
+Query history is best-effort and expires after 30 days; it is not a billing ledger.
+
+`ApiError` includes HTTP status, code, optional request ID, validation fields and
+Retry-After seconds. `TransportError` means the outcome of a write can be unknown.
+Keep creation IDs to reconcile; never blindly retry. Key creation is one-time:
+`created.secret.get_secret_value()` reveals the secret and must only be used for
+secure storage. Its ordinary representation is masked. Lost secrets cannot be
+recovered.
+
+For async streaming, use `async with await client.stream(sql) as stream` followed
+by `async for batch in stream`. Streams validate completion and close on early
+exit, errors, and cancellation. No threads or background polling are introduced.

periplus_python_sdk-0.11.0/README.md

@@ -0,0 +1,130 @@
+# Periplus Python SDK
+
+Typed organization operations and SQL access through the Periplus HTTP API.
+The 0.11.0 platform interface requires the matching API release. It includes
+the source-snapshot metadata introduced in 0.10.0 alongside customer operations.
+Install from PyPI:
+
+```sh
+python -m pip install --upgrade periplus-python-sdk
+```
+
+```python
+from periplus_sdk import Client
+
+with Client("https://api.periplus.dev", api_key="ppl_…") as client:
+    result = client.execute(
+        "SELECT capture_id, url FROM public_v1.captures LIMIT ?", [10]
+    )
+    print(result.columns, result.rows)
+```
+
+The default origin is `https://api.periplus.dev`. Use `PERIPLUS_API_URL` to override it and `PERIPLUS_API_KEY` to
+supply your personal organization API key. A key with `organization:sql:exec`
+is required. Database usernames/passwords and anonymous access are not supported.
+Use HTTPS outside loopback development. Connect directly to the API origin,
+not the public marketing site.
+
+Version 0.9.0 requires personal API keys instead of database credentials. Create
+a key in the app's Settings → My API keys. It inherits your current access in
+that organization; SQL requires your membership to have `organization:sql:exec`.
+For local development, install `./clients/periplus-python-sdk` from the repository
+root and connect to `http://localhost:8000`.
+
+`AsyncClient` accepts the same options. `prepare` explains a SELECT; `execute`
+returns typed columns/rows for read-only queries. `schema()` returns
+visible tables, column types/descriptions and helper documentation. All SQL uses
+`POST /api/v1/sql`; schema discovery uses `GET /api/v1/schema`. ClickHouse enforces
+permissions. The SDK never retries automatically, including failed queries.
+
+Public HTML joins use `parse_id` and `node_index`; `document_id` identifies exact
+raw bytes. Public shorthand uses the `public_v1` schema.
+
+In 0.10.0, `result.source_snapshot` is a typed `SourceSnapshot` containing
+`layout_id` (UUID) and `publication_epoch` (integer), or `None` when no build-bound
+public corpus was read. Buffered, asynchronous, streamed and DB-API results share
+this contract. Compare both fields, not just the epoch. The identity describes
+the public corpus inputs, not any native staff/external inputs. It does not retain
+the data or request historical reads. This replaces the old nullable integer field;
+use this SDK version with the corresponding API release.
+
+For notebook/SQLAlchemy integration:
+
+```python
+from periplus_sdk import sql_api
+from sqlalchemy import text
+
+engine = sql_api.create_engine(base_url="http://localhost:8000", api_key="ppl_…")
+with engine.connect() as connection:
+    print(connection.execute(text("SELECT url FROM public_v1.captures LIMIT 5")).all())
+engine.dispose()
+```
+
+Marimo discovers accessible tables, views, typed columns and comments through the
+schema endpoint. Reflection does not execute SQL. One SQLAlchemy Inspector caches
+its metadata; call `inspector.clear_cache()` to refresh it. Missing metadata raises
+an error rather than presenting an apparently complete empty schema.
+
+The DB-API connection advertises the ClickHouse dialect and converts native
+nullable integer, decimal, date and datetime types. Nested types retain JSON wire
+values. Writes are not exposed through the query API. There are no client
+transactions; each statement is independent.
+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).
+
+## Organization resources
+
+The same key selects your organization and inherits your live membership access.
+`Client` and `AsyncClient` expose the same namespaces:
+
+| Namespace | Operations |
+| --- | --- |
+| `identity`, `availability` | `get` |
+| `discovery` | `create`, `get`, `list`, `iter`, `arrivals`, `cancel` |
+| `retention`, `monitoring` | `create`, `preview`, `activate`, `get`, `list`, `iter`, `members`, `update`, `pause`, `resume`, `delete` |
+| `saved_queries` | `create`, `get`, `list`, `iter`, `rename`, `delete` |
+| `members` | `list`, `update_role`, `remove` |
+| `invitations` | `list`, `create`, `cancel` |
+| `api_keys` | `create`, `list`, `iter`, `revoke` |
+| `usage` | `get` |
+| `query_history` | `list`, `iter`, `get`, `summary` |
+| `audit` | `list`, `iter` |
+
+```python
+from periplus_sdk import Client
+
+with Client() as client:
+    preview = client.retention.preview(
+        name="Research sources", days=90,
+        sql="SELECT capture_id FROM captures WHERE domain(url) = ?",
+        parameters=["example.com"],
+    )
+    print(preview.id, preview.capture_count, preview.sample)
+    # Review the selection before calling:
+    # active = client.retention.activate(preview)
+```
+
+SQL previews persist inactive, frozen selections; activation never reruns SQL.
+Explicit IDs/URLs passed to `create` activate immediately. Monitoring URLs must
+already be known in the corpus. Use `members` and its `next_cursor` for complete
+membership: policy detail contains a sample. Updates/deletion accept a fetched
+`Policy` or an ID with `expected_version`; conflicts are never retried.
+
+Paginated lists return `Page[T]` (`items`, `next_cursor`). Pass cursors unchanged
+or use `iter()`; membership/invitation lists are bounded snapshots instead.
+Offset-based lists can shift during concurrent changes. Query history and arrivals
+use keyset cursors. UTC usage ranges have an exclusive end date, at most 93 days.
+Query history is best-effort and expires after 30 days; it is not a billing ledger.
+
+`ApiError` includes HTTP status, code, optional request ID, validation fields and
+Retry-After seconds. `TransportError` means the outcome of a write can be unknown.
+Keep creation IDs to reconcile; never blindly retry. Key creation is one-time:
+`created.secret.get_secret_value()` reveals the secret and must only be used for
+secure storage. Its ordinary representation is masked. Lost secrets cannot be
+recovered.
+
+For async streaming, use `async with await client.stream(sql) as stream` followed
+by `async for batch in stream`. Streams validate completion and close on early
+exit, errors, and cancellation. No threads or background polling are introduced.