volcano-sdk-python 0.10.3__py3-none-any.whl → 0.11.0__py3-none-any.whl

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/durable_authoring.py

@@ -131,6 +131,24 @@ class DurableRuntimeMissingError(Exception):
         self.__cause__ = cause
 
 
+class _DurableEngine(Protocol):
+    """The operations the Volcano facade needs from the optional runtime."""
+
+    def seconds(self, value: int) -> object: ...
+
+    def step_options(self, *, retry: Retry, at_most_once: bool) -> object: ...
+
+    def wait_condition_options(self, options: WaitUntilOptions) -> object: ...
+
+    def map_options(self, options: BatchOptions | None) -> object: ...
+
+    def parallel_options(self, options: BatchOptions | None) -> object: ...
+
+    def named_branch(
+        self, run: Callable[[object], object], name: str | None
+    ) -> object: ...
+
+
 class _Engine:
     """The durable protocol, from the AWS durable execution SDK.
 
@@ -186,6 +204,101 @@ class _Engine:
             cls._loaded = cls()
         return cls._loaded
 
+    def seconds(self, value: int) -> EngineDuration:
+        """Build the runtime's duration from whole seconds."""
+        return self.duration.from_seconds(value)
+
+    def step_options(self, *, retry: Retry, at_most_once: bool) -> StepConfig:
+        """Build the runtime's step options."""
+        config: dict[str, Any] = {}
+        if at_most_once:
+            config["step_semantics"] = self.step_semantics.AT_MOST_ONCE_PER_RETRY
+        strategy = self._retry_strategy(retry)
+        if strategy is not None:
+            config["retry_strategy"] = strategy
+        return self.step_config(**config)
+
+    def _retry_strategy(self, retry: object) -> Any:
+        if retry is None or retry is True:
+            return None
+        # False disables the runtime's default retry policy for this step.
+        if retry is False:
+            return self._never_retry()
+        if isinstance(retry, RetryOptions):
+            return self.create_retry_strategy(
+                self.retry_strategy_config(**self._retry_kwargs(retry))
+            )
+        if callable(retry):
+            return retry
+        raise TypeError(_INVALID_RETRY)
+
+    def _never_retry(self) -> Callable[[Exception, int], RetryDecision]:
+        no_delay = self.seconds(0)
+
+        def never_retry(_error: Exception, _attempt: int) -> RetryDecision:
+            return self.retry_decision(should_retry=False, delay=no_delay)
+
+        return never_retry
+
+    def _retry_kwargs(self, retry: RetryOptions) -> dict[str, Any]:
+        return _engine_kwargs(
+            max_attempts=retry.attempts,
+            initial_delay=self._optional_duration(retry.initial_delay, "initial_delay"),
+            max_delay=self._optional_duration(retry.max_delay, "max_delay"),
+            backoff_rate=retry.backoff_rate,
+            retryable_errors=(None if retry.retry_on is None else list(retry.retry_on)),
+            retryable_error_types=(
+                None if retry.retry_on_types is None else list(retry.retry_on_types)
+            ),
+        )
+
+    def _optional_duration(
+        self, value: Duration | None, field_name: str
+    ) -> EngineDuration | None:
+        return None if value is None else self.seconds(_to_seconds(value, field_name))
+
+    def wait_condition_options(self, options: WaitUntilOptions) -> object:
+        """Build the runtime's polling options."""
+        until = options.until
+
+        def keep_polling(state: Any) -> bool:
+            return not until(state)
+
+        strategy = self.wait_strategy_config(
+            **_engine_kwargs(
+                should_continue_polling=keep_polling,
+                max_attempts=options.max_attempts,
+                initial_delay=self._optional_duration(options.interval, "interval"),
+                max_delay=self._optional_duration(options.max_interval, "max_interval"),
+                backoff_rate=options.backoff_rate,
+            )
+        )
+        return self.wait_for_condition_config(
+            wait_strategy=self.create_wait_strategy(strategy),
+            initial_state=options.initial_state,
+        )
+
+    def _batch_options(self, options: BatchOptions | None) -> dict[str, Any]:
+        resolved = BatchOptions() if options is None else options
+        config = _engine_kwargs(max_concurrency=resolved.concurrency)
+        if resolved.min_succeeded is not None:
+            config["completion_config"] = self.completion_config(
+                min_successful=resolved.min_succeeded
+            )
+        return config
+
+    def map_options(self, options: BatchOptions | None) -> object:
+        """Build the runtime's map options."""
+        return self.map_config(**self._batch_options(options))
+
+    def parallel_options(self, options: BatchOptions | None) -> ParallelConfig:
+        """Build the runtime's parallel options."""
+        return self.parallel_config(**self._batch_options(options))
+
+    def named_branch(self, run: Callable[[object], object], name: str | None) -> object:
+        """Build a named runtime branch."""
+        return self.parallel_branch(func=run, name=name)
+
 
 @dataclass(frozen=True, slots=True)
 class RetryOptions:
