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:

python -m pip install --upgrade periplus-python-sdk

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:

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 and query boundary.

Organization resources

The same key selects your organization and inherits your live membership access. Client and AsyncClient expose the same namespaces:

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.