volcano-sdk-python 0.10.2__py3-none-any.whl → 0.10.4__py3-none-any.whl

volcano_sdk/_callbacks.py

@@ -0,0 +1,12 @@
+"""Validate runtime callbacks without erasing their static signatures."""
+
+
+def require_callable(value: object, message: str) -> None:
+    """Reject non-callable values supplied by unchecked callers.
+
+    Raises:
+        TypeError: The value is not callable.
+
+    """
+    if not callable(value):
+        raise TypeError(message)

volcano_sdk/_transport.py

@@ -738,7 +738,7 @@ def _error_type(status: int) -> type[VolcanoError]:
     return VolcanoError
 
 
-def response_payload(response: TransportResponse, expected_status: int) -> Any:
+def response_payload(response: TransportResponse, expected_status: int) -> object:
     status = int(response.status_code)
     if status != expected_status:
         payload: Mapping[str, object]

volcano_sdk/auth.py

@@ -12,6 +12,7 @@ from http import HTTPStatus
 from typing import TYPE_CHECKING, Literal, Protocol, TypeVar, cast
 from urllib.parse import quote, urlencode
 
+from ._callbacks import require_callable
 from ._generated.models.auth_confirm_email_change_response_200 import (
     AuthConfirmEmailChangeResponse200,
 )
@@ -514,8 +515,7 @@ class Auth:
             TypeError: The callback is not callable.
 
         """
-        if not callable(callback):
-            raise TypeError(_INVALID_AUTH_CALLBACK)
+        require_callable(callback, _INVALID_AUTH_CALLBACK)
         return self._client._subscribe_auth_state_change(callback)
 
     def set_session(self, session: Session) -> Session:

volcano_sdk/client.py

@@ -126,14 +126,14 @@ class VolcanoClient:
             if _transport is not None
             else GeneratedTransport(api_url=self._api_url, timeout=timeout)
         )
-        self.auth = Auth(self)
-        self.functions = Functions(self)
-        self.durable = Durable(self)
-        self.logs = Logs(self)
-        self.storage = Storage(self)
-        self.locks = Locks(self)
+        self.auth: Auth = Auth(self)
+        self.functions: Functions = Functions(self)
+        self.durable: Durable = Durable(self)
+        self.logs: Logs = Logs(self)
+        self.storage: Storage = Storage(self)
+        self.locks: Locks = Locks(self)
         if _realtime_client_factory is None:
-            self.realtime = Realtime(self, api_url=self._api_url)
+            self.realtime: Realtime = Realtime(self, api_url=self._api_url)
         else:
             self.realtime = Realtime(
                 self,

volcano_sdk/database.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from collections.abc import Mapping
 from dataclasses import dataclass, replace
-from typing import TYPE_CHECKING, Any, Protocol, Self, TypedDict, cast
+from typing import TYPE_CHECKING, Protocol, Self, TypedDict, TypeGuard, cast
 
 from typing_extensions import override
 
@@ -16,6 +16,30 @@ if TYPE_CHECKING:
 
 from ._transport import Transport, invoke, response_payload
 
+_INVALID_DATABASE_ROWS = "Expected a list of database rows with string keys"
+
+
+def _is_database_row(value: object) -> TypeGuard[dict[str, object]]:
+    if not isinstance(value, dict):
+        return False
+    row = cast("dict[object, object]", value)
+    return all(isinstance(key, str) for key in row)
+
+
+def _database_rows(payload: object) -> list[dict[str, object]]:
+    if not isinstance(payload, Mapping):
+        raise TypeError(_INVALID_DATABASE_ROWS)
+    values = cast("Mapping[object, object]", payload)
+    raw_rows = values.get("data")
+    if not isinstance(raw_rows, list):
+        raise TypeError(_INVALID_DATABASE_ROWS)
+    rows: list[dict[str, object]] = []
+    for row in cast("list[object]", raw_rows):
+        if not _is_database_row(row):
+            raise TypeError(_INVALID_DATABASE_ROWS)
+        rows.append(row)
+    return rows
+
 
 def _snapshot_json(value: JSONValue) -> JSONValue:
     if isinstance(value, Mapping):
@@ -62,9 +86,10 @@ class _OrderClause(TypedDict):
 class FilterBuilder:
     """Shared immutable filters for database operations."""
 
-    _filters: tuple[_FilterCondition, ...]
+    _filters: tuple[_FilterCondition, ...] = ()
 
     def _with_filters(self, filters: tuple[_FilterCondition, ...]) -> Self:
+        del filters
         raise NotImplementedError
 
     def eq(self, column: str, value: object) -> Self:
@@ -314,12 +339,12 @@ class QueryBuilder(FilterBuilder):
             if value is not None
         }
 
-    def execute(self) -> list[dict[str, Any]]:
+    def execute(self) -> list[dict[str, object]]:
         """Execute the query and return its rows.
 
         Returns
         -------
-        list[dict[str, Any]]
+        list[dict[str, object]]
             Rows returned by the select request.
 
         """
@@ -332,8 +357,8 @@ class QueryBuilder(FilterBuilder):
                 body=body,
             )
         )
-        payload = response_payload(response, 200)
-        return list(payload["data"])
+        payload: object = response_payload(response, 200)
+        return _database_rows(payload)
 
 
 @dataclass(frozen=True, slots=True)
@@ -345,12 +370,12 @@ class InsertBuilder:
     _table: str
     _values: dict[str, JSONValue]
 
-    def execute(self) -> list[dict[str, Any]]:
+    def execute(self) -> list[dict[str, object]]:
         """Insert one row and return the inserted rows.
 
         Returns
         -------