@@ -436,7 +549,7 @@ class DurableContext:
 
     __slots__ = ("_context", "_engine", "log")
 
-    def __init__(self, context: Any, engine: _Engine) -> None:
+    def __init__(self, context: Any, engine: _DurableEngine) -> None:
         """Wrap an engine context."""
         self._context = context
         self._engine = engine
@@ -478,7 +591,7 @@ class DurableContext:
             self._context.step(
                 run,
                 step_name,
-                self._step_config(retry=retry, at_most_once=at_most_once),
+                self._engine.step_options(retry=retry, at_most_once=at_most_once),
             ),
         )
 
@@ -543,29 +656,13 @@ class DurableContext:
         check_func = _callable(check, "wait_until")
         _validate_wait_options(options)
         engine = self._engine
-        until = options.until
-
-        def keep_polling(state: Any) -> bool:
-            return not until(state)
 
         def check_state(state: Any, scope: Any) -> Any:
             return check_func(state, StepScope(scope.logger, scope.attempt))
 
-        strategy = engine.wait_strategy_config(
-            **_engine_kwargs(
-                should_continue_polling=keep_polling,
-                max_attempts=options.max_attempts,
-                initial_delay=self._optional_duration(options.interval, "interval"),
-                max_delay=self._optional_duration(options.max_interval, "max_interval"),
-                backoff_rate=options.backoff_rate,
-            )
-        )
         return self._context.wait_for_condition(
             check_state,
-            engine.wait_for_condition_config(
-                wait_strategy=engine.create_wait_strategy(strategy),
-                initial_state=options.initial_state,
-            ),
+            engine.wait_condition_options(options),
             name,
         )
 
@@ -601,7 +698,7 @@ class DurableContext:
                 list(items),
                 run,
                 name,
-                engine.map_config(**self._batch_config(options)),
+                engine.map_options(options),
             )
         )
 
@@ -623,7 +720,7 @@ class DurableContext:
             self._context.parallel(
                 [self._branch(branch) for branch in branches],
                 name,
-                engine.parallel_config(**self._batch_config(options)),
+                engine.parallel_options(options),
             )
         )
 
@@ -650,7 +747,7 @@ class DurableContext:
             def run_named(context: Any) -> Any:
                 return named(DurableContext(context, engine))
 
-            return engine.parallel_branch(func=run_named, name=branch.name)
+            return engine.named_branch(run_named, branch.name)
         require_callable(branch, _INVALID_BRANCH)
         bare = branch
 
@@ -659,72 +756,7 @@ class DurableContext:
 
         return run_bare
 
-    def _batch_config(self, options: BatchOptions | None) -> dict[str, Any]:
-        resolved = BatchOptions() if options is None else options
-        config = _engine_kwargs(max_concurrency=resolved.concurrency)
-        if resolved.min_succeeded is not None:
-            config["completion_config"] = self._engine.completion_config(
-                min_successful=resolved.min_succeeded
-            )
-        return config
-
-    def _step_config(self, *, retry: Retry, at_most_once: bool) -> StepConfig:
-        engine = self._engine
-        config: dict[str, Any] = {}
-        if at_most_once:
-            config["step_semantics"] = engine.step_semantics.AT_MOST_ONCE_PER_RETRY
-        strategy = self._retry_strategy(retry)
-        if strategy is not None:
-            config["retry_strategy"] = strategy
-        return engine.step_config(**config)
-
-    def _retry_strategy(self, retry: object) -> Any:
-        engine = self._engine
-        if retry is None or retry is True:
-            return None
-        # retry=False means "fail on the first error", which is not the same as
-        # leaving retry unset: the platform retries by default, and a step that
-        # is not safe to repeat wants the opposite.
-        if retry is False:
-            return self._never_retry()
-        if isinstance(retry, RetryOptions):
-            return engine.create_retry_strategy(
-                engine.retry_strategy_config(**self._retry_kwargs(retry))
-            )
-        if callable(retry):
-            return retry
-        raise TypeError(_INVALID_RETRY)
-
-    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) -> RetryDecision:
-            return engine.retry_decision(should_retry=False, delay=no_delay)
-
-        return never_retry
-
-    def _retry_kwargs(self, retry: RetryOptions) -> dict[str, Any]:
-        return _engine_kwargs(
-            max_attempts=retry.attempts,
-            initial_delay=self._optional_duration(retry.initial_delay, "initial_delay"),
-            max_delay=self._optional_duration(retry.max_delay, "max_delay"),
-            backoff_rate=retry.backoff_rate,
-            retryable_errors=(None if retry.retry_on is None else list(retry.retry_on)),
-            retryable_error_types=(
-                None if retry.retry_on_types is None else list(retry.retry_on_types)
-            ),
-        )
-
-    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) -> EngineDuration:
-        return self._engine.duration.from_seconds(_to_seconds(value, field_name))
-
-    def _wait_duration(self, value: object) -> EngineDuration:
+    def _wait_duration(self, value: object) -> object:
         seconds = _to_seconds(value, "wait")
         if seconds < _MIN_WAIT_SECONDS:
             message = f"wait must be at least {_MIN_WAIT_SECONDS} second"
@@ -732,7 +764,7 @@ class DurableContext:
         if seconds > _MAX_WAIT_SECONDS:
             message = f"wait must be at most {_MAX_WAIT_SECONDS} seconds (366 days)"
             raise TypeError(message)
-        return self._engine.duration.from_seconds(seconds)
+        return self._engine.seconds(seconds)
 
 
 @overload

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/realtime.py

@@ -35,6 +35,7 @@ from ._transport import (
     invoke_async,
     response_payload,
 )
+from .database import _database_rows
 from .models import JSONValue, _freeze_json
 
 if TYPE_CHECKING:
@@ -1391,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),

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, TypeGuard, cast
+from typing import TYPE_CHECKING, 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:
@@ -462,6 +463,13 @@ def _upload_content_type(value: object) -> str:
     return value
 
 
+def _is_string_keyed_mapping(value: object) -> TypeGuard[Mapping[str, object]]:
+    if not isinstance(value, Mapping):
+        return False
+    mapping = cast("Mapping[object, object]", value)
+    return all(isinstance(key, str) for key in mapping)
+
+
 @dataclass(frozen=True, slots=True)
 class StorageBucket:
     """Operations scoped to one storage bucket."""
@@ -475,7 +483,7 @@ class StorageBucket:
         data: bytes | BinaryIO,
         *,
         content_type: str | None = None,
-    ) -> dict[str, Any]:
+    ) -> dict[str, object]:
         """Upload bytes or the remaining contents of a binary stream.
 
         Returns:
@@ -498,6 +506,8 @@ class StorageBucket:
             binding=binding,
         )
         payload = response_payload(response, 201)
+        if not _is_string_keyed_mapping(payload):
+            raise TypeError(_INVALID_UPLOAD_RESPONSE)
         return dict(payload)
 
     def download(self, path: str, *, byte_range: str | None = None) -> bytes:

{volcano_sdk_python-0.10.3.dist-info → volcano_sdk_python-0.11.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: volcano-sdk-python
-Version: 0.10.3
+Version: 0.11.0
 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.10.3.dist-info → volcano_sdk_python-0.11.0.dist-info}/RECORD

@@ -8,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/_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=XuXGqlfEPvlOBB33jyTVNhRGe4vrgzOBne2rTRzkQis,13806
 volcano_sdk/durable.py,sha256=YQa_5tT4kxkHTyP4nRMhjWyExnSICXD_RAipSQ1cax8,13422
-volcano_sdk/durable_authoring.py,sha256=L8qK694e0aPLnRLIDQm9dbYGy4M0NPf9wZYECkVrOfA,35842
+volcano_sdk/durable_authoring.py,sha256=92ENW366IdeP7P-ABqo-HB8V7YsG8KkE_ekVWnu9ZXU,36899
 volcano_sdk/errors.py,sha256=ffs66FIN_jhyh5SMj7KdXb-zVV3DSgVK6xJEPNA5h9Y,1613
 volcano_sdk/functions.py,sha256=7loNEF1tkojAnp_C0rBWWcvO3l22Tx2JQn28l6PoV2Q,13264
-volcano_sdk/locks.py,sha256=ptZq7CvXtlK0VU42Qq6DcQQMMjMqQl1zw9cxqdALMfU,9922
+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=gYTqfrmR0owEVxUjUU2Su8k6u_wm1Pjyggo2jJXSR1g,64200
-volcano_sdk/storage.py,sha256=3US6vkhMC9jaTah6KcCatuAuLATjpPZfYHdF20t361U,27713
+volcano_sdk/realtime.py,sha256=qulBz-rUm8SFId_jt40z7Q-wDtTb572gi1SKMDqbAto,64213
+volcano_sdk/storage.py,sha256=FUuE5SnF5IV-S4OF-sFtMqzidWvUC_Gt5Xw5NW7aUss,28137
 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
@@ -810,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.3.dist-info/METADATA,sha256=hSD3rh78qfzXlJ1uF0_cOLwlp9q5IEHrXZA5vnwuCl4,45774
-volcano_sdk_python-0.10.3.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-volcano_sdk_python-0.10.3.dist-info/licenses/LICENSE,sha256=AIHJy-5MFqM8fHfuGFTTb9a8rvJGypcVgN4aZ-7XTWw,11387
-volcano_sdk_python-0.10.3.dist-info/RECORD,,
+volcano_sdk_python-0.11.0.dist-info/METADATA,sha256=paWdliEZVJYayjiBqVjB_zjpTx8faq62pbpH5ZZOHZM,45774
+volcano_sdk_python-0.11.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+volcano_sdk_python-0.11.0.dist-info/licenses/LICENSE,sha256=AIHJy-5MFqM8fHfuGFTTb9a8rvJGypcVgN4aZ-7XTWw,11387
+volcano_sdk_python-0.11.0.dist-info/RECORD,,