volcano-sdk-python 0.9.1__tar.gz → 0.9.3__tar.gz

volcano_sdk_python-0.9.3/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.9.3"
+}

{volcano_sdk_python-0.9.1 → volcano_sdk_python-0.9.3}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.9.3](https://github.com/Kong/volcano-sdk-python/compare/v0.9.2...v0.9.3) (2026-09-18)
+
+
+### Bug Fixes
+
+* **functions:** recover rejected user sessions before dispatch ([#173](https://github.com/Kong/volcano-sdk-python/issues/173)) ([ab76b7f](https://github.com/Kong/volcano-sdk-python/commit/ab76b7f6448022fb2101cff5382fdfdac1861c26))
+
+## [0.9.2](https://github.com/Kong/volcano-sdk-python/compare/v0.9.1...v0.9.2) (2026-09-18)
+
+
+### Bug Fixes
+
+* **realtime:** fetch rows from custom Postgres schemas ([#171](https://github.com/Kong/volcano-sdk-python/issues/171)) ([2a54e95](https://github.com/Kong/volcano-sdk-python/commit/2a54e957975792a6a092121786992f0a917d4aa5))
+
 ## [0.9.1](https://github.com/Kong/volcano-sdk-python/compare/v0.9.0...v0.9.1) (2026-09-18)
 
 

{volcano_sdk_python-0.9.1 → volcano_sdk_python-0.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: volcano-sdk-python
-Version: 0.9.1
+Version: 0.9.3
 Summary: Official Python SDK for Volcano
 Project-URL: Homepage, https://volcano.dev
 Project-URL: Repository, https://github.com/Kong/volcano-sdk-python
@@ -79,14 +79,18 @@ function = client.functions.invoke(
 )
 print(function.status, function.version, function.data)
 
-logs = client.logs.search(
+# Project logs use a control-plane project token, not this end-user session.
+logs_client = VolcanoClient(
+    anon_key="ak_your_anon_key", access_token="vpat_your_project_token"
+)
+logs = logs_client.logs.search(
     "00000000-0000-4000-8000-000000000001",
     {"resource": {"type": "function"}, "limit": 100},
 )
 for event in logs.data:
     print(event["timestamp"], event["body"])
 
-activity = client.logs.activity(
+activity = logs_client.logs.activity(
     "00000000-0000-4000-8000-000000000001",
     {"resource": {"type": "function"}, "bucket_count": 24},
 )
@@ -220,13 +224,23 @@ user session; the function receives no user identity. The immutable result
 includes the response body, status, headers, and `X-Volcano-Version`. The body
 can be a JSON object, array, scalar, or text; an empty body returns `None`.
 JSON arrays become immutable tuples. Invalid JSON is returned as text. A
-function's own non-2xx response is returned when the version header proves it
-ran; platform failures raise typed SDK errors.
+function's own non-2xx response is returned when Volcano confirms it ran;
+non-success platform HTTP responses raise typed SDK errors.
+
+
+Function resolution and invocation recover from a platform HTTP 401 before dispatch:
+the SDK refreshes the captured session and retries the rejected request once.
+Concurrent calls share successful recovery. Replacing or signing out that session
+prevents replay under another identity. The call preserves its original payload values.
+A function's own response, HTTP 403, or a network failure never triggers this retry.
+Anonymous and service keys do not refresh.
 
 `logs.search()` returns an immutable page of retained runtime or deployment log
 events. Pass `next_cursor` back as `cursor` to continue a search. `logs.activity()`
 returns immutable time buckets using the same resource selector and query syntax.
-Both methods require an active user session.
+Both methods require a platform user token or a project access token.
+A `read_only` project token is sufficient; end-user sessions cannot read project logs.
+See the [logs guide](https://github.com/Kong/volcano-sdk-python/blob/main/docs/logs.md).
 
 Database selects, inserts, updates, deletes, log reads, and authenticated storage
 requests (including upload sessions and parts) refresh the captured
@@ -784,12 +798,12 @@ stop_changes()
 ```
 
 Binding a database automatically fetches the matching row for lightweight
-`INSERT` and `UPDATE` notifications in the `public` schema. The fetch uses the
+`INSERT` and `UPDATE` notifications in public or custom schemas. The fetch uses the
 realtime connection's RLS-scoped access token. Compatible row lookups are
 batched while callback delivery preserves publication order.
 If the row is absent or the query fails, the callback receives the lightweight
-notification with its `id` and `mode` intact. Non-public schemas also retain
-that lightweight form. Lightweight deletes never query the database; they
+notification with its `id` and `mode` intact. Custom-schema row lookups preserve
+the schema from the notification. Lightweight deletes never query the database; they
 preserve `old_record`, or provide `{"id": change.id}` when no old row was
 included. Tune a channel's batching with `fetch_batch_window_ms` and
 `fetch_max_batch_size`; the defaults are 20 milliseconds and 50 rows. Set

{volcano_sdk_python-0.9.1 → volcano_sdk_python-0.9.3}/README.md

@@ -57,14 +57,18 @@ function = client.functions.invoke(
 )
 print(function.status, function.version, function.data)
 
-logs = client.logs.search(
+# Project logs use a control-plane project token, not this end-user session.
+logs_client = VolcanoClient(
+    anon_key="ak_your_anon_key", access_token="vpat_your_project_token"
+)
+logs = logs_client.logs.search(
     "00000000-0000-4000-8000-000000000001",
     {"resource": {"type": "function"}, "limit": 100},
 )
 for event in logs.data:
     print(event["timestamp"], event["body"])
 
-activity = client.logs.activity(
+activity = logs_client.logs.activity(
     "00000000-0000-4000-8000-000000000001",
     {"resource": {"type": "function"}, "bucket_count": 24},
 )
@@ -198,13 +202,23 @@ user session; the function receives no user identity. The immutable result
 includes the response body, status, headers, and `X-Volcano-Version`. The body
 can be a JSON object, array, scalar, or text; an empty body returns `None`.
 JSON arrays become immutable tuples. Invalid JSON is returned as text. A
-function's own non-2xx response is returned when the version header proves it
-ran; platform failures raise typed SDK errors.
+function's own non-2xx response is returned when Volcano confirms it ran;
+non-success platform HTTP responses raise typed SDK errors.
+
+
+Function resolution and invocation recover from a platform HTTP 401 before dispatch:
+the SDK refreshes the captured session and retries the rejected request once.
+Concurrent calls share successful recovery. Replacing or signing out that session
+prevents replay under another identity. The call preserves its original payload values.
+A function's own response, HTTP 403, or a network failure never triggers this retry.
+Anonymous and service keys do not refresh.
 
 `logs.search()` returns an immutable page of retained runtime or deployment log
 events. Pass `next_cursor` back as `cursor` to continue a search. `logs.activity()`
 returns immutable time buckets using the same resource selector and query syntax.
-Both methods require an active user session.
+Both methods require a platform user token or a project access token.
+A `read_only` project token is sufficient; end-user sessions cannot read project logs.
+See the [logs guide](https://github.com/Kong/volcano-sdk-python/blob/main/docs/logs.md).
 
 Database selects, inserts, updates, deletes, log reads, and authenticated storage
 requests (including upload sessions and parts) refresh the captured
@@ -762,12 +776,12 @@ stop_changes()
 ```
 
 Binding a database automatically fetches the matching row for lightweight
-`INSERT` and `UPDATE` notifications in the `public` schema. The fetch uses the
+`INSERT` and `UPDATE` notifications in public or custom schemas. The fetch uses the
 realtime connection's RLS-scoped access token. Compatible row lookups are
 batched while callback delivery preserves publication order.
 If the row is absent or the query fails, the callback receives the lightweight
-notification with its `id` and `mode` intact. Non-public schemas also retain
-that lightweight form. Lightweight deletes never query the database; they
+notification with its `id` and `mode` intact. Custom-schema row lookups preserve
+the schema from the notification. Lightweight deletes never query the database; they
 preserve `old_record`, or provide `{"id": change.id}` when no old row was
 included. Tune a channel's batching with `fetch_batch_window_ms` and
 `fetch_max_batch_size`; the defaults are 20 milliseconds and 50 rows. Set

{volcano_sdk_python-0.9.1 → volcano_sdk_python-0.9.3}/docs/README.md

@@ -118,3 +118,12 @@ See [release notes](https://github.com/Kong/volcano-sdk-python/releases) for ver
 Include the package version, Python version, and a minimal reproduction without credentials.
 
 See [Distributed locks](./locks.md) for acquisition recovery, renewal, and fencing.
+
+Read the [database guide](./database.md) for projection, filters, ordered pagination, and mutations.
+
+For uploads, visibility, and resumable sessions, see [Storage](./storage.md).
+
+See [Logs](./logs.md) for project-token authentication, search, pagination, and activity.
+
+
+See [Realtime](./realtime.md) for broadcasts, presence, database changes, and shutdown.

volcano_sdk_python-0.9.3/docs/database.md

@@ -0,0 +1,85 @@
+---
+title: Database queries
+description: Read and change Postgres rows through the Python SDK with filters, ordering, and pagination.
+order: 3
+---
+
+Query an existing database and table using the signed-in user's permissions.
+This example expects a `main` database with an `items` table containing `id`, `name`, and `status` columns, plus Row-Level Security policies that permit the user to read those rows.
+Set the credentials described in the [quickstart](./README.md).
+
+```python
+import os
+
+from volcano_sdk import VolcanoClient
+
+client = VolcanoClient(
+    anon_key=os.environ["VOLCANO_ANON_KEY"],
+    api_url=os.environ.get("VOLCANO_API_URL", "https://api.volcano.dev"),
+)
+client.auth.sign_in(
+    email=os.environ["VOLCANO_USER_EMAIL"],
+    password=os.environ["VOLCANO_USER_PASSWORD"],
+)
+items = client.database("main").from_("items")
+rows = items.select("id", "name").eq("status", "published").execute()
+for row in rows:
+    print(row["id"], row["name"])
+```
+
+`execute()` returns a list of row dictionaries, including an empty list when no rows match.
+Builders are immutable; each chained operation returns a new builder, so a base query can be reused.
+The following examples reuse an authenticated `client` and the same table.
+
+## Filter, sort, and page through rows
+
+```python
+base = client.database("main").from_("items").select("id", "name")
+rows = (
+    base.ilike("name", "%volcano%")
+    .in_("status", ["draft", "published"])
+    .order("name")
+    .order("id")
+    .limit(20)
+    .offset(40)
+    .execute()
+)
+```
+
+| Methods | Filter |
+| --- | --- |
+| `eq`, `neq` | Equal or not equal to a value |
+| `gt`, `gte`, `lt`, `lte` | Compare values |
+| `like`, `ilike` | Case-sensitive or case-insensitive SQL pattern; `%` matches any sequence |
+| `is_("deleted_at", None)` | Match a SQL null |
+| `is_("enabled", True)` | Match a SQL boolean |
+| `in_("status", ["draft", "published"])` | Match a member of a list |
+
+Use `select("*")` to return every column.
+Pass `ascending=False` to `order()` for descending order.
+Include a unique final sort column such as `id` when paging with `limit()` and `offset()`.
+
+## Insert, update, and delete
+
+```python
+items = client.database("main").from_("items")
+created = items.insert({"name": "Volcano", "status": "draft"}).execute()
+item_id = created[0]["id"]
+updated = items.update({"status": "published"}).eq("id", item_id).execute()
+deleted = items.delete().eq("id", item_id).execute()
+```
+
+Mutations return a list of the affected rows.
+Updates and deletes with no matches return an empty list.
+They require at least one filter; Volcano rejects filterless updates and deletes.
+
+## Handle authentication failures
+
+Database reads and mutations refresh a rejected access token once when the captured session has a usable refresh token, then retry the same request.
+HTTP 403 responses and network failures do not trigger this retry.
+Mutations are never retried after an ambiguous transport failure.
+Replacing or signing out the session during recovery raises `SessionChangedError` instead of replaying under another user.
+
+For direct Postgres connections inside a Volcano function, `database_connection_string()` can derive a connection string from `DATABASE_URL` and a server-validated `user_id` while preserving its database target.
+Passing a user ID applies that user's Row-Level Security context; omitting it requests service access.
+Keep the resulting connection string private.

volcano_sdk_python-0.9.3/docs/logs.md

@@ -0,0 +1,54 @@
+---
+title: Logs
+description: Search retained project logs, paginate events, and read activity counts.
+order: 6
+---
+
+Search logs and inspect activity for resources in your project.
+
+Project logs require a platform user token or a [project access token](/platform/api-reference/using-the-api). For server-side log readers, create a `read_only` project token and set `VOLCANO_PROJECT_ACCESS_TOKEN`, `VOLCANO_PROJECT_ID`, and `VOLCANO_ANON_KEY`. Keep this credential on your server. The constructor requires an anon key, but the supplied project access token authorizes these requests. Project end-user sign-in, anon keys, and service keys do not grant project log access.
+
+```python
+import os
+from volcano_sdk import VolcanoClient
+
+project_id = os.environ["VOLCANO_PROJECT_ID"]
+client = VolcanoClient(
+    anon_key=os.environ["VOLCANO_ANON_KEY"],
+    api_url=os.environ.get("VOLCANO_API_URL", "https://api.volcano.dev"),
+    access_token=os.environ["VOLCANO_PROJECT_ACCESS_TOKEN"],
+)
+request = {"resource": {"type": "function"}, "q": "checkout_failed", "limit": 100}
+page = client.logs.search(project_id, request)
+for event in page.data:
+    print(event["timestamp"], event["body"])
+```
+
+`search()` returns an immutable `LogSearchResponse` with `data`, `limit`, `has_more`, and `next_cursor`.
+
+## Continue a search
+
+```python
+if page.has_more and page.next_cursor:
+    next_page = client.logs.search(project_id, {**request, "cursor": page.next_cursor})
+```
+
+## Read activity buckets
+
+```python
+activity = client.logs.activity(
+    project_id,
+    {"resource": request["resource"], "q": request["q"], "bucket_count": 24},
+)
+print(activity.total)
+for bucket in activity.data:
+    print(bucket["start_time"], bucket["counts"], bucket["total"])
+```
+
+Keep the same resource selector, query, and time bounds on every pagination request. Results are newest first. `body` preserves JSON values, including objects and arrays; it is not always a string. Events include a stable `id`, `timestamp`, and owning `resource`.
+
+Activity returns time buckets and a total count. Each bucket contains `start_time`, `end_time`, `total`, and `counts` grouped by `levels`, `regions`, and `resource_ids`.
+
+Both methods accept `resource.ids` to restrict results to specific resources, `q` for text or field queries, and RFC3339 `start_time` and `end_time` bounds. Logs arrive asynchronously; use bounded polling when waiting for a new event. These methods read retained logs rather than open a live stream.
+
+A project token has no refresh token. The SDK sends it as supplied and surfaces authentication failures; rotate or replace expired credentials through project token management. Do not use auth sign-out to revoke a project token.

volcano_sdk_python-0.9.3/docs/realtime.md

@@ -0,0 +1,125 @@
+---
+title: Realtime
+description: Send broadcasts, observe presence, and receive database changes with Python async channels.
+order: 8
+---
+
+Subscribe to a broadcast channel and send a JSON publication using Python's async lifecycle.
+Sign in with the [quickstart credentials](./README.md) and enable the project's realtime capabilities and access policies.
+
+```python
+import asyncio
+import os
+
+from volcano_sdk import VolcanoClient
+
+client = VolcanoClient(
+    anon_key=os.environ["VOLCANO_ANON_KEY"],
+    api_url=os.environ.get("VOLCANO_API_URL", "https://api.volcano.dev"),
+)
+client.auth.sign_in(
+    email=os.environ["VOLCANO_USER_EMAIL"],
+    password=os.environ["VOLCANO_USER_PASSWORD"],
+)
+
+
+async def main():
+    channel = client.realtime.channel("updates")
+    channel.on("message", lambda message: print(message))
+    try:
+        await channel.subscribe()
+        await channel.send({"event": "message", "value": "hello"})
+        await asyncio.sleep(2)
+    finally:
+        await client.realtime.disconnect()
+
+
+asyncio.run(main())
+```
+
+`subscribe()` waits for the server acknowledgement; a presence subscription also waits for its initial roster.
+Channel names receive their type prefix, so `updates` becomes `broadcast:updates`.
+Use the same event loop for a client's realtime operations.
+The following channel examples belong inside an async function with an authenticated `client`.
+
+## Pause or remove channels
+
+```python
+channel = client.realtime.channel("updates")
+channel.on("message", print)
+await channel.subscribe()
+await channel.unsubscribe()
+await channel.subscribe()
+await client.realtime.remove_channel("updates")
+```
+
+Unsubscribe pauses delivery while retaining handlers and the in-memory broadcast recovery position.
+Subscribe resumes and requests missed broadcasts when retained history is available.
+Pausing discards queued callbacks; a callback already running may finish.
+Removal forgets the channel and its recovery position.
+`remove_all_channels()` removes all channels while leaving the shared connection available; `disconnect()` closes it.
+Application code owns any work its callbacks start and should await that work during shutdown.
+
+## Observe presence
+
+```python
+lobby = client.realtime.channel("lobby", channel_type="presence")
+stop_sync = lobby.on_presence_sync(lambda state: print("Online", len(state)))
+lobby.on("join", lambda info: print("Joined", info.user))
+lobby.on("leave", lambda info: print("Left", info.user))
+await lobby.subscribe()
+await lobby.track({"status": "online"})
+print(lobby.tracked_state)
+print(lobby.get_presence_state())
+await client.realtime.remove_channel("lobby", channel_type="presence")
+stop_sync()
+```
+
+Presence identity and metadata come from the authenticated user.
+`track()` stores optional local application state; it does not replace server-managed presence metadata.
+The roster maps connection IDs to immutable client identity and user metadata snapshots.
+One user can have several connections. The original sync callback observes connections joining and leaving.
+The roster is refreshed after reconnection; a failed roster query reports an error and clears the snapshot.
+
+## Subscribe to database changes
+
+Use an existing `app` database and `public.messages` table with realtime and suitable Row-Level Security policies configured:
+
+```python
+client.realtime.set_database_name("app")
+changes = client.realtime.channel("public:messages", channel_type="postgres")
+stop_changes = changes.on_postgres_changes(
+    "INSERT",
+    schema="public",
+    table="messages",
+    callback=lambda change: print(change.record),
+)
+await changes.subscribe()
+await asyncio.sleep(30)
+stop_changes()
+await client.realtime.remove_channel("public:messages", channel_type="postgres")
+```
+
+Insert a row from another client during the listening period.
+Automatic row lookup requires a primary key named `id`. It reads the current row after the notification; rapid updates may have already changed that row.
+Matching insert and update notifications can fetch full rows using the subscription's user token.
+Compatible row lookups are batched while publication order is preserved.
+Defaults are a 20 millisecond window and 50 rows; set `fetch_batch_window_ms` and `fetch_max_batch_size` on the channel to change them.
+Set `auto_fetch=False` when first creating the channel or `set_database_name(None)` to retain lightweight notifications without row lookups.
+For a custom schema, use its `schema:table` channel name and matching schema/table filters; row lookups preserve that schema.
+Missing rows and failed lookups retain the lightweight notification.
+Deletes use `old_record` or the row ID and do not query the database.
+
+## Handle connection changes
+
+```python
+stop_errors = client.realtime.on_error(lambda context: print(context.message))
+stop_connected = client.realtime.on_connect(lambda context: print(context.client))
+stop_disconnected = client.realtime.on_disconnect(lambda context: print(context.reason))
+```
+
+Each registration returns an idempotent unsubscribe function.
+Callbacks receive immutable contexts and run outside connection processing.
+Broadcast recovery stays within one client lifetime and one authenticated session lineage; it is not persisted across processes.
+After signing in again or changing users, disconnect before subscribing for the new session.
+Do not use realtime delivery as a durable record of every database change.

volcano_sdk_python-0.9.3/docs/storage.md

@@ -0,0 +1,116 @@
+---
+title: Storage
+description: Upload, download, list, move, and resume files using the Python SDK.
+order: 4
+---
+
+Upload and read bytes from an existing `assets` bucket whose policies permit the signed-in user to access the object.
+Set the [quickstart credentials](./README.md).
+
+```python
+import os
+
+from volcano_sdk import VolcanoClient
+
+client = VolcanoClient(
+    anon_key=os.environ["VOLCANO_ANON_KEY"],
+    api_url=os.environ.get("VOLCANO_API_URL", "https://api.volcano.dev"),
+)
+client.auth.sign_in(
+    email=os.environ["VOLCANO_USER_EMAIL"],
+    password=os.environ["VOLCANO_USER_PASSWORD"],
+)
+bucket = client.storage.from_("assets")
+bucket.upload("examples/hello.txt", b"hello", content_type="text/plain")
+assert bucket.download("examples/hello.txt") == b"hello"
+print(bucket.download("examples/hello.txt", byte_range="bytes=1-3"))
+```
+
+Uploads accept bytes or a binary file-like object; downloads return bytes.
+An omitted `content_type` uses `application/octet-stream`.
+Explicit content types must be non-blank printable ASCII and may include MIME parameters.
+The following examples reuse an authenticated `client` and `bucket`.
+
+## List and manage objects
+
+```python
+page = bucket.list("examples", limit=100)
+for object_ in page.objects:
+    print(object_.name)
+if page.next_cursor is not None:
+    next_page = bucket.list("examples", limit=100, cursor=page.next_cursor)
+
+copied = bucket.copy("examples/hello.txt", "examples/hello-copy.txt")
+moved = bucket.move("examples/hello-copy.txt", "examples/hello-moved.txt")
+removed = bucket.remove(["examples/hello-moved.txt"])
+```
+
+Copy preserves its source; move removes its source after creating the destination.
+Object metadata and listing responses are immutable.
+`remove()` accepts one path or a sequence and returns removed paths as a tuple.
+It processes paths in order; a failure raises after earlier successful deletions.
+
+## Control public visibility
+
+```python
+object_ = bucket.update_visibility("examples/hello.txt", is_public=True)
+print(object_.public_url)
+url = bucket.get_public_url("examples/hello.txt")
+```
+
+`update_visibility()` returns server-confirmed metadata; its `public_url` is populated only for a public object.
+`get_public_url()` constructs a URL locally and does not check whether the object exists or is public.
+Pass `is_public=False` to make an object private again.
+
+## Upload a file in parts
+
+```python
+with open("video.mp4", "rb") as source:
+    uploaded = bucket.upload_resumable(
+        "videos/demo.mp4",
+        source,
+        content_type="video/mp4",
+        on_progress=lambda sent, total: print(f"{sent}/{total}"),
+    )
+print(uploaded.name)
+```
+
+The helper creates an upload session, uses the server-selected part size, and completes the object.
+It streams seekable files and spools non-seekable inputs to a temporary file with bounded reads.
+Progress runs after each successful part with cumulative uploaded bytes and total size.
+If a part or progress callback fails, the helper attempts to abort and raises the original error.
+
+## Resume or cancel an upload session
+
+For application-managed recovery, retain the session ID and upload progress yourself:
+
+```python
+payload = b"example file"
+session = bucket.create_upload_session(
+    "examples/resumable.txt",
+    total_size=len(payload),
+    content_type="text/plain",
+)
+for offset in range(0, len(payload), session.part_size):
+    bucket.upload_part(
+        "examples/resumable.txt",
+        session_id=session.session_id,
+        part_number=offset // session.part_size + 1,
+        data=payload[offset : offset + session.part_size],
+    )
+status = bucket.get_upload_session(
+    "examples/resumable.txt", session_id=session.session_id
+)
+print(status.parts_uploaded, status.bytes_uploaded)
+completed = bucket.complete_upload_session(
+    "examples/resumable.txt", session_id=session.session_id
+)
+```
+
+The server returns the part size, total part count, and session expiration.
+`get_upload_session()` exposes uploaded-part metadata to help an application resume.
+Uploading the same part number again replaces that part.
+To abandon an unfinished session, call `bucket.abort_upload_session(path, session_id=session_id)`; this discards its uploaded parts without publishing an object. Further session-status requests report not found.
+
+Authenticated storage requests refresh and retry once after an explicit HTTP 401 when a refresh token is available.
+They preserve the original request and session ownership, and do not retry ambiguous network failures or HTTP 403 responses.