-        list[dict[str, Any]]
+        list[dict[str, object]]
             Inserted rows returned by the server.
 
         """
@@ -362,8 +387,8 @@ class InsertBuilder:
                 body={"table": self._table, "values": _snapshot_row(self._values)},
             )
         )
-        payload = response_payload(response, 200)
-        return list(payload["data"])
+        payload: object = response_payload(response, 200)
+        return _database_rows(payload)
 
 
 @dataclass(frozen=True, slots=True)
@@ -380,12 +405,12 @@ class UpdateBuilder(FilterBuilder):
     def _with_filters(self, filters: tuple[_FilterCondition, ...]) -> UpdateBuilder:
         return replace(self, _filters=filters)
 
-    def execute(self) -> list[dict[str, Any]]:
+    def execute(self) -> list[dict[str, object]]:
         """Update matching rows and return them.
 
         Returns
         -------
-        list[dict[str, Any]]
+        list[dict[str, object]]
             Updated rows returned by the server.
 
         """
@@ -401,8 +426,8 @@ class UpdateBuilder(FilterBuilder):
                 },
             )
         )
-        payload = response_payload(response, 200)
-        return list(payload["data"])
+        payload: object = response_payload(response, 200)
+        return _database_rows(payload)
 
 
 @dataclass(frozen=True, slots=True)
@@ -418,12 +443,12 @@ class DeleteBuilder(FilterBuilder):
     def _with_filters(self, filters: tuple[_FilterCondition, ...]) -> DeleteBuilder:
         return replace(self, _filters=filters)
 
-    def execute(self) -> list[dict[str, Any]]:
+    def execute(self) -> list[dict[str, object]]:
         """Delete matching rows and return them.
 
         Returns
         -------
-        list[dict[str, Any]]
+        list[dict[str, object]]
             Deleted rows returned by the server.
 
         """
@@ -435,8 +460,8 @@ class DeleteBuilder(FilterBuilder):
                 body={"table": self._table, "filters": list(self._filters)},
             )
         )
-        payload = response_payload(response, 200)
-        return list(payload["data"])
+        payload: object = response_payload(response, 200)
+        return _database_rows(payload)
 
 
 @dataclass(frozen=True, slots=True)

volcano_sdk/durable.py

@@ -4,11 +4,12 @@ from __future__ import annotations
 
 from collections.abc import Mapping, Sequence
 from datetime import datetime
-from typing import TYPE_CHECKING, Protocol, cast
+from typing import Protocol, cast
 from uuid import UUID
 
 from ._transport import (
     DurableExecutionListRequest,
+    Transport,
     TransportResponse,
     invoke,
     response_payload,
@@ -21,9 +22,6 @@ from .models import (
     JSONValue,
 )
 
-if TYPE_CHECKING:
-    from .client import VolcanoClient
-
 _INVALID_EXECUTION_PAYLOAD = "Expected a complete durable execution"
 _INVALID_EXECUTION_PAGE = "Expected a complete durable execution page"
 # The spec's maxLength on X-Volcano-Execution-Name. Checked here so an
@@ -49,6 +47,16 @@ _HTTP_ACCEPTED = 202
 _HTTP_OK = 200
 
 
+class DurableClientContext(Protocol):
+    """Client capabilities required by durable execution requests."""
+
+    _transport: Transport
+
+    def _function_token(self) -> str: ...
+
+    def _session_token(self) -> str: ...
+
+
 class DurableTransport(Protocol):
     """Transport operations required by the durable facade."""
 
@@ -100,7 +108,7 @@ class DurableTransport(Protocol):
 class Durable:
     """Start and follow executions of deployed durable functions."""
 
-    def __init__(self, client: VolcanoClient) -> None:
+    def __init__(self, client: DurableClientContext) -> None:
         """Bind durable operations to a Volcano client."""
         self._client = client
 

volcano_sdk/durable_authoring.py

@@ -28,12 +28,37 @@ from __future__ import annotations
 import functools
 import importlib
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Generic, TypeAlias, TypeVar, cast, overload
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Generic,
+    ParamSpec,
+    Protocol,
+    TypeAlias,
+    TypeVar,
+    cast,
+    overload,
+)
+
+from ._callbacks import require_callable
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Sequence
+    from collections.abc import Callable, Mapping, Sequence
+
+    from aws_durable_execution_sdk_python.config import (
+        CompletionConfig,
+        ParallelConfig,
+        StepConfig,
+        StepSemantics,
+    )
+    from aws_durable_execution_sdk_python.config import Duration as EngineDuration
+    from aws_durable_execution_sdk_python.retries import (
+        RetryDecision,
+        RetryStrategyConfig,
+    )
 
 T = TypeVar("T")
+_P = ParamSpec("_P")
 # A duration: "30s", "5m", "2h", "1d", a compound string like "1m30s", a whole
 # number of seconds, or the mapping form.
 Duration: TypeAlias = "str | int | dict[str, int]"
@@ -133,16 +158,18 @@ class _Engine:
         except ImportError as error:
             raise DurableRuntimeMissingError(error) from error
         self.durable_execution = root.durable_execution
-        self.duration = config.Duration
-        self.step_config = config.StepConfig
-        self.step_semantics = config.StepSemantics
+        self.duration: type[EngineDuration] = config.Duration
+        self.step_config: type[StepConfig] = config.StepConfig
+        self.step_semantics: type[StepSemantics] = config.StepSemantics
         self.map_config = config.MapConfig
-        self.parallel_config = config.ParallelConfig
-        self.completion_config = config.CompletionConfig
+        self.parallel_config: type[ParallelConfig] = config.ParallelConfig
+        self.completion_config: type[CompletionConfig] = config.CompletionConfig
         self.parallel_branch = config.ParallelBranch
         self.create_retry_strategy = retries.create_retry_strategy
-        self.retry_strategy_config = retries.RetryStrategyConfig
-        self.retry_decision = retries.RetryDecision
+        self.retry_strategy_config: type[RetryStrategyConfig] = (
+            retries.RetryStrategyConfig
+        )
+        self.retry_decision: type[RetryDecision] = retries.RetryDecision
         self.create_wait_strategy = waits.create_wait_strategy
         self.wait_strategy_config = waits.WaitStrategyConfig
         self.wait_for_condition_config = waits.WaitForConditionConfig
@@ -225,6 +252,40 @@ class ParallelBranch(Generic[T]):
     name: str | None = None
 
 
+class DurableLogger(Protocol):
+    """Replay-aware logging methods exposed by durable contexts and steps."""
+
+    def debug(
+        self, msg: object, *args: object, extra: Mapping[str, object] | None = None
+    ) -> None:
+        """Log a debug message unless the operation is replaying."""
+        ...
+
+    def info(
+        self, msg: object, *args: object, extra: Mapping[str, object] | None = None
+    ) -> None:
+        """Log an informational message unless the operation is replaying."""
+        ...
+
+    def warning(
+        self, msg: object, *args: object, extra: Mapping[str, object] | None = None
+    ) -> None:
+        """Log a warning unless the operation is replaying."""
+        ...
+
+    def error(
+        self, msg: object, *args: object, extra: Mapping[str, object] | None = None
+    ) -> None:
+        """Log an error unless the operation is replaying."""
+        ...
+
+    def exception(
+        self, msg: object, *args: object, extra: Mapping[str, object] | None = None
+    ) -> None:
+        """Log an exception unless the operation is replaying."""
+        ...
+
+
 @dataclass(frozen=True, slots=True)
 class StepScope:
     """What a step's function is given: logging, and which attempt it is on.
@@ -235,7 +296,7 @@ class StepScope:
     would invite exactly the mistake the engine then rejects.
     """
 
-    log: Any
+    log: DurableLogger
     # 1 on the first attempt.
     attempt: int
 
@@ -380,7 +441,7 @@ class DurableContext:
         self._context = context
         self._engine = engine
         # Logs, suppressed while an operation is being replayed.
-        self.log = context.logger
+        self.log: DurableLogger = context.logger
 
     def step(
         self,
@@ -407,7 +468,7 @@ class DurableContext:
         """
         step_name, step_func = _named(name, func, "step")
 
-        def run(scope: Any) -> Any:
+        def run(scope: Any) -> T:
             return step_func(StepScope(scope.logger, scope.attempt))
 
         # The engine hands back whatever the step returned, untyped. T is the
@@ -454,7 +515,7 @@ class DurableContext:
         child_name, child_func = _named(name, func, "child")
         engine = self._engine
 
-        def run(context: Any) -> Any:
+        def run(context: Any) -> T:
             return child_func(DurableContext(context, engine))
 
         return cast("T", self._context.run_in_child_context(run, child_name))
@@ -532,7 +593,7 @@ class DurableContext:
             raise TypeError(_INVALID_ITEMS)
         engine = self._engine
 
-        def run(context: Any, item: Any, index: int, _all: Any) -> Any:
+        def run(context: Any, item: Any, index: int, _all: Any) -> T:
             return map_func(item, DurableContext(context, engine), index)
 
         return BatchResult(
@@ -590,8 +651,7 @@ class DurableContext:
                 return named(DurableContext(context, engine))
 
             return engine.parallel_branch(func=run_named, name=branch.name)
-        if not callable(branch):
-            raise TypeError(_INVALID_BRANCH)
+        require_callable(branch, _INVALID_BRANCH)
         bare = branch
 
         def run_bare(context: Any) -> Any:
@@ -608,7 +668,7 @@ class DurableContext:
             )
         return config
 
-    def _step_config(self, *, retry: Retry, at_most_once: bool) -> Any:
+    def _step_config(self, *, retry: Retry, at_most_once: bool) -> StepConfig:
         engine = self._engine
         config: dict[str, Any] = {}
         if at_most_once:
@@ -618,7 +678,7 @@ class DurableContext:
             config["retry_strategy"] = strategy
         return engine.step_config(**config)
 
-    def _retry_strategy(self, retry: Retry) -> Any:
+    def _retry_strategy(self, retry: object) -> Any:
         engine = self._engine
         if retry is None or retry is True:
             return None
@@ -635,11 +695,11 @@ class DurableContext:
             return retry
         raise TypeError(_INVALID_RETRY)
 
-    def _never_retry(self) -> Callable[[Exception, int], Any]:
+    def _never_retry(self) -> Callable[[Exception, int], RetryDecision]:
         engine = self._engine
         no_delay = engine.duration.from_seconds(0)
 
-        def never_retry(_error: Exception, _attempt: int) -> Any:
+        def never_retry(_error: Exception, _attempt: int) -> RetryDecision:
             return engine.retry_decision(should_retry=False, delay=no_delay)
 
         return never_retry
@@ -656,13 +716,15 @@ class DurableContext:
             ),
         )
 
-    def _optional_duration(self, value: Duration | None, field_name: str) -> Any:
+    def _optional_duration(
+        self, value: Duration | None, field_name: str
+    ) -> EngineDuration | None:
         return None if value is None else self._duration(value, field_name)
 
-    def _duration(self, value: object, field_name: str) -> Any:
+    def _duration(self, value: object, field_name: str) -> EngineDuration:
         return self._engine.duration.from_seconds(_to_seconds(value, field_name))
 
-    def _wait_duration(self, value: object) -> Any:
+    def _wait_duration(self, value: object) -> EngineDuration:
         seconds = _to_seconds(value, "wait")
         if seconds < _MIN_WAIT_SECONDS:
             message = f"wait must be at least {_MIN_WAIT_SECONDS} second"
@@ -714,8 +776,7 @@ def durable(
             return durable(func, logger=logger)
 
         return decorate
-    if not callable(handler):
-        raise TypeError(_REQUIRES_HANDLER)
+    require_callable(handler, _REQUIRES_HANDLER)
 
     return _wrap_durable(handler, logger)
 
@@ -758,10 +819,10 @@ def _validate_wait_options(options: WaitUntilOptions) -> None:
 
 
 def _named(
-    name: str | Callable[..., Any] | None,
-    func: Callable[..., Any] | None,
+    name: str | Callable[_P, T] | None,
+    func: Callable[_P, T] | None,
     operation: str,
-) -> tuple[str | None, Callable[..., Any]]:
+) -> tuple[str | None, Callable[_P, T]]:
     """Accept both the named and unnamed form of an operation.
 
     The name is what the operation is recorded under, so it is worth
@@ -776,7 +837,7 @@ def _named(
     return None, _callable(name, operation)
 
 
-def _callable(func: object, operation: str) -> Callable[..., Any]:
+def _callable(func: Callable[_P, T] | None, operation: str) -> Callable[_P, T]:
     if not callable(func):
         message = f"{operation}() requires a function to run"
         raise TypeError(message)

volcano_sdk/functions.py

@@ -7,9 +7,16 @@ import re
 from collections.abc import Callable, Mapping
 from typing import TYPE_CHECKING, Protocol, TypeVar, cast
 
-from . import _function_resolution
-from ._function_resolution import FunctionResolution
-from ._transport import TransportResponse, invoke, response_payload
+from ._function_resolution import (
+    FunctionResolution,
+    forget,
+    lookup,
+    resolve_lock,
+    store,
+    store_missing,
+    valid_invoke_url,
+)
+from ._transport import Transport, TransportResponse, invoke, response_payload
 from .errors import (
     AuthenticationError,
     NotFoundError,
@@ -19,7 +26,9 @@ from .errors import (
 from .models import FunctionResponse, JSONValue, _freeze_json
 
 if TYPE_CHECKING:
-    from .client import VolcanoClient
+    from ._session_operations import SessionOperations
+    from .auth import Auth
+    from .models import Session
 
 _FUNCTION_NAME = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$")
 _INVALID_FUNCTION_NAME = (
@@ -39,8 +48,23 @@ _FUNCTION_INVOKED_HEADER = "X-Volcano-Function-Invoked"
 _Result = TypeVar("_Result")
 
 
+class FunctionsContext(Protocol):
+    """Client capabilities required by function invocation."""
+
+    _transport: Transport
+    auth: Auth
+
+    def _capture_session_binding(
+        self,
+    ) -> tuple[int, SessionOperations, Session | None]: ...
+
+    def _function_token(self) -> str: ...
+
+    def _api_base_url(self) -> str: ...
+
+
 class _FunctionAuth:
-    def __init__(self, client: VolcanoClient) -> None:
+    def __init__(self, client: FunctionsContext) -> None:
         self._client = client
         self._binding = client._capture_session_binding()
         self._fallback_token = client._function_token()
@@ -116,7 +140,7 @@ class FunctionsTransport(Protocol):
 class Functions:
     """Invoke deployed Volcano functions by name."""
 
-    def __init__(self, client: VolcanoClient) -> None:
+    def __init__(self, client: FunctionsContext) -> None:
         """Bind function calls to a Volcano client."""
         self._client = client
 
@@ -149,9 +173,7 @@ class Functions:
         if _stale_mapping(response):
             # The function was deleted and recreated, so the cached identity no
             # longer exists. Resolve again before giving up.
-            _function_resolution.forget(
-                self._client._api_base_url(), authorization, name
-            )
+            forget(self._client._api_base_url(), authorization, name)
             _, resolution = auth.run(
                 lambda token: (token, self._resolve(transport, token, name))
             )
@@ -211,7 +233,7 @@ class Functions:
 
         # Hold the name's lock across the round trip so concurrent callers wait
         # for one resolve instead of each opening their own.
-        with _function_resolution.resolve_lock(api_url, authorization, name):
+        with resolve_lock(api_url, authorization, name):
             cached = self._cached(api_url, authorization, name)
             if cached is not None:
                 return cached
@@ -221,7 +243,7 @@ class Functions:
     def _cached(
         api_url: str, authorization: str, name: str
     ) -> FunctionResolution | None:
-        cached = _function_resolution.lookup(api_url, authorization, name)
+        cached = lookup(api_url, authorization, name)
         if cached is None:
             return None
         if cached.resolution is None:
@@ -248,12 +270,10 @@ class Functions:
         try:
             payload = response_payload(resolved, _HTTP_SUCCESS_MIN)
         except NotFoundError as error:
-            _function_resolution.store_missing(api_url, authorization, name, error)
+            store_missing(api_url, authorization, name, error)
             raise
         resolution = self._resolution(payload, api_url)
-        _function_resolution.store(
-            api_url, authorization, name, resolution, self._cache_ttl(payload)
-        )
+        store(api_url, authorization, name, resolution, self._cache_ttl(payload))
         return resolution
 
     @staticmethod
@@ -268,9 +288,7 @@ class Functions:
         # local development; the function is reached through the API instead.
         return FunctionResolution(
             function_id=function_id,
-            invoke_url=_function_resolution.valid_invoke_url(
-                values.get("invoke_url"), api_url
-            ),
+            invoke_url=valid_invoke_url(values.get("invoke_url"), api_url),
         )
 
     @staticmethod

volcano_sdk/locks.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from contextlib import contextmanager, suppress
 from datetime import datetime
 from typing import TYPE_CHECKING, Protocol, cast
@@ -22,6 +23,7 @@ _MIN_LOCK_TTL_SECONDS = 5
 _MAX_LOCK_TTL_SECONDS = 7_776_000
 _INVALID_LOCK_TTL = "ttl must be an integer between 5 seconds and 90 days"
 _MISSING_RENEWAL_FAILURE = "lock guard rejected renewal without a failure"
+_INVALID_LOCK_RESPONSE = "Expected a complete lock response"
 
 
 class LocksContext(Protocol):
@@ -82,6 +84,26 @@ def _parse_datetime(value: object) -> datetime | None:
     return datetime.fromisoformat(str(value))
 
 
+def _lock_values(payload: object) -> Mapping[object, object]:
+    if not isinstance(payload, Mapping):
+        raise TypeError(_INVALID_LOCK_RESPONSE)
+    return cast("Mapping[object, object]", payload)
+
+
+def _fencing_token(value: object) -> int | None:
+    if value is None or type(value) is int:
+        return value
+    raise TypeError(_INVALID_LOCK_RESPONSE)
+
+
+def _lease_fields(payload: Mapping[object, object]) -> tuple[datetime, int]:
+    expires_at = payload.get("expires_at")
+    fencing_token = payload.get("fencing_token")
+    if not isinstance(expires_at, str) or type(fencing_token) is not int:
+        raise TypeError(_INVALID_LOCK_RESPONSE)
+    return datetime.fromisoformat(expires_at), fencing_token
+
+
 def _validate_ttl(ttl: object) -> None:
     if (
         isinstance(ttl, bool)
@@ -125,11 +147,14 @@ class Locks:
             key=key,
             request_id=_request_uuid(request_id, "request_id"),
         )
-        payload = response_payload(response, 200)
+        payload = _lock_values(response_payload(response, 200))
+        held = payload.get("held")
+        if not isinstance(held, bool):
+            raise TypeError(_INVALID_LOCK_RESPONSE)
         return LockState(
-            held=payload["held"],
+            held=held,
             expires_at=_parse_datetime(payload.get("expires_at")),
-            fencing_token=payload.get("fencing_token"),
+            fencing_token=_fencing_token(payload.get("fencing_token")),
         )
 
     def acquire(
@@ -173,17 +198,18 @@ class Locks:
                 raise
             started_at = _lease_now()
             payload = self._acquire_payload(key, ttl, token, request_id, authorization)
+        expires_at, fencing_token = _lease_fields(payload)
         lease = LockLease(
             key=key,
             token=token,
-            expires_at=_parse_datetime(payload.get("expires_at")),
-            fencing_token=cast("int | None", payload.get("fencing_token")),
+            expires_at=expires_at,
+            fencing_token=fencing_token,
         )
         return lease, started_at
 
     def _acquire_payload(
         self, key: str, ttl: int, token: str, request_id: str, authorization: str
-    ) -> dict[str, object]:
+    ) -> Mapping[object, object]:
         response = invoke(
             self._client._transport.acquire_project_lock,
             authorization=authorization,
@@ -192,7 +218,7 @@ class Locks:
             token=token,
             request_id=request_id,
         )
-        return cast("dict[str, object]", response_payload(response, 201))
+        return _lock_values(response_payload(response, 201))
 
     def renew(
         self, key: str, lease: LockLease, *, ttl: int, request_id: str | None = None
@@ -216,12 +242,13 @@ class Locks:
             ttl=ttl,
             token=lease.token,
         )
-        payload = response_payload(response, 200)
+        payload = _lock_values(response_payload(response, 200))
+        expires_at, fencing_token = _lease_fields(payload)
         return LockLease(
             key=key,
             token=lease.token,
-            expires_at=_parse_datetime(payload.get("expires_at")),
-            fencing_token=payload.get("fencing_token"),
+            expires_at=expires_at,
+            fencing_token=fencing_token,
         )
 
     def release(

volcano_sdk/logs.py

@@ -11,16 +11,23 @@ from ._log_response import (
     response_values,
     search_metadata,
 )
-from ._transport import TransportResponse, invoke, response_payload
+from ._transport import Transport, TransportResponse, invoke, response_payload
 from .models import JSONValue, LogActivityResponse, LogSearchResponse, _freeze_json
 
 if TYPE_CHECKING:
-    from .client import VolcanoClient
+    from .auth import Auth
 
 _INVALID_PROJECT_ID = "project_id must be a non-empty string"
 _INVALID_LOG_REQUEST = "Log request must be a mapping"
 
 
+class LogsContext(Protocol):
+    """Client capabilities required by project log reads."""
+
+    _transport: Transport
+    auth: Auth
+
+
 class LogsTransport(Protocol):
     """Transport operations required by the logs facade."""
 
@@ -48,7 +55,7 @@ class LogsTransport(Protocol):
 class Logs:
     """Search retained project logs and activity."""
 
-    def __init__(self, client: VolcanoClient) -> None:
+    def __init__(self, client: LogsContext) -> None:
         """Bind log reads to a Volcano client."""
         self._client = client
 

volcano_sdk/realtime.py

@@ -8,11 +8,21 @@ import inspect
 from collections.abc import Awaitable, Callable, Mapping
 from dataclasses import dataclass, field, replace
 from types import MappingProxyType
-from typing import TYPE_CHECKING, Any, Literal, Protocol, TypeAlias, cast
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+    Protocol,
+    TypeAlias,
+    TypeVar,
+    cast,
+    overload,
+)
 from urllib.parse import quote, urlsplit, urlunsplit
 
 from typing_extensions import override
 
+from ._callbacks import require_callable
 from ._realtime_fetch_worker import (
     PostgresFetchJob,
     PostgresFetchOutcome,
@@ -25,6 +35,7 @@ from ._transport import (
     invoke_async,
     response_payload,
 )
+from .database import _database_rows
 from .models import JSONValue, _freeze_json
 
 if TYPE_CHECKING:
@@ -34,6 +45,8 @@ if TYPE_CHECKING:
     from .models import Session
 
 _PostgresFetchRequest: TypeAlias = PostgresFetchRequest
+_SubscriptionT = TypeVar("_SubscriptionT")
+_DefaultT = TypeVar("_DefaultT")
 
 MessageCallback = Callable[[Any], Any]
 RealtimeCallback = Callable[[Any], Any]
@@ -459,9 +472,20 @@ def _centrifuge_client(
     )
 
 
-class _ProjectAwareSubscriptions(dict[str, Any]):
+class _ProjectAwareSubscriptions(dict[str, _SubscriptionT]):
+    @overload
+    def get(self, key: str, default: None = None) -> _SubscriptionT | None: ...
+
+    @overload
+    def get(self, key: str, default: _SubscriptionT) -> _SubscriptionT: ...
+
+    @overload
+    def get(self, key: str, default: _DefaultT) -> _SubscriptionT | _DefaultT: ...
+
     @override
-    def get(self, key: str, default: Any = None) -> Any:
+    def get(
+        self, key: str, default: _DefaultT | None = None
+    ) -> _SubscriptionT | _DefaultT | None:
         subscription = super().get(key)
         if subscription is not None:
             return subscription
@@ -473,15 +497,22 @@ class _ProjectAwareSubscriptions(dict[str, Any]):
         return max(matches, key=lambda match: len(match[0]))[1] if matches else default
 
 
+def _project_subscriptions(value: object) -> _ProjectAwareSubscriptions[object]:
+    if not isinstance(value, dict):
+        raise TypeError(SUBSCRIPTION_REGISTRY_UNAVAILABLE)
+    subscriptions = _ProjectAwareSubscriptions[object]()
+    for channel, subscription in cast("Mapping[object, object]", value).items():
+        if not isinstance(channel, str):
+            raise TypeError(SUBSCRIPTION_REGISTRY_UNAVAILABLE)
+        subscriptions[channel] = subscription
+    return subscriptions
+
+
 class _VolcanoCentrifugeConnection:
     def __init__(self, connection: CentrifugeConnection) -> None:
         self._connection = connection
         state = vars(connection)
-        subscriptions = state.get("_subs")
-        if not isinstance(subscriptions, dict):
-            raise TypeError(SUBSCRIPTION_REGISTRY_UNAVAILABLE)
-        typed_subscriptions = cast("dict[str, Any]", subscriptions)
-        state["_subs"] = _ProjectAwareSubscriptions(typed_subscriptions)
+        state["_subs"] = _project_subscriptions(state.get("_subs"))
 
     async def connect(self) -> None:
         await self._connection.connect()
@@ -1361,8 +1392,7 @@ class Realtime:
                 "limit": len(row_ids),
             },
         )
-        payload = response_payload(response, 200)
-        rows = list(payload["data"])
+        rows = _database_rows(response_payload(response, 200))
         return tuple(
             next(
                 (row for row in rows if row.get("id") == request.row_id),
@@ -1409,8 +1439,7 @@ class Realtime:
         event: str,
         callback: RealtimeCallback,
     ) -> UnsubscribeCallback:
-        if not callable(callback):
-            raise TypeError(CALLBACK_NOT_CALLABLE)
+        require_callable(callback, CALLBACK_NOT_CALLABLE)
         self._next_callback_id += 1
         callback_id = self._next_callback_id
         self._connection_callbacks[event][callback_id] = callback
@@ -1666,19 +1695,31 @@ class Realtime:
                     subscription = await self._prepare_subscription(channel, generation)
                     if channel._subscribed:
                         return
-                    channel._paused = False
-                    await subscription.subscribe()
-                channel._readiness_task = asyncio.create_task(
-                    _wait_subscription(channel, subscription)
-                )
-                try:
-                    await channel._readiness_task
-                finally:
-                    channel._readiness_task = None
+                    await self._resume_subscription(channel, subscription)
+                await self._wait_subscription_readiness(channel, subscription)
             except BaseException as error:
                 await self._cleanup_failed_subscription(channel, subscription, error)
                 raise
 
+    @staticmethod
+    async def _resume_subscription(
+        channel: Channel, subscription: CentrifugeSubscription
+    ) -> None:
+        channel._paused = False
+        await subscription.subscribe()
+
+    @staticmethod
+    async def _wait_subscription_readiness(
+        channel: Channel, subscription: CentrifugeSubscription
+    ) -> None:
+        channel._readiness_task = asyncio.create_task(
+            _wait_subscription(channel, subscription)
+        )
+        try:
+            await channel._readiness_task
+        finally:
+            channel._readiness_task = None
+
     async def _cleanup_failed_subscription(
         self,
         channel: Channel,

volcano_sdk/storage.py

@@ -11,7 +11,7 @@ from dataclasses import dataclass
 from datetime import datetime
 from io import SEEK_END, BytesIO
 from tempfile import TemporaryFile
-from typing import TYPE_CHECKING, Any, BinaryIO, Protocol, cast
+from typing import TYPE_CHECKING, Any, BinaryIO, Protocol, TypeGuard, cast
 from urllib.parse import quote
 
 from ._transport import (
@@ -50,6 +50,7 @@ _HTTP_PARTIAL_CONTENT = 206
 _UPLOAD_SPOOL_READ_SIZE = 1_048_576
 _UPLOAD_SOURCE_UNAVAILABLE = "Upload source is temporarily unavailable"
 _INVALID_SIMPLE_UPLOAD = "Upload data must be bytes or a readable binary stream"
+_INVALID_UPLOAD_RESPONSE = "Expected a storage upload response object"
 
 
 def _optional_datetime(value: object) -> datetime | None:
@@ -154,11 +155,15 @@ def _upload_session_status(payload: object) -> UploadSessionStatus:
     )
 
 
+def _is_object_sequence(value: object) -> TypeGuard[Sequence[object]]:
+    return isinstance(value, Sequence)
+
+
 def _storage_paths(paths: object) -> tuple[str, ...]:
     if isinstance(paths, str):
         raw_paths: tuple[object, ...] = (paths,)
-    elif isinstance(paths, Sequence):
-        raw_paths = tuple(cast("Sequence[object]", paths))
+    elif _is_object_sequence(paths):
+        raw_paths = tuple(paths)
     else:
         raise TypeError(_INVALID_STORAGE_PATHS)
     if not raw_paths or any(
@@ -494,7 +499,12 @@ class StorageBucket:
             binding=binding,
         )
         payload = response_payload(response, 201)
-        return dict(payload)
+        if not isinstance(payload, Mapping):
+            raise TypeError(_INVALID_UPLOAD_RESPONSE)
+        values = cast("Mapping[object, object]", payload)
+        if not all(isinstance(key, str) for key in values):
+            raise TypeError(_INVALID_UPLOAD_RESPONSE)
+        return dict(cast("Mapping[str, Any]", values))
 
     def download(self, path: str, *, byte_range: str | None = None) -> bytes:
         """Download bytes from a path in this bucket.

{volcano_sdk_python-0.10.2.dist-info → volcano_sdk_python-0.10.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: volcano-sdk-python
-Version: 0.10.2
+Version: 0.10.4
 Summary: Official Python SDK for Volcano
 Project-URL: Homepage, https://volcano.dev
 Project-URL: Repository, https://github.com/Kong/volcano-sdk-python
@@ -11,6 +11,8 @@ License-File: LICENSE
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.11
 Requires-Dist: attrs>=26.1.0
@@ -330,6 +332,10 @@ the clock or a random value.
 | `ctx.child(name, fn)` | Groups operations under one recorded context. |
 | `ctx.log` | The execution's logger, suppressed while an operation is replayed. |
 
+`ctx.log` and a step's `scope.log` expose `debug`, `info`, `warning`, `error`,
+and `exception`. They accept a message, formatting arguments, and an optional
+`extra` mapping. Messages are suppressed during replay.
+
 `ctx.map` and `ctx.parallel` both return a batch result: `items` (the items that
 finished, each with `index`, `status`, `result`, `error`), `results`, `errors`,
 `succeeded`, `failed`, `completed`, `completion_reason`, and `throw_if_failed()`.
@@ -966,7 +972,8 @@ does not need it otherwise.
 
 ## Compatibility
 
-CI tests the SDK on Python 3.11 and 3.14. Its public facade is intentionally
+CI tests the SDK on every Python version from 3.11 through 3.14.
+Its public facade is intentionally
 independent of generated httpx types. The bundled `openapi/openapi.yaml` matches
 the public bundle from [Hosting #991](https://github.com/Kong/volcano-hosting/pull/991)
 at commit `ef03f689e`.

{volcano_sdk_python-0.10.2.dist-info → volcano_sdk_python-0.10.4.dist-info}/RECORD

@@ -1,4 +1,5 @@
 volcano_sdk/__init__.py,sha256=azhzz2nWUoy_j8sPRuovhs8Fy8CVuwJpLAvT5bhgT5g,2172
+volcano_sdk/_callbacks.py,sha256=VuhphT6RM7IfIGPSAVXGC-Xm6ml-aUOSN-GQ9YVDycg,329
 volcano_sdk/_function_resolution.py,sha256=3qfLiyxMUKsOCyaoZpL4sDQkfwq56CPGGwcRW1aorSg,5919
 volcano_sdk/_lock_guard.py,sha256=YxuJDQOCxHYf7mk6Cp_CPE-mYKC9IoGt_Cxe7SVL8aw,5922
 volcano_sdk/_lock_renewer.py,sha256=cgogAmoRM_An-PdymXumuGmxm62MGqOsQU4c_PYlUjg,1000
@@ -7,21 +8,21 @@ volcano_sdk/_log_response.py,sha256=wZaugr0eD0ZLSa-M6TUEwdIDsI_wblyDXucYEwNK14c,
 volcano_sdk/_realtime_fetch_worker.py,sha256=f3mUPe5qZmGuhA9jfpqEUtpLZmvlJ1FhI1XkNz238FI,10406
 volcano_sdk/_session.py,sha256=w7B1rwbhH3yoE8kFA6gSpUpQb24rPwppotMu-IPHXdI,3025
 volcano_sdk/_session_operations.py,sha256=s_m-Gl-knjDrjUOFl6z2lJW4IGHAgCSCjRNA7LCB5j0,5727
-volcano_sdk/_transport.py,sha256=hPciv-WJ7A7Siu6SNU6Ix6x_avPGTucxj8rzJePj43w,61904
-volcano_sdk/auth.py,sha256=f1Dfyq6gpoIzajUKooiVGqgWgvVtCsF_dIG_uA23Hx0,52224
-volcano_sdk/client.py,sha256=MiwpMsAMyRebPZ7qhktx698TNmQR2y-Gytgf-FNG3TU,12643
+volcano_sdk/_transport.py,sha256=XcDk8NAEAHmtH3nmlMWIixcIiEFb-FP_n8VU44QcuXg,61907
+volcano_sdk/auth.py,sha256=OxK9s6XW9jNGA_cXos-cHEZYcmYsxrojruSyLS0mWVs,52237
+volcano_sdk/client.py,sha256=KH52e5WC4ii-hnipB9vNzSDEyfvvpOMBCdtwzRqNUOI,12701
 volcano_sdk/connection_string.py,sha256=p87P-fd9wVfia-LLRRsFTkW6tzx9FXn-GAy9OIOoDvE,2664
-volcano_sdk/database.py,sha256=60Rt4oeaS_WHutC6wGPFunVvFHIo08rwaLiHGuFNRKM,12860
-volcano_sdk/durable.py,sha256=3PuhxRNJy6m7IBhpc_Np6wnlRZVTmChdjjqVp_wLoxk,13250
-volcano_sdk/durable_authoring.py,sha256=NqBY18LDqZoNsnChx_5XjT-1h9OoAniAu7Yu911ebKw,34029
+volcano_sdk/database.py,sha256=XuXGqlfEPvlOBB33jyTVNhRGe4vrgzOBne2rTRzkQis,13806
+volcano_sdk/durable.py,sha256=YQa_5tT4kxkHTyP4nRMhjWyExnSICXD_RAipSQ1cax8,13422
+volcano_sdk/durable_authoring.py,sha256=L8qK694e0aPLnRLIDQm9dbYGy4M0NPf9wZYECkVrOfA,35842
 volcano_sdk/errors.py,sha256=ffs66FIN_jhyh5SMj7KdXb-zVV3DSgVK6xJEPNA5h9Y,1613
-volcano_sdk/functions.py,sha256=pdKdgDNo13MbEedeDYtAFazK4r7AZtzYQqrfz-xV5Pw,12977
-volcano_sdk/locks.py,sha256=ptZq7CvXtlK0VU42Qq6DcQQMMjMqQl1zw9cxqdALMfU,9922
-volcano_sdk/logs.py,sha256=6gYFKLdPcG62KrVugpgw57Lqx0WcxKEZ-zosRz-DeW4,3943
+volcano_sdk/functions.py,sha256=7loNEF1tkojAnp_C0rBWWcvO3l22Tx2JQn28l6PoV2Q,13264
+volcano_sdk/locks.py,sha256=Ctr4OKAmJqCPD03lkPEjH7JzYfdpESHEYFOmTj0z1Ds,10894
+volcano_sdk/logs.py,sha256=l71mT5ejIq2_9O_aug5_pZuZPAYkdJQa03RhPvSDH9g,4075
 volcano_sdk/models.py,sha256=ZIo2YdZ-Ba7rCmHBo3eV9LGjpEftVTeVmrrfq-zGujs,11182
 volcano_sdk/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-volcano_sdk/realtime.py,sha256=k1vqSDZUfN-lO1zKSGd0lM-Cf9q2ebkdngu8oniLZF8,63091
-volcano_sdk/storage.py,sha256=fZKa2Jf0w_JVytQ3UjfFSUZRAJllwSHuqbH3ywzhb8Q,27617
+volcano_sdk/realtime.py,sha256=qulBz-rUm8SFId_jt40z7Q-wDtTb572gi1SKMDqbAto,64213
+volcano_sdk/storage.py,sha256=kh5xN5Pu1gp3fOKyJlmrMGE9ZnN7U9jkLp_l2Ovj1_Y,28081
 volcano_sdk/_generated/__init__.py,sha256=ZlB8wMYdN6EjpUS5W_lX3jsxq9G1kOcmUr-j3Fccfn8,164
 volcano_sdk/_generated/client.py,sha256=GDzw6T2uRmPlUb1DImpBGxwy0dNbhmBknfvvIQW0GuU,12387
 volcano_sdk/_generated/errors.py,sha256=trp-p5qn1_JLRxGZhdHtICaNPaCrcDCe4TgIihBravk,546
@@ -809,7 +810,7 @@ volcano_sdk/_generated/models/usage_data_point.py,sha256=d4U08JbVTiIMM_l2BmRILL1
 volcano_sdk/_generated/models/variable.py,sha256=t8XaBfTwIH42L8RL4DFDtdqbhVfDEnRS5Axq2q6Tpvk,6405
 volcano_sdk/_generated/models/variable_deploy_source.py,sha256=G_aCiFHzQx8WhJFs0GvYZEFclfTrfkDvd3kT1e3vty8,463
 volcano_sdk/_generated/models/variable_status.py,sha256=THSsKBSiAYG4kAtBzGA4TZqxjgx8hdL0Q4qCdZfOj00,391
-volcano_sdk_python-0.10.2.dist-info/METADATA,sha256=iZ4NdMioMG22X20j6pclTVxcptrI5soVYsx_GYHfpqw,45435
-volcano_sdk_python-0.10.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-volcano_sdk_python-0.10.2.dist-info/licenses/LICENSE,sha256=AIHJy-5MFqM8fHfuGFTTb9a8rvJGypcVgN4aZ-7XTWw,11387
-volcano_sdk_python-0.10.2.dist-info/RECORD,,
+volcano_sdk_python-0.10.4.dist-info/METADATA,sha256=HGwNfdnW1A-y9EZipIB3jxJbC8y9PDbHDjJBQY0O8-A,45774
+volcano_sdk_python-0.10.4.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+volcano_sdk_python-0.10.4.dist-info/licenses/LICENSE,sha256=AIHJy-5MFqM8fHfuGFTTb9a8rvJGypcVgN4aZ-7XTWw,11387
+volcano_sdk_python-0.10.4.dist-info/RECORD,,