volcano-sdk-python 0.7.1__tar.gz → 0.7.3__tar.gz

volcano_sdk_python-0.7.3/.github/workflows/lint-docs.yml

@@ -0,0 +1,16 @@
+name: Lint docs
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/lint-docs.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  docs:
+    uses: Kong/volcano-docs/.github/workflows/lint-docs.yml@2eed9e93cae0b070f57788e7c270ccfbb4cd4579
+    with:
+      path: docs

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

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

{volcano_sdk_python-0.7.1 → volcano_sdk_python-0.7.3}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.7.3](https://github.com/Kong/volcano-sdk-python/compare/v0.7.2...v0.7.3) (2026-09-17)
+
+
+### Bug Fixes
+
+* **auth:** refresh rejected profile requests within their session ([#157](https://github.com/Kong/volcano-sdk-python/issues/157)) ([534e5e2](https://github.com/Kong/volcano-sdk-python/commit/534e5e270c94cad758779d98714b217263537dc0))
+
+## [0.7.2](https://github.com/Kong/volcano-sdk-python/compare/v0.7.1...v0.7.2) (2026-09-17)
+
+
+### Bug Fixes
+
+* **storage:** refresh rejected sessions and replay bounded requests ([#154](https://github.com/Kong/volcano-sdk-python/issues/154)) ([5b1f93f](https://github.com/Kong/volcano-sdk-python/commit/5b1f93fa59fda0a5cd5b06c6e9cc2da3f372ab8a))
+
 ## [0.7.1](https://github.com/Kong/volcano-sdk-python/compare/v0.7.0...v0.7.1) (2026-09-17)
 
 

{volcano_sdk_python-0.7.1 → volcano_sdk_python-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: volcano-sdk-python
-Version: 0.7.1
+Version: 0.7.3
 Summary: Official Python SDK for Volcano
 Project-URL: Homepage, https://volcano.dev
 Project-URL: Repository, https://github.com/Kong/volcano-sdk-python
@@ -25,6 +25,8 @@ Description-Content-Type: text/markdown
 Use the Volcano Python SDK to access authentication, databases, storage,
 functions, locks, logs, and realtime events. Requires Python 3.11 or later.
 
+Start with the [Python quickstart](https://github.com/Kong/volcano-sdk-python/blob/main/docs/README.md).
+
 ## Install
 
 ```shell
@@ -219,7 +221,8 @@ 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.
 
-Database selects, inserts, updates, deletes, and log reads refresh the captured
+Database selects, inserts, updates, deletes, log reads, and authenticated storage
+requests (including upload sessions and parts) refresh the captured
 session after an HTTP 401 and retry the same request once. Concurrent requests reuse a successful
 refresh for that session.
 Replacing or signing out the session before replay, or while replay is in flight,

{volcano_sdk_python-0.7.1 → volcano_sdk_python-0.7.3}/README.md

@@ -3,6 +3,8 @@
 Use the Volcano Python SDK to access authentication, databases, storage,
 functions, locks, logs, and realtime events. Requires Python 3.11 or later.
 
+Start with the [Python quickstart](https://github.com/Kong/volcano-sdk-python/blob/main/docs/README.md).
+
 ## Install
 
 ```shell
@@ -197,7 +199,8 @@ 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.
 
-Database selects, inserts, updates, deletes, and log reads refresh the captured
+Database selects, inserts, updates, deletes, log reads, and authenticated storage
+requests (including upload sessions and parts) refresh the captured
 session after an HTTP 401 and retry the same request once. Concurrent requests reuse a successful
 refresh for that session.
 Replacing or signing out the session before replay, or while replay is in flight,

volcano_sdk_python-0.7.3/docs/README.md

@@ -0,0 +1,82 @@
+---
+title: Python SDK
+description: Install the Volcano Python SDK and authenticate a user from a Python application.
+order: 1
+---
+
+Use `volcano-sdk-python` for authentication, database queries, storage, functions, logs, locks, and realtime events.
+REST calls are synchronous and raise typed exceptions on failure.
+Python 3.11 or later is required; CI tests Python 3.11 and 3.14.
+
+## Install the published package
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install volcano-sdk-python
+```
+
+The [PyPI distribution](https://pypi.org/project/volcano-sdk-python/) is named `volcano-sdk-python`.
+Import it as `volcano_sdk`.
+The package includes type information for mypy and other PEP 561-compatible checkers.
+
+## Sign in and read a profile
+
+Create a project, enable [email and password authentication](/platform/authentication/configuring-auth-methods), and create a user with a confirmed email when your project requires confirmation.
+Use that project's [anonymous key](/platform/authentication/security/anon-keys).
+Set `VOLCANO_ANON_KEY`, `VOLCANO_USER_EMAIL`, and `VOLCANO_USER_PASSWORD` in your environment.
+Set `VOLCANO_API_URL` only when using a different API endpoint, such as local mode.
+
+Save this as `quickstart.py`:
+
+```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"),
+)
+session = client.auth.sign_in(
+    email=os.environ["VOLCANO_USER_EMAIL"],
+    password=os.environ["VOLCANO_USER_PASSWORD"],
+)
+try:
+    user = client.auth.get_user()
+    assert user.id == session.user_id
+    print(f"Signed in as {user.email}")
+finally:
+    client.auth.sign_out()
+```
+
+Run it with `python quickstart.py`.
+It signs in, fetches the server-validated profile, prints the user's email, revokes its refresh token, and clears the local session.
+An invalid email or password raises `AuthenticationError`; failed network requests raise `TransportError`.
+Both inherit from `VolcanoError` and are exported from `volcano_sdk`.
+
+## Keep authentication scoped to one user
+
+A client holds its current session in memory.
+Use a separate client for each independent user session; do not share one mutable client across users in a web server.
+`client.current_session` and `client.auth.get_session()` read the local immutable snapshot without a request.
+Use `client.auth.get_user()` when you need a server-validated profile.
+Successful profile operations update the cached user while preserving the current credentials.
+If `get_user()`, `update_user()`, `convert_anonymous()`, or `confirm_email_change()` receives an HTTP 401 and the session has a usable refresh token, the client refreshes once and retries with the original request values.
+These operations do not retry other HTTP failures or ambiguous network failures, and they never retry under a replacement session.
+
+`sign_up()` returns an acknowledgement without signing in by default.
+Pass `sign_in_when_allowed=True` to sign in only when the project does not require email confirmation.
+To adopt an existing session, pass a `Session` containing its access token, refresh token, and user ID to `client.auth.set_session()`.
+The SDK does not persist tokens for you.
+
+For operations that require a [service key](/platform/authentication/security/service-keys), pass `service_key` to the constructor in trusted server code.
+Keep service keys and user credentials out of source control and client applications.
+
+## Use the rest of the API
+
+The SDK repository contains [examples for every public facade](https://github.com/Kong/volcano-sdk-python#try-the-contract-facade), including database filters and mutations, resumable uploads, function invocation, log queries, lock guards, and realtime presence and database changes.
+Realtime uses an asynchronous lifecycle; follow those examples to connect and disconnect its channels.
+
+See [release notes](https://github.com/Kong/volcano-sdk-python/releases) for version changes and [GitHub issues](https://github.com/Kong/volcano-sdk-python/issues) to report a problem.
+Include the package version, Python version, and a minimal reproduction without credentials.

volcano_sdk_python-0.7.3/features/staged/README.md

@@ -0,0 +1,11 @@
+# Staged contract scenarios
+
+These copies are pending additions to hosting's canonical SDK contract. They do
+not count as active coverage and ordinary contract runs do not execute them.
+Keep each file byte-identical to its coordinated hosting change and add its
+language binding before merging the SDK change.
+
+Hosting activates a scenario only after every SDK has the matching copy. Once
+that hosting change reaches main, move the copy into `features/contract` and
+update the native copy checks. Keep active copies unchanged until activation;
+hosting's current main must remain compatible throughout the rollout.

volcano_sdk_python-0.7.3/features/staged/auth-profile-refresh.feature

@@ -0,0 +1,10 @@
+Feature: SDK profile authentication recovery
+
+  @auth @SDK-AUTH-007
+  Scenario: A rejected profile read refreshes the session and caches the same user
+    Given an authenticated client
+    And the client replaces its access token with a rejected token
+    When the client loads its server-validated profile
+    Then the SDK operation succeeds
+    And the returned and cached profiles belong to the contract user
+    And the profile read replaces the rejected token for the same user

volcano_sdk_python-0.7.3/features/staged/storage-refresh.feature

@@ -0,0 +1,11 @@
+Feature: SDK storage authentication recovery
+
+  @storage @SDK-STORAGE-005
+  Scenario: A rejected upload refreshes the session and preserves its bytes
+    Given an authenticated client
+    And the client replaces its access token with a rejected token
+    When the client uploads and downloads the contract object
+    Then the SDK operation succeeds
+    And the downloaded bytes equal the uploaded bytes
+    And the stored object path equals the contract path
+    And the storage operation replaces the rejected token for the same user

{volcano_sdk_python-0.7.1 → volcano_sdk_python-0.7.3}/features/steps/sdk_contract_steps.py

@@ -175,6 +175,8 @@ def replace_access_token(context: Any) -> None:
     )
 
 
+@then("the profile read replaces the rejected token for the same user")
+@then("the storage operation replaces the rejected token for the same user")
 @then("the database read replaces the rejected token for the same user")
 def read_replaced_token(context: Any) -> None:
     world = _world(context)
@@ -186,6 +188,23 @@ def read_replaced_token(context: Any) -> None:
     assert session.user_id == world.fixture["user_id"]
 
 
+@when("the client loads its server-validated profile")
+def load_server_profile(context: Any) -> None:
+    world = _world(context)
+    world.record(world.client.auth.get_user)
+
+
+@then("the returned and cached profiles belong to the contract user")
+def profiles_belong_to_contract_user(context: Any) -> None:
+    world = _world(context)
+    assert world.last_outcome is not None
+    assert world.last_outcome.value.id == world.fixture["user_id"]
+    session = world.client.current_session
+    assert session is not None
+    assert session.user is not None
+    assert session.user["id"] == world.fixture["user_id"]
+
+
 @when("one client pauses delivery for 1 second and then resumes with the same handler")
 def pause_and_resume(context: Any) -> None:
     world = _world(context)

{volcano_sdk_python-0.7.1 → volcano_sdk_python-0.7.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "volcano-sdk-python"
-version = "0.7.1"
+version = "0.7.3"
 description = "Official Python SDK for Volcano"
 readme = "README.md"
 requires-python = ">=3.11"

{volcano_sdk_python-0.7.1 → volcano_sdk_python-0.7.3}/src/volcano_sdk/_transport.py

@@ -13,14 +13,10 @@ from uuid import UUID, uuid4
 import httpx
 
 from ._generated.api.authentication import (
-    auth_confirm_email_change,
-    auth_convert_anonymous,
-    auth_get_user,
     auth_logout,
     auth_refresh,
     auth_signin,
     auth_signup,
-    auth_update_user,
 )
 from ._generated.api.authentication.auth_cancel_email_change import (
     _get_kwargs as cancel_email_change_kwargs,
@@ -28,6 +24,18 @@ from ._generated.api.authentication.auth_cancel_email_change import (
 from ._generated.api.authentication.auth_confirm_email import (
     _get_kwargs as confirm_email_kwargs,
 )
+from ._generated.api.authentication.auth_confirm_email_change import (
+    _build_response as build_auth_confirm_email_change_response,
+)
+from ._generated.api.authentication.auth_confirm_email_change import (
+    _get_kwargs as auth_confirm_email_change_kwargs,
+)
+from ._generated.api.authentication.auth_convert_anonymous import (
+    _build_response as build_auth_convert_anonymous_response,
+)
+from ._generated.api.authentication.auth_convert_anonymous import (
+    _get_kwargs as auth_convert_anonymous_kwargs,
+)
 from ._generated.api.authentication.auth_delete_all_my_sessions import (
     _get_kwargs as delete_all_my_sessions_kwargs,
 )
@@ -40,6 +48,12 @@ from ._generated.api.authentication.auth_forgot_password import (
 from ._generated.api.authentication.auth_get_my_sessions import (
     _get_kwargs as get_my_sessions_kwargs,
 )
+from ._generated.api.authentication.auth_get_user import (
+    _build_response as build_auth_get_user_response,
+)
+from ._generated.api.authentication.auth_get_user import (
+    _get_kwargs as auth_get_user_kwargs,
+)
 from ._generated.api.authentication.auth_request_email_change import (
     _get_kwargs as request_email_change_kwargs,
 )
@@ -52,6 +66,12 @@ from ._generated.api.authentication.auth_reset_password import (
 from ._generated.api.authentication.auth_signup_anonymous import (
     _get_kwargs as signup_anonymous_kwargs,
 )
+from ._generated.api.authentication.auth_update_user import (
+    _build_response as build_auth_update_user_response,
+)
+from ._generated.api.authentication.auth_update_user import (
+    _get_kwargs as auth_update_user_kwargs,
+)
 from ._generated.api.database_queries import (
     query_database_select,
 )
@@ -829,9 +849,13 @@ class GeneratedTransport:
         )
         try:
             with self._client(authorization) as client:
-                response = auth_convert_anonymous.sync_detailed(
-                    client=client,
-                    body=body,
+                raw_response = client.get_httpx_client().request(
+                    **auth_convert_anonymous_kwargs(body=body)
+                )
+                if raw_response.status_code == HTTP_UNAUTHORIZED:
+                    return self._raw_response(raw_response)
+                response = build_auth_convert_anonymous_response(
+                    client=client, response=raw_response
                 )
         except (
             AttributeError,
@@ -928,9 +952,13 @@ class GeneratedTransport:
         body = AuthConfirmEmailChangeBody(email_change_token=token)
         try:
             with self._client(authorization) as client:
-                response = auth_confirm_email_change.sync_detailed(
-                    client=client,
-                    body=body,
+                raw_response = client.get_httpx_client().request(
+                    **auth_confirm_email_change_kwargs(body=body)
+                )
+                if raw_response.status_code == HTTP_UNAUTHORIZED:
+                    return self._raw_response(raw_response)
+                response = build_auth_confirm_email_change_response(
+                    client=client, response=raw_response
                 )
         except (
             AttributeError,
@@ -1204,7 +1232,14 @@ class GeneratedTransport:
     def auth_get_user(self, *, authorization: str) -> TransportResponse:
         try:
             with self._client(authorization) as client:
-                response = auth_get_user.sync_detailed(client=client)
+                raw_response = client.get_httpx_client().request(
+                    **auth_get_user_kwargs()
+                )
+                if raw_response.status_code == HTTP_UNAUTHORIZED:
+                    return self._raw_response(raw_response)
+                response = build_auth_get_user_response(
+                    client=client, response=raw_response
+                )
         except (
             AttributeError,
             KeyError,
@@ -1239,7 +1274,14 @@ class GeneratedTransport:
         )
         try:
             with self._client(authorization) as client:
-                response = auth_update_user.sync_detailed(client=client, body=body)
+                raw_response = client.get_httpx_client().request(
+                    **auth_update_user_kwargs(body=body)
+                )
+                if raw_response.status_code == HTTP_UNAUTHORIZED:
+                    return self._raw_response(raw_response)
+                response = build_auth_update_user_response(
+                    client=client, response=raw_response
+                )
         except (
             AttributeError,
             KeyError,

{volcano_sdk_python-0.7.1 → volcano_sdk_python-0.7.3}/src/volcano_sdk/auth.py

@@ -9,6 +9,7 @@ import secrets
 import threading
 from collections.abc import Mapping
 from contextlib import suppress
+from copy import deepcopy
 from dataclasses import replace
 from datetime import datetime
 from http import HTTPStatus
@@ -574,18 +575,22 @@ class Auth:
         metadata: Mapping[str, object] | None = None,
     ) -> User:
         """Attach email credentials to the current anonymous account."""
-        generation, current = self._client._capture_session()
-        if current is None:
+        binding = self._client._capture_session_binding()
+        if binding[2] is None:
             raise AuthenticationError(_NO_ACTIVE_SESSION)
         transport = cast("AuthConvertAnonymousTransport", self._client._transport)
-        response = invoke(
-            transport.auth_convert_anonymous,
-            authorization=current.access_token,
-            email=email,
-            password=password,
-            metadata=dict(metadata or {}),
+        request_metadata = deepcopy(dict(metadata or {}))
+        response = self._session_request(
+            lambda access_token: invoke(
+                transport.auth_convert_anonymous,
+                authorization=access_token,
+                email=email,
+                password=password,
+                metadata=request_metadata,
+            ),
+            binding=binding,
         )
-        return self._update_current_user(response_payload(response, 200), generation)
+        return self._update_current_user(response_payload(response, 200), binding)
 
     def reset_password_for_email(self, *, email: str) -> None:
         """Request a reset email without revealing whether the account exists."""
@@ -629,16 +634,19 @@ class Auth:
 
     def confirm_email_change(self, *, token: str) -> User:
         """Confirm a pending email change and return the updated user."""
-        generation, current = self._client._capture_session()
-        if current is None:
+        binding = self._client._capture_session_binding()
+        if binding[2] is None:
             raise AuthenticationError(_NO_ACTIVE_SESSION)
         transport = cast("AuthConfirmEmailChangeTransport", self._client._transport)
-        response = invoke(
-            transport.auth_confirm_email_change,
-            authorization=current.access_token,
-            token=token,
+        response = self._session_request(
+            lambda access_token: invoke(
+                transport.auth_confirm_email_change,
+                authorization=access_token,
+                token=token,
+            ),
+            binding=binding,
         )
-        return self._update_current_user(response_payload(response, 200), generation)
+        return self._update_current_user(response_payload(response, 200), binding)
 
     def delete_all_other_sessions(self) -> None:
         """Delete every other session while preserving the current session."""
@@ -944,7 +952,10 @@ class Auth:
         )
         response_payload(response, 200)
 
-    def _update_current_user(self, payload: object, generation: int) -> User:
+    def _update_current_user(
+        self, payload: object, binding: tuple[int, int, Session | None]
+    ) -> User:
+        generation = self._owned_refresh_session(binding)[0]
         user, snapshot = _user_from_payload(payload)
         if not self._client._update_session_user_if_current(snapshot, generation):
             raise SessionChangedError
@@ -952,12 +963,17 @@ class Auth:
 
     def get_user(self) -> User:
         """Load a server-validated profile for the current session."""
-        generation, current = self._client._capture_session()
-        if current is None:
+        binding = self._client._capture_session_binding()
+        if binding[2] is None:
             raise AuthenticationError(_NO_ACTIVE_SESSION)
         transport = cast("AuthGetUserTransport", self._client._transport)
-        response = invoke(transport.auth_get_user, authorization=current.access_token)
-        return self._update_current_user(response_payload(response, 200), generation)
+        response = self._session_request(
+            lambda access_token: invoke(
+                transport.auth_get_user, authorization=access_token
+            ),
+            binding=binding,
+        )
+        return self._update_current_user(response_payload(response, 200), binding)
 
     def update_user(
         self,
@@ -966,17 +982,21 @@ class Auth:
         metadata: Mapping[str, object] | None = None,
     ) -> User:
         """Update and return the current user's server-validated profile."""
-        generation, current = self._client._capture_session()
-        if current is None:
+        binding = self._client._capture_session_binding()
+        if binding[2] is None:
             raise AuthenticationError(_NO_ACTIVE_SESSION)
         transport = cast("AuthUpdateUserTransport", self._client._transport)
-        response = invoke(
-            transport.auth_update_user,
-            authorization=current.access_token,
-            password=password,
-            metadata=None if metadata is None else dict(metadata),
+        request_metadata = None if metadata is None else deepcopy(dict(metadata))
+        response = self._session_request(
+            lambda access_token: invoke(
+                transport.auth_update_user,
+                authorization=access_token,
+                password=password,
+                metadata=request_metadata,
+            ),
+            binding=binding,
         )
-        return self._update_current_user(response_payload(response, 200), generation)
+        return self._update_current_user(response_payload(response, 200), binding)
 
     def sign_in(self, *, email: str, password: str) -> Session:
         """Sign in a user and store the returned session."""
@@ -1007,12 +1027,20 @@ class Auth:
         )
 
     def _session_request(
-        self, operation: Callable[[str], TransportResponse]
+        self,
+        operation: Callable[[str], TransportResponse],
+        *,
+        binding: tuple[int, int, Session | None] | None = None,
     ) -> TransportResponse:
-        binding = self._client._capture_session_binding()
+        if binding is None:
+            binding = self._client._capture_session_binding()
         if binding[2] is None:
             raise RuntimeError(_NO_ACTIVE_SESSION)
-        response = operation(binding[2].access_token)
+        binding = self._owned_refresh_session(binding)
+        current = binding[2]
+        if current is None:
+            raise SessionChangedError
+        response = operation(current.access_token)
         if response.status_code != HTTPStatus.UNAUTHORIZED:
             return response
         try: