volcano-sdk-python 0.11.0__tar.gz → 0.11.1__tar.gz

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

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

{volcano_sdk_python-0.11.0 → volcano_sdk_python-0.11.1}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.11.1](https://github.com/Kong/volcano-sdk-python/compare/v0.11.0...v0.11.1) (2026-09-23)
+
+
+### Bug Fixes
+
+* **storage:** validate optional transport capabilities ([#303](https://github.com/Kong/volcano-sdk-python/issues/303)) ([e6b8e1a](https://github.com/Kong/volcano-sdk-python/commit/e6b8e1a9c677503c510ea58ec2a6956a21fb9652))
+
 ## [0.11.0](https://github.com/Kong/volcano-sdk-python/compare/v0.10.4...v0.11.0) (2026-09-23)
 
 

{volcano_sdk_python-0.11.0 → volcano_sdk_python-0.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: volcano-sdk-python
-Version: 0.11.0
+Version: 0.11.1
 Summary: Official Python SDK for Volcano
 Project-URL: Homepage, https://volcano.dev
 Project-URL: Repository, https://github.com/Kong/volcano-sdk-python

{volcano_sdk_python-0.11.0 → volcano_sdk_python-0.11.1}/pyproject.toml

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

{volcano_sdk_python-0.11.0 → volcano_sdk_python-0.11.1}/src/volcano_sdk/_function_resolution.py

@@ -196,7 +196,7 @@ def _store(
 def forget(api_url: str, authorization: str, name: str) -> None:
     """Drop one cached resolution that turned out to be stale."""
     with _lock:
-        _entries.pop((api_url, authorization, name), None)
+        _ = _entries.pop((api_url, authorization, name), None)
 
 
 def clear() -> None:

{volcano_sdk_python-0.11.0 → volcano_sdk_python-0.11.1}/src/volcano_sdk/_lock_guard.py

@@ -9,22 +9,31 @@ from typing import TYPE_CHECKING
 from ._lock_renewer import renewal_delay as _calculate_renewal_delay
 
 if TYPE_CHECKING:
+    from _thread import LockType
+
     from .models import LockLease
 
 MAX_LOCK_LIFETIME_SECONDS = 7_776_000
 LOSS_POLL_INTERVAL_SECONDS = 1.0
-SUSPEND_AWARE_CLOCK_ID = getattr(time, "CLOCK_BOOTTIME", None)
 _LEASE_EXPIRED = "lock lease expired before renewal completed"
 _NO_SAFE_RENEWAL_WINDOW = "lock renewal returned no safe lease window"
 
 
+def _suspend_aware_clock_id(value: object) -> int | None:
+    return value if isinstance(value, int) else None
+
+
+_clock_id_value: object = getattr(time, "CLOCK_BOOTTIME", None)
+SUSPEND_AWARE_CLOCK_ID = _suspend_aware_clock_id(_clock_id_value)
+
+
 class _FallbackClock:
     """Combine monotonic progress with suspend-aware wall time."""
 
     def __init__(self) -> None:
-        self._lock = threading.Lock()
-        self._monotonic = time.monotonic()
-        self._value = time.time()
+        self._lock: LockType = threading.Lock()
+        self._monotonic: float = time.monotonic()
+        self._value: float = time.time()
 
     def __call__(self) -> float:
         with self._lock:
@@ -38,11 +47,11 @@ class _FallbackClock:
 _FALLBACK_CLOCK = _FallbackClock()
 
 
-def _lease_now() -> float:
-    clock_gettime = getattr(time, "clock_gettime", None)
+def lease_now() -> float:
+    clock_gettime: object = getattr(time, "clock_gettime", None)
     if clock_gettime is None or SUSPEND_AWARE_CLOCK_ID is None:
         return _FALLBACK_CLOCK()
-    return float(clock_gettime(SUSPEND_AWARE_CLOCK_ID))
+    return float(time.clock_gettime(SUSPEND_AWARE_CLOCK_ID))
 
 
 class LockGuard:
@@ -57,15 +66,17 @@ class LockGuard:
         lease_started_at: float | None = None,
     ) -> None:
         """Track one acquired lease against its local monotonic deadline."""
-        self._state_lock = threading.Lock()
-        self._lease = lease
-        self._ttl = ttl
-        self._absolute_deadline = started_at + MAX_LOCK_LIFETIME_SECONDS
+        self._state_lock: LockType = threading.Lock()
+        self._lease: LockLease = lease
+        self._ttl: int = ttl
+        self._absolute_deadline: float = started_at + MAX_LOCK_LIFETIME_SECONDS
         # A successful retry renews the TTL, not the maximum ownership lifetime.
         lease_started_at = started_at if lease_started_at is None else lease_started_at
-        self._lease_deadline = min(lease_started_at + ttl, self._absolute_deadline)
+        self._lease_deadline: float = min(
+            lease_started_at + ttl, self._absolute_deadline
+        )
         self._failure: Exception | None = None
-        self._lost = threading.Event()
+        self._lost: threading.Event = threading.Event()
 
     @property
     def lease(self) -> LockLease:
@@ -77,7 +88,7 @@ class LockGuard:
     def lost(self) -> bool:
         """Whether renewal failed, the lease expired, or the guard closed."""
         with self._state_lock:
-            self._expire_if_needed_locked(_lease_now())
+            self._expire_if_needed_locked(lease_now())
             return self._lost.is_set()
 
     def wait_lost(self, timeout: float | None = None) -> bool:
@@ -89,10 +100,10 @@ class LockGuard:
             True when the guard reports lost ownership, False on timeout.
 
         """
-        timeout_deadline = None if timeout is None else _lease_now() + timeout
+        timeout_deadline = None if timeout is None else lease_now() + timeout
         while True:
             with self._state_lock:
-                now = _lease_now()
+                now = lease_now()
                 self._expire_if_needed_locked(now)
                 if self._lost.is_set():
                     return True
@@ -101,15 +112,15 @@ class LockGuard:
                     self._remaining_seconds_locked(now),
                 )
             if timeout_deadline is not None:
-                timeout_remaining = timeout_deadline - _lease_now()
+                timeout_remaining = timeout_deadline - lease_now()
                 if timeout_remaining <= 0:
                     return False
                 wait = min(wait, timeout_remaining)
-            self._lost.wait(wait)
+            _ = self._lost.wait(wait)
 
     def replace_lease(self, lease: LockLease, *, started_at: float) -> bool:
         with self._state_lock:
-            now = _lease_now()
+            now = lease_now()
             self._expire_if_needed_locked(now)
             if self._lost.is_set():
                 return False
@@ -126,18 +137,18 @@ class LockGuard:
 
     def mark_lost(self, failure: Exception) -> None:
         with self._state_lock:
-            self._expire_if_needed_locked(_lease_now())
+            self._expire_if_needed_locked(lease_now())
             self._mark_lost_locked(failure)
 
     def _remaining_seconds(self) -> float:
         with self._state_lock:
-            now = _lease_now()
+            now = lease_now()
             self._expire_if_needed_locked(now)
             return self._remaining_seconds_locked(now)
 
     def renewal_delay(self) -> float:
         with self._state_lock:
-            now = _lease_now()
+            now = lease_now()
             self._expire_if_needed_locked(now)
             if self._lost.is_set():
                 return 0.0
@@ -148,12 +159,12 @@ class LockGuard:
 
     def _renewal_failure(self) -> Exception | None:
         with self._state_lock:
-            self._expire_if_needed_locked(_lease_now())
+            self._expire_if_needed_locked(lease_now())
             return self._failure
 
     def _close(self) -> None:
         with self._state_lock:
-            self._expire_if_needed_locked(_lease_now())
+            self._expire_if_needed_locked(lease_now())
             self._lost.set()
 
     def _mark_lost_locked(self, failure: Exception) -> None:

{volcano_sdk_python-0.11.0 → volcano_sdk_python-0.11.1}/src/volcano_sdk/_lock_worker.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import threading
 from typing import TYPE_CHECKING, Protocol
 
-from ._lock_guard import LockGuard, _lease_now
+from ._lock_guard import LockGuard, lease_now
 
 if TYPE_CHECKING:
     from types import TracebackType
@@ -27,7 +27,7 @@ class LockRenewalClient(Protocol):
 
 class _RenewalFailureRecorder:
     def __init__(self, guard: LockGuard) -> None:
-        self._guard = guard
+        self._guard: LockGuard = guard
 
     def __enter__(self) -> None:
         return None
@@ -56,12 +56,12 @@ class LockRenewer:
         *,
         ttl: int,
     ) -> None:
-        self._locks = locks
-        self._key = key
-        self._guard = guard
-        self._ttl = ttl
-        self._stop = threading.Event()
-        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._locks: LockRenewalClient = locks
+        self._key: str = key
+        self._guard: LockGuard = guard
+        self._ttl: int = ttl
+        self._stop: threading.Event = threading.Event()
+        self._thread: threading.Thread = threading.Thread(target=self._run, daemon=True)
 
     def start(self) -> None:
         """Start renewing the guarded lease."""
@@ -81,11 +81,11 @@ class LockRenewer:
                     return
 
     def _wait_until_renewal(self) -> bool:
-        renew_at = _lease_now() + self._guard.renewal_delay()
+        renew_at = lease_now() + self._guard.renewal_delay()
         while not self._stop.is_set():
             if self._guard.lost:
                 return False
-            remaining = renew_at - _lease_now()
+            remaining = renew_at - lease_now()
             if remaining <= 0:
                 return True
             if self._stop.wait(min(remaining, MAX_RENEWAL_WAIT_SLICE_SECONDS)):
@@ -93,7 +93,7 @@ class LockRenewer:
         return False
 
     def _renew_once(self) -> bool:
-        started_at = _lease_now()
+        started_at = lease_now()
         with _RenewalFailureRecorder(self._guard):
             lease = self._locks.renew(
                 self._key,

{volcano_sdk_python-0.11.0 → volcano_sdk_python-0.11.1}/src/volcano_sdk/_session.py

@@ -33,8 +33,8 @@ def session_id_from_access_token(access_token: str) -> str | None:
         return None
     padding = "=" * (-len(parts[1]) % 4)
     try:
-        payload: object = json.loads(
-            base64.urlsafe_b64decode(parts[1] + padding).decode()
+        payload = cast(
+            "object", json.loads(base64.urlsafe_b64decode(parts[1] + padding).decode())
         )
     except (ValueError, UnicodeDecodeError, RecursionError):
         return None

{volcano_sdk_python-0.11.0 → volcano_sdk_python-0.11.1}/src/volcano_sdk/_session_operations.py

@@ -9,6 +9,7 @@ from typing import TYPE_CHECKING, TypeVar
 from .errors import SessionChangedError, VolcanoError
 
 if TYPE_CHECKING:
+    from _thread import LockType
     from collections.abc import Callable
 
     from .models import Session
@@ -40,11 +41,11 @@ class SessionOperations:
     """Retain only this session's latest refresh and shared sign-out outcome."""
 
     def __init__(self, verified: Session | None = None) -> None:
-        self._lock = Lock()
+        self._lock: LockType = Lock()
         self.refreshing: Future[Session] | None = None
         self.signing_out: Future[BaseException | None] | None = None
-        self._locally_cleared = False
-        self._verified_pair = (
+        self._locally_cleared: bool = False
+        self._verified_pair: tuple[str, str | None] | None = (
             (verified.access_token, verified.refresh_token)
             if verified is not None
             else None

{volcano_sdk_python-0.11.0 → volcano_sdk_python-0.11.1}/src/volcano_sdk/client.py

@@ -29,6 +29,7 @@ from .realtime import CentrifugeFactory, Realtime
 from .storage import Storage
 
 if TYPE_CHECKING:
+    from _thread import LockType
     from collections.abc import Callable, Mapping
     from types import TracebackType
 
@@ -104,15 +105,15 @@ class VolcanoClient:
         **credentials: Unpack[_BootstrapCredentials],
     ) -> None:
         """Create a client for a Volcano project."""
-        self._api_url = api_url.rstrip("/")
-        self._anon_key = anon_key
-        self._service_key = service_key
-        self._session_lock = threading.Lock()
-        self._session_generation = 0
-        self._session_lineage = SessionOperations()
-        self._current_session = _bootstrap_session(credentials)
+        self._api_url: str = api_url.rstrip("/")
+        self._anon_key: str = anon_key
+        self._service_key: str | None = service_key
+        self._session_lock: LockType = threading.Lock()
+        self._session_generation: int = 0
+        self._session_lineage: SessionOperations = SessionOperations()
+        self._current_session: Session | None = _bootstrap_session(credentials)
         self._auth_callbacks: dict[int, AuthStateCallback] = {}
-        self._next_auth_callback_id = 0
+        self._next_auth_callback_id: int = 0
         self._auth_notifications: deque[
             tuple[
                 tuple[int, ...],
@@ -120,7 +121,7 @@ class VolcanoClient:
                 Session | None,
             ]
         ] = deque()
-        self._dispatching_auth_notifications = False
+        self._dispatching_auth_notifications: bool = False
         self._transport: Transport = (
             _transport
             if _transport is not None
@@ -312,7 +313,7 @@ class VolcanoClient:
 
     def _unsubscribe_auth_state_change(self, callback_id: int) -> None:
         with self._session_lock:
-            self._auth_callbacks.pop(callback_id, None)
+            _ = self._auth_callbacks.pop(callback_id, None)
 
     def _enqueue_auth_state_change(
         self,

{volcano_sdk_python-0.11.0 → volcano_sdk_python-0.11.1}/src/volcano_sdk/connection_string.py

@@ -73,7 +73,7 @@ def _query_parameters(query: str) -> list[str]:
         if unquote(parameter.partition("=")[0]) != "application_name"
     ]
     while parameters and not parameters[-1]:
-        parameters.pop()
+        _ = parameters.pop()
     return parameters
 
 

{volcano_sdk_python-0.11.0 → volcano_sdk_python-0.11.1}/src/volcano_sdk/durable.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from collections.abc import Mapping, Sequence
 from datetime import datetime
-from typing import Protocol, cast
+from typing import Protocol, cast, runtime_checkable
 from uuid import UUID
 
 from ._transport import (
@@ -24,6 +24,7 @@ from .models import (
 
 _INVALID_EXECUTION_PAYLOAD = "Expected a complete durable execution"
 _INVALID_EXECUTION_PAGE = "Expected a complete durable execution page"
+_INVALID_DURABLE_TRANSPORT = "Transport does not support durable executions"
 # The spec's maxLength on X-Volcano-Execution-Name. Checked here so an
 # over-long name is refused before a request is spent on it, the way the
 # JavaScript SDK refuses it.
@@ -57,6 +58,7 @@ class DurableClientContext(Protocol):
     def _session_token(self) -> str: ...
 
 
+@runtime_checkable
 class DurableTransport(Protocol):
     """Transport operations required by the durable facade."""
 
@@ -110,7 +112,13 @@ class Durable:
 
     def __init__(self, client: DurableClientContext) -> None:
         """Bind durable operations to a Volcano client."""
-        self._client = client
+        self._client: DurableClientContext = client
+
+    def _durable_transport(self) -> DurableTransport:
+        transport = self._client._transport
+        if not isinstance(transport, DurableTransport):
+            raise TypeError(_INVALID_DURABLE_TRANSPORT)
+        return transport
 
     def start(
         self,
@@ -139,7 +147,7 @@ class Durable:
         """
         identifier = _identifier(function_name, "function_name")
         name = None if execution_name is None else _execution_name(execution_name)
-        transport = cast("DurableTransport", self._client._transport)
+        transport = self._durable_transport()
         response = invoke(
             transport.start_durable_execution_from_application,
             authorization=self._client._function_token(),
@@ -147,7 +155,8 @@ class Durable:
             payload={} if payload is None else payload,
             execution_name=name,
         )
-        return _durable_execution(response_payload(response, _HTTP_ACCEPTED))
+        response_body: object = response_payload(response, _HTTP_ACCEPTED)
+        return _durable_execution(response_body)
 
     def get(
         self,
@@ -173,7 +182,7 @@ class Durable:
         project = _identifier(project_id, "project_id")
         identifier = _identifier(function_name, "function_name")
         execution = _identifier(execution_id, "execution_id")
-        transport = cast("DurableTransport", self._client._transport)
+        transport = self._durable_transport()
         response = invoke(
             transport.get_durable_execution,
             authorization=self._client._session_token(),
@@ -181,7 +190,8 @@ class Durable:
             function_id=identifier,
             execution_id=execution,
         )
-        return _durable_execution(response_payload(response, _HTTP_OK))
+        response_body: object = response_payload(response, _HTTP_OK)
+        return _durable_execution(response_body)
 
     def list(
         self,
@@ -205,7 +215,7 @@ class Durable:
         """
         project = _identifier(project_id, "project_id")
         identifier = _identifier(function_name, "function_name")
-        transport = cast("DurableTransport", self._client._transport)
+        transport = self._durable_transport()
         request = DurableExecutionListRequest(status=status, page=page, limit=limit)
         response = invoke(
             transport.list_durable_executions,
@@ -214,7 +224,8 @@ class Durable:
             function_id=identifier,
             request=request,
         )
-        return _durable_execution_page(response_payload(response, _HTTP_OK))
+        response_body: object = response_payload(response, _HTTP_OK)
+        return _durable_execution_page(response_body)
 
     def stop(
         self,
@@ -239,7 +250,7 @@ class Durable:
         project = _identifier(project_id, "project_id")
         identifier = _identifier(function_name, "function_name")
         execution = _identifier(execution_id, "execution_id")
-        transport = cast("DurableTransport", self._client._transport)
+        transport = self._durable_transport()
         response = invoke(
             transport.stop_durable_execution,
             authorization=self._client._session_token(),
@@ -247,7 +258,8 @@ class Durable:
             function_id=identifier,
             execution_id=execution,
         )
-        return _durable_execution(response_payload(response, _HTTP_OK))
+        response_body: object = response_payload(response, _HTTP_OK)
+        return _durable_execution(response_body)
 
 
 def _execution_name(value: object) -> str:
@@ -299,7 +311,7 @@ def _identifier(value: object, field: str) -> str:
     trimmed = value.strip()
     if field in _UUID_IDENTIFIERS:
         try:
-            UUID(trimmed)
+            _ = UUID(trimmed)
         except ValueError as exc:
             raise ValueError(_UUID_IDENTIFIERS[field]) from exc
     return trimmed

{volcano_sdk_python-0.11.0 → volcano_sdk_python-0.11.1}/src/volcano_sdk/errors.py

@@ -16,9 +16,9 @@ class VolcanoError(Exception):
     ) -> None:
         """Create an error from an API or transport failure."""
         super().__init__(message)
-        self.status = status
-        self.code = code
-        self.retry_after = retry_after
+        self.status: int | None = status
+        self.code: str | None = code
+        self.retry_after: int | None = retry_after
 
 
 class AuthenticationError(VolcanoError):

{volcano_sdk_python-0.11.0 → volcano_sdk_python-0.11.1}/src/volcano_sdk/functions.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import json
 import re
 from collections.abc import Callable, Mapping
-from typing import TYPE_CHECKING, Protocol, TypeVar, cast
+from typing import TYPE_CHECKING, Protocol, TypeVar, cast, runtime_checkable
 
 from ._function_resolution import (
     FunctionResolution,
@@ -37,6 +37,7 @@ _INVALID_FUNCTION_NAME = (
 )
 _INVALID_FUNCTION_RESPONSE = "Expected a complete function response"
 _INVALID_FUNCTION_PAYLOAD = "Function payload must be a mapping"
+_INVALID_FUNCTION_TRANSPORT = "Transport does not support function invocation"
 _HTTP_SUCCESS_MIN = 200
 _HTTP_SUCCESS_MAX = 300
 _HTTP_NOT_FOUND = 404
@@ -65,9 +66,11 @@ class FunctionsContext(Protocol):
 
 class _FunctionAuth:
     def __init__(self, client: FunctionsContext) -> None:
-        self._client = client
-        self._binding = client._capture_session_binding()
-        self._fallback_token = client._function_token()
+        self._client: FunctionsContext = client
+        self._binding: tuple[int, SessionOperations, Session | None] = (
+            client._capture_session_binding()
+        )
+        self._fallback_token: str = client._function_token()
 
     def run(self, operation: Callable[[str], _Result]) -> _Result:
         if self._binding[2] is not None:
@@ -88,7 +91,7 @@ class _FunctionAuth:
                 raise
             try:
                 # Resolve has released its cache lock before refresh callbacks run.
-                self._client.auth._refresh_session_for_binding(self._binding)
+                _ = self._client.auth._refresh_session_for_binding(self._binding)
             except SessionChangedError:
                 raise
             except VolcanoError:
@@ -104,6 +107,7 @@ class _FunctionAuth:
         return session.access_token
 
 
+@runtime_checkable
 class FunctionsTransport(Protocol):
     """Transport operations required by the functions facade."""
 
@@ -142,7 +146,13 @@ class Functions:
 
     def __init__(self, client: FunctionsContext) -> None:
         """Bind function calls to a Volcano client."""
-        self._client = client
+        self._client: FunctionsContext = client
+
+    def _function_transport(self) -> FunctionsTransport:
+        transport = self._client._transport
+        if not isinstance(transport, FunctionsTransport):
+            raise TypeError(_INVALID_FUNCTION_TRANSPORT)
+        return transport
 
     def invoke(
         self,
@@ -161,7 +171,7 @@ class Functions:
         auth = _FunctionAuth(self._client)
         name = _function_name(name)
         request_payload = _function_payload(payload)
-        transport = cast("FunctionsTransport", self._client._transport)
+        transport = self._function_transport()
         authorization, resolution = auth.run(
             lambda token: (token, self._resolve(transport, token, name))
         )
@@ -209,7 +219,7 @@ class Functions:
             response.status_code == _HTTP_UNAUTHORIZED
             and _header(response.headers, _FUNCTION_INVOKED_HEADER) is None
         ):
-            response_payload(response, _HTTP_SUCCESS_MIN)
+            _ = response_payload(response, _HTTP_SUCCESS_MIN)
         return response
 
     def _resolve(
@@ -268,7 +278,7 @@ class Functions:
             name=name,
         )
         try:
-            payload = response_payload(resolved, _HTTP_SUCCESS_MIN)
+            payload: object = response_payload(resolved, _HTTP_SUCCESS_MIN)
         except NotFoundError as error:
             store_missing(api_url, authorization, name, error)
             raise
@@ -310,7 +320,7 @@ class Functions:
         # as though the function had returned it.
         dispatched = _header(response.headers, _FUNCTION_INVOKED_HEADER) is not None
         if not _HTTP_SUCCESS_MIN <= status < _HTTP_SUCCESS_MAX and not dispatched:
-            response_payload(response, _HTTP_SUCCESS_MIN)
+            _ = response_payload(response, _HTTP_SUCCESS_MIN)
         headers = {} if response.headers is None else dict(response.headers)
         return FunctionResponse(
             data=_function_data(response),