dex-python-sdk 0.7.0__tar.gz → 0.8.0__tar.gz

{dex_python_sdk-0.7.0 → dex_python_sdk-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dex-python-sdk
-Version: 0.7.0
+Version: 0.8.0
 Requires-Dist: grpcio>=1.83.0
 Requires-Dist: grpcio-status>=1.83.0
 Requires-Dist: protobuf>=7.35.1
@@ -455,7 +455,10 @@ client operations, and assertions as the Java suite against an isolated
 The strongly typed contracts, registry, synchronous Client/Worker, optional
 `AsyncClient`/`AsyncWorker` (`grpc.aio`), and Rust-backed BlobCache are
 implemented. Python owns its gRPC transport; the native bridge is limited to
-the shared BlobCache. Design notes:
+the shared BlobCache. Serialized object values use wire encoding `json` for JSON
+and `raw` for raw bytes. Internal Blob references are opaque. Hydration sends the
+owning Flow ID with each reference, and the cache is isolated by
+`(flow_id, blob_ref)`. Design notes:
 [`python-sdk-async-apis.md`](../docs/design/plan/python-sdk-async-apis.md) and
 [`python-sdk-step-streaming.md`](../docs/design/plan/python-sdk-step-streaming.md).
 

{dex_python_sdk-0.7.0 → dex_python_sdk-0.8.0}/README.md

@@ -439,7 +439,10 @@ client operations, and assertions as the Java suite against an isolated
 The strongly typed contracts, registry, synchronous Client/Worker, optional
 `AsyncClient`/`AsyncWorker` (`grpc.aio`), and Rust-backed BlobCache are
 implemented. Python owns its gRPC transport; the native bridge is limited to
-the shared BlobCache. Design notes:
+the shared BlobCache. Serialized object values use wire encoding `json` for JSON
+and `raw` for raw bytes. Internal Blob references are opaque. Hydration sends the
+owning Flow ID with each reference, and the cache is isolated by
+`(flow_id, blob_ref)`. Design notes:
 [`python-sdk-async-apis.md`](../docs/design/plan/python-sdk-async-apis.md) and
 [`python-sdk-step-streaming.md`](../docs/design/plan/python-sdk-step-streaming.md).
 

{dex_python_sdk-0.7.0 → dex_python_sdk-0.8.0}/dex/_async_value_hydrator.py

@@ -20,6 +20,7 @@ _LOGGER = logging.getLogger(__name__)
 
 @dataclass
 class _PendingBlob:
+    flow_id: str
     blob_id: str
     is_object: bool
     request: pb.Value
@@ -36,21 +37,37 @@ class AsyncValueHydrator:
         self._service = service
         self._cache = cache
 
-    async def hydrate(self, value: pb.Value) -> pb.Value:
-        return (await self.hydrate_all([value]))[0]
+    async def hydrate(self, flow_id: str, value: pb.Value) -> pb.Value:
+        return (await self.hydrate_all(flow_id, [value]))[0]
 
-    async def hydrate_all(self, values: list[pb.Value]) -> list[pb.Value]:
+    async def hydrate_all(
+        self,
+        flow_id: str,
+        values: list[pb.Value],
+    ) -> list[pb.Value]:
+        return await self.hydrate_all_for_flows(
+            [(flow_id, value) for value in values]
+        )
+
+    async def hydrate_all_for_flows(
+        self,
+        flow_values: list[tuple[str, pb.Value]],
+    ) -> list[pb.Value]:
+        values = [value for _, value in flow_values]
         hydrated = list(values)
-        pending: dict[tuple[str, bool], _PendingBlob] = {}
-        for index, value in enumerate(values):
+        pending: dict[tuple[str, str, bool], _PendingBlob] = {}
+        for index, (flow_id, value) in enumerate(flow_values):
+            if not flow_id:
+                raise ValueError(f"Flow ID at index {index} is required")
             key = self._blob_key(value)
             if key is None:
                 self._validate_concrete(value)
                 continue
-            blob = pending.get(key)
+            flow_blob_key = (flow_id, key[0], key[1])
+            blob = pending.get(flow_blob_key)
             if blob is None:
-                blob = _PendingBlob(key[0], key[1], value)
-                pending[key] = blob
+                blob = _PendingBlob(flow_id, key[0], key[1], value)
+                pending[flow_blob_key] = blob
             blob.indexes.append(index)
 
         misses: list[_PendingBlob] = []
@@ -86,7 +103,7 @@ class AsyncValueHydrator:
             for message in channel_values.messages
         ]
         values.extend(message.value for message in channel_messages)
-        hydrated = iter(await self.hydrate_all(values))
+        hydrated = iter(await self.hydrate_all(request.context.flow_id, values))
         result.step_input.CopyFrom(next(hydrated))
         if has_heartbeat:
             result.context.last_heartbeat_value.CopyFrom(next(hydrated))
@@ -122,7 +139,11 @@ class AsyncValueHydrator:
         values.extend(message.value for message in channel_messages)
         for channel_result in request.condition_results.channel_results:
             values.extend(channel_result.values)
-        hydrated = iter(await self.hydrate_all(values))
+        for flow_result in request.condition_results.sub_flow_results:
+            values.extend(
+                completion.completed_step_output for completion in flow_result.results
+            )
+        hydrated = iter(await self.hydrate_all(request.context.flow_id, values))
         if has_step_input:
             result.step_input.CopyFrom(next(hydrated))
         if has_heartbeat:
@@ -141,6 +162,9 @@ class AsyncValueHydrator:
         for channel_result in result.condition_results.channel_results:
             for value in channel_result.values:
                 value.CopyFrom(next(hydrated))
+        for flow_result in result.condition_results.sub_flow_results:
+            for completion in flow_result.results:
+                completion.completed_step_output.CopyFrom(next(hydrated))
         return result
 
     async def rpc_request(
@@ -156,7 +180,7 @@ class AsyncValueHydrator:
             for message in channel_values.messages
         ]
         values.extend(message.value for message in channel_messages)
-        hydrated = await self.hydrate_all(values)
+        hydrated = await self.hydrate_all(request.context.flow_id, values)
         result.input.CopyFrom(hydrated[0])
         hydrated_entries = iter(hydrated[1:])
         for entry in result.attributes:
@@ -172,10 +196,11 @@ class AsyncValueHydrator:
 
     async def step_outputs(
         self,
+        flow_id: str,
         outputs: list[pb.StepCompletionOutput],
     ) -> list[pb.StepCompletionOutput]:
         values = [output.completed_step_output for output in outputs]
-        hydrated = await self.hydrate_all(values)
+        hydrated = await self.hydrate_all(flow_id, values)
         results: list[pb.StepCompletionOutput] = []
         for output, value in zip(outputs, hydrated):
             result = pb.StepCompletionOutput()
@@ -188,7 +213,15 @@ class AsyncValueHydrator:
         if not misses:
             return
         response = await self._service.LoadBlobs(
-            pb.LoadBlobsRequest(values=[miss.request for miss in misses])
+            pb.LoadBlobsRequest(
+                entries=[
+                    pb.LoadBlobRequestEntry(
+                        flow_id=miss.flow_id,
+                        blob_value=miss.request,
+                    )
+                    for miss in misses
+                ]
+            )
         )
         for miss in misses:
             concrete = response.values.get(miss.blob_id)
@@ -200,7 +233,7 @@ class AsyncValueHydrator:
 
     def _read_cache(self, blob: _PendingBlob) -> pb.Value | None:
         try:
-            payload = self._cache.get(blob.blob_id)
+            payload = self._cache.get(self._cache_key(blob))
             if payload is None:
                 return None
             if blob.is_object:
@@ -212,7 +245,7 @@ class AsyncValueHydrator:
         except Exception:
             _LOGGER.warning("cannot read cached blob %s", blob.blob_id, exc_info=True)
             try:
-                self._cache.delete(blob.blob_id)
+                self._cache.delete(self._cache_key(blob))
             except Exception:
                 _LOGGER.warning(
                     "cannot delete cached blob %s",
@@ -228,7 +261,7 @@ class AsyncValueHydrator:
                 if blob.is_object
                 else concrete.string_value.encode("utf-8")
             )
-            self._cache.put(blob.blob_id, payload)
+            self._cache.put(self._cache_key(blob), payload)
         except Exception:
             _LOGGER.warning("cannot cache blob %s", blob.blob_id, exc_info=True)
 
@@ -247,6 +280,10 @@ class AsyncValueHydrator:
             return blob_id, True
         return None
 
+    @staticmethod
+    def _cache_key(blob: _PendingBlob) -> str:
+        return f"{len(blob.flow_id)}:{blob.flow_id}{blob.blob_id}"
+
     @staticmethod
     def _validate_hydrated(blob: _PendingBlob, value: pb.Value) -> None:
         expected = "obj_value" if blob.is_object else "string_value"
@@ -268,7 +305,7 @@ class AsyncValueHydrator:
                 raise ValueError("non-finite numbers are unsupported")
             return
         if kind == "obj_value":
-            if value.obj_value.encoding not in ("json", "rawbytes"):
+            if value.obj_value.encoding not in ("json", "raw"):
                 raise ValueError(
                     f"unsupported object encoding {value.obj_value.encoding}"
                 )

{dex_python_sdk-0.7.0 → dex_python_sdk-0.8.0}/dex/_value_hydrator.py

@@ -20,6 +20,7 @@ _LOGGER = logging.getLogger(__name__)
 
 @dataclass
 class _PendingBlob:
+    flow_id: str
     blob_id: str
     is_object: bool
     request: pb.Value
@@ -36,21 +37,31 @@ class ValueHydrator:
         self._service = service
         self._cache = cache
 
-    def hydrate(self, value: pb.Value) -> pb.Value:
-        return self.hydrate_all([value])[0]
+    def hydrate(self, flow_id: str, value: pb.Value) -> pb.Value:
+        return self.hydrate_all(flow_id, [value])[0]
 
-    def hydrate_all(self, values: list[pb.Value]) -> list[pb.Value]:
+    def hydrate_all(self, flow_id: str, values: list[pb.Value]) -> list[pb.Value]:
+        return self.hydrate_all_for_flows([(flow_id, value) for value in values])
+
+    def hydrate_all_for_flows(
+        self,
+        flow_values: list[tuple[str, pb.Value]],
+    ) -> list[pb.Value]:
+        values = [value for _, value in flow_values]
         hydrated = list(values)
-        pending: dict[tuple[str, bool], _PendingBlob] = {}
-        for index, value in enumerate(values):
+        pending: dict[tuple[str, str, bool], _PendingBlob] = {}
+        for index, (flow_id, value) in enumerate(flow_values):
+            if not flow_id:
+                raise ValueError(f"Flow ID at index {index} is required")
             key = self._blob_key(value)
             if key is None:
                 self._validate_concrete(value)
                 continue
-            blob = pending.get(key)
+            flow_blob_key = (flow_id, key[0], key[1])
+            blob = pending.get(flow_blob_key)
             if blob is None:
-                blob = _PendingBlob(key[0], key[1], value)
-                pending[key] = blob
+                blob = _PendingBlob(flow_id, key[0], key[1], value)
+                pending[flow_blob_key] = blob
             blob.indexes.append(index)
 
         misses: list[_PendingBlob] = []
@@ -86,7 +97,7 @@ class ValueHydrator:
             for message in channel_values.messages
         ]
         values.extend(message.value for message in channel_messages)
-        hydrated = iter(self.hydrate_all(values))
+        hydrated = iter(self.hydrate_all(request.context.flow_id, values))
         result.step_input.CopyFrom(next(hydrated))
         if has_heartbeat:
             result.context.last_heartbeat_value.CopyFrom(next(hydrated))
@@ -126,7 +137,7 @@ class ValueHydrator:
             values.extend(
                 completion.completed_step_output for completion in flow_result.results
             )
-        hydrated = iter(self.hydrate_all(values))
+        hydrated = iter(self.hydrate_all(request.context.flow_id, values))
         if has_step_input:
             result.step_input.CopyFrom(next(hydrated))
         if has_heartbeat:
@@ -163,7 +174,7 @@ class ValueHydrator:
             for message in channel_values.messages
         ]
         values.extend(message.value for message in channel_messages)
-        hydrated = self.hydrate_all(values)
+        hydrated = self.hydrate_all(request.context.flow_id, values)
         result.input.CopyFrom(hydrated[0])
         hydrated_entries = iter(hydrated[1:])
         for entry in result.attributes:
@@ -179,10 +190,11 @@ class ValueHydrator:
 
     def step_outputs(
         self,
+        flow_id: str,
         outputs: list[pb.StepCompletionOutput],
     ) -> list[pb.StepCompletionOutput]:
         values = [output.completed_step_output for output in outputs]
-        hydrated = self.hydrate_all(values)
+        hydrated = self.hydrate_all(flow_id, values)
         results: list[pb.StepCompletionOutput] = []
         for output, value in zip(outputs, hydrated):
             result = pb.StepCompletionOutput()
@@ -195,7 +207,15 @@ class ValueHydrator:
         if not misses:
             return
         response = self._service.LoadBlobs(
-            pb.LoadBlobsRequest(values=[miss.request for miss in misses])
+            pb.LoadBlobsRequest(
+                entries=[
+                    pb.LoadBlobRequestEntry(
+                        flow_id=miss.flow_id,
+                        blob_value=miss.request,
+                    )
+                    for miss in misses
+                ]
+            )
         )
         for miss in misses:
             concrete = response.values.get(miss.blob_id)
@@ -207,7 +227,7 @@ class ValueHydrator:
 
     def _read_cache(self, blob: _PendingBlob) -> pb.Value | None:
         try:
-            payload = self._cache.get(blob.blob_id)
+            payload = self._cache.get(self._cache_key(blob))
             if payload is None:
                 return None
             if blob.is_object:
@@ -219,7 +239,7 @@ class ValueHydrator:
         except Exception:
             _LOGGER.warning("cannot read cached blob %s", blob.blob_id, exc_info=True)
             try:
-                self._cache.delete(blob.blob_id)
+                self._cache.delete(self._cache_key(blob))
             except Exception:
                 _LOGGER.warning(
                     "cannot delete cached blob %s",
@@ -235,7 +255,7 @@ class ValueHydrator:
                 if blob.is_object
                 else concrete.string_value.encode("utf-8")
             )
-            self._cache.put(blob.blob_id, payload)
+            self._cache.put(self._cache_key(blob), payload)
         except Exception:
             _LOGGER.warning("cannot cache blob %s", blob.blob_id, exc_info=True)
 
@@ -254,6 +274,10 @@ class ValueHydrator:
             return blob_id, True
         return None
 
+    @staticmethod
+    def _cache_key(blob: _PendingBlob) -> str:
+        return f"{len(blob.flow_id)}:{blob.flow_id}{blob.blob_id}"
+
     @staticmethod
     def _validate_hydrated(blob: _PendingBlob, value: pb.Value) -> None:
         expected = "obj_value" if blob.is_object else "string_value"
@@ -275,7 +299,7 @@ class ValueHydrator:
                 raise ValueError("non-finite numbers are unsupported")
             return
         if kind == "obj_value":
-            if value.obj_value.encoding not in ("json", "rawbytes"):
+            if value.obj_value.encoding not in ("json", "raw"):
                 raise ValueError(
                     f"unsupported object encoding {value.obj_value.encoding}"
                 )

{dex_python_sdk-0.7.0 → dex_python_sdk-0.8.0}/dex/_value_mapper.py

@@ -22,7 +22,7 @@ from dex.dexpb import dex_pb2 as pb
 from dex.runtime_errors import ValueMappingError
 
 _JSON_ENCODING = "json"
-_RAW_BYTES_ENCODING = "rawbytes"
+_RAW_BYTES_ENCODING = "raw"
 
 
 class ValueMapper:
@@ -43,10 +43,7 @@ class ValueMapper:
     def _encode(self, value: Any, codec: Codec[Any]) -> pb.Value:
         if value is None:
             return pb.Value(
-                obj_value=pb.EncodedObject(
-                    encoding=_JSON_ENCODING,
-                    payload=b"null",
-                )
+                null_value=cast(struct_pb2.NullValue, struct_pb2.NULL_VALUE)
             )
         logical = codec.encode(value)
         if logical.kind is WireKind.STRING:
@@ -134,7 +131,7 @@ class ValueMapper:
         ):
             raise ValueError("blob-backed Value was not hydrated")
         if kind == "null_value":
-            raise ValueError("attribute deletion marker cannot be decoded")
+            return None
         raise TypeError(f"cannot decode {kind or 'empty Value'} as {codec.type_name}")
 
     def to_value(self, value: pb.Value) -> Value:
@@ -166,6 +163,8 @@ class ValueMapper:
             "internal_blob_id_for_obj_value",
         ):
             raise ValueError("blob-backed Value was not hydrated")
+        if kind == "null_value":
+            return Value(WireKind.JSON, "null")
         raise TypeError(f"cannot wrap {kind or 'empty Value'} as Value")
 
     @staticmethod

{dex_python_sdk-0.7.0 → dex_python_sdk-0.8.0}/dex/async_client.py

@@ -308,7 +308,7 @@ class AsyncClient:
         if rpc.output_codec is None:
             return None
         return self._values.decode(
-            await self._hydrator.hydrate(response.output),
+            await self._hydrator.hydrate(flow_id, response.output),
             rpc.output_codec,
         )
 
@@ -505,7 +505,7 @@ class AsyncClient:
             DexServiceError: If FlowService cannot perform the wait.
         """
         response = await self._wait_for_flow_response(flow_id, timeout)
-        hydrated = await self._hydrator.step_outputs(list(response.results))
+        hydrated = await self._hydrator.step_outputs(flow_id, list(response.results))
         mapped = pb.FlowResult()
         mapped.CopyFrom(response)
         del mapped.results[:]
@@ -625,7 +625,9 @@ class AsyncClient:
         self, entry: pb.SearchFlowsResponseEntry
     ) -> SearchFlowEntry:
         attributes = {
-            kv.key: self._values.to_value(await self._hydrator.hydrate(kv.value))
+            kv.key: self._values.to_value(
+                await self._hydrator.hydrate(entry.flow_id, kv.value)
+            )
             for kv in entry.indexed_attributes
         }
         closed_at = (
@@ -734,6 +736,10 @@ class AsyncClient:
 
         The server derives a stable Request ID from the Step execution when none
         is supplied. Transport long polls automatically reattach to the same wait.
+        Leave the maximum wait time at zero for ordinary infinite waits. A positive
+        value releases per-Flow in-flight Update capacity for abandoned waits.
+        The budget spans Continue-as-New and is distinct from the caller's lifetime.
+        Retrying after expiry creates a new Update generation.
 
         Args:
             flow_id: The non-empty active Flow ID.
@@ -780,6 +786,10 @@ class AsyncClient:
 
         The Client returns the value observed by the successful wait. The server
         derives a stable Request ID from the condition when none is supplied.
+        Leave the maximum wait time at zero for ordinary infinite waits. A positive
+        value releases per-Flow in-flight Update capacity for rarely matching waits.
+        The budget spans transport reattachments and Continue-as-New, and is distinct
+        from the caller's lifetime. Retrying after expiry creates a new Update generation.
         JSON, bytes, and null operands raise ``ValueError`` before transport.
 
         Args:

{dex_python_sdk-0.7.0 → dex_python_sdk-0.8.0}/dex/client.py

@@ -308,7 +308,7 @@ class Client:
         if rpc.output_codec is None:
             return None
         return self._values.decode(
-            self._hydrator.hydrate(response.output),
+            self._hydrator.hydrate(flow_id, response.output),
             rpc.output_codec,
         )
 
@@ -505,7 +505,7 @@ class Client:
             DexServiceError: If FlowService cannot perform the wait.
         """
         response = self._wait_for_flow_response(flow_id, timeout)
-        hydrated = self._hydrator.step_outputs(list(response.results))
+        hydrated = self._hydrator.step_outputs(flow_id, list(response.results))
         mapped = pb.FlowResult()
         mapped.CopyFrom(response)
         del mapped.results[:]
@@ -624,7 +624,9 @@ class Client:
 
     def _map_search_entry(self, entry: pb.SearchFlowsResponseEntry) -> SearchFlowEntry:
         attributes = {
-            kv.key: self._values.to_value(self._hydrator.hydrate(kv.value))
+            kv.key: self._values.to_value(
+                self._hydrator.hydrate(entry.flow_id, kv.value)
+            )
             for kv in entry.indexed_attributes
         }
         closed_at = (
@@ -731,6 +733,10 @@ class Client:
 
         The server derives a stable Request ID from the Step execution when none
         is supplied. Transport long polls automatically reattach to the same wait.
+        Leave the maximum wait time at zero for ordinary infinite waits. A positive
+        value releases per-Flow in-flight Update capacity for abandoned waits.
+        The budget spans Continue-as-New and is distinct from the caller's lifetime.
+        Retrying after expiry creates a new Update generation.
 
         Args:
             flow_id: The non-empty active Flow ID.
@@ -777,6 +783,10 @@ class Client:
 
         The Client returns the value observed by the successful wait. The server
         derives a stable Request ID from the condition when none is supplied.
+        Leave the maximum wait time at zero for ordinary infinite waits. A positive
+        value releases per-Flow in-flight Update capacity for rarely matching waits.
+        The budget spans transport reattachments and Continue-as-New, and is distinct
+        from the caller's lifetime. Retrying after expiry creates a new Update generation.
         JSON, bytes, and null operands raise ``ValueError`` before transport.
 
         Args: