dex-python-sdk 0.1.2__tar.gz → 0.1.3__tar.gz

{dex_python_sdk-0.1.2 → dex_python_sdk-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dex-python-sdk
-Version: 0.1.2
+Version: 0.1.3
 Requires-Dist: grpcio>=1.83.0
 Requires-Dist: grpcio-status>=1.83.0
 Requires-Dist: protobuf>=7.35.1
@@ -135,6 +135,20 @@ two handler calls. Timer and channel conditions determine how long a Step waits.
 codec before Client or Worker startup. `Client` methods use these typed objects
 instead of raw Flow, Step, or RPC strings.
 
+### Waiting and map inspection
+
+`Wait.all_of` and `Wait.any_of` may use unnamed Conditions. Every Condition in
+`Wait.any_combination_of` must have a non-empty user ID; the same Condition
+instance may appear in multiple combinations.
+
+Both `Client` and `AsyncClient` provide `wait_for_attribute_equal` and
+`wait_for_attribute_map_equal`. They target the current run and accept only
+string, bool, int, or float wire values. JSON objects, bytes, and null fail
+before transport. `AttributeMap.get_map_size/get_all_instance_keys` include
+buffered sets and deletes. The matching `ChannelMap` methods are RPC-only,
+include buffered publishes, and omit empty instances. Keys are decoded and
+sorted. Use `force_complete_if_channels_empty(...)` for conditional completion.
+
 ### Errors
 
 Client calls raise concrete `DexServiceError` subclasses. Existing-Flow reads

{dex_python_sdk-0.1.2 → dex_python_sdk-0.1.3}/README.md

@@ -119,6 +119,20 @@ two handler calls. Timer and channel conditions determine how long a Step waits.
 codec before Client or Worker startup. `Client` methods use these typed objects
 instead of raw Flow, Step, or RPC strings.
 
+### Waiting and map inspection
+
+`Wait.all_of` and `Wait.any_of` may use unnamed Conditions. Every Condition in
+`Wait.any_combination_of` must have a non-empty user ID; the same Condition
+instance may appear in multiple combinations.
+
+Both `Client` and `AsyncClient` provide `wait_for_attribute_equal` and
+`wait_for_attribute_map_equal`. They target the current run and accept only
+string, bool, int, or float wire values. JSON objects, bytes, and null fail
+before transport. `AttributeMap.get_map_size/get_all_instance_keys` include
+buffered sets and deletes. The matching `ChannelMap` methods are RPC-only,
+include buffered publishes, and omit empty instances. Keys are decoded and
+sorted. Use `force_complete_if_channels_empty(...)` for conditional completion.
+
 ### Errors
 
 Client calls raise concrete `DexServiceError` subclasses. Existing-Flow reads

{dex_python_sdk-0.1.2 → dex_python_sdk-0.1.3}/dex/__init__.py

@@ -78,7 +78,7 @@ from dex.step import (
     WaitForFailurePolicy,
     dead_end,
     force_complete,
-    force_complete_when_channels_empty,
+    force_complete_if_channels_empty,
     force_fail,
     go_to,
     go_to_multi,
@@ -163,7 +163,7 @@ __all__ = [
     "WorkerTarget",
     "dead_end",
     "force_complete",
-    "force_complete_when_channels_empty",
+    "force_complete_if_channels_empty",
     "force_fail",
     "graceful_complete",
     "go_to",

{dex_python_sdk-0.1.2 → dex_python_sdk-0.1.3}/dex/_invocation_context.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 from enum import Enum
 from typing import Any, Sequence, TypeVar, cast
+from urllib.parse import unquote
 
 from dex._utils import require_name
 from dex._value_mapper import ValueMapper
@@ -204,6 +205,38 @@ class InvocationContext:
                 size=(current.size if current is not None else 0) + 1
             )
 
+    def _attribute_map_keys(
+        self,
+        definition: AttributeMap[object],
+    ) -> tuple[str, ...]:
+        self._require_registered(definition)
+        prefix = f"{definition.name}/"
+        physical_keys = {key for key in self._attributes if key.startswith(prefix)}
+        for key, write in self.attribute_writes.items():
+            if not key.startswith(prefix):
+                continue
+            if write.value.WhichOneof("kind") == "null_value":
+                physical_keys.discard(key)
+            else:
+                physical_keys.add(key)
+        return tuple(sorted(unquote(key[len(prefix) :]) for key in physical_keys))
+
+    def _channel_map_keys(
+        self,
+        definition: ChannelMap[object],
+    ) -> tuple[str, ...]:
+        self._require_registered(definition)
+        if self._method is not InvocationMethod.RPC:
+            raise ValueError("ChannelMap introspection requires an RPC invocation")
+        prefix = f"{definition.name}/"
+        return tuple(
+            sorted(
+                unquote(key[len(prefix) :])
+                for key, info in self._channel_infos.items()
+                if key.startswith(prefix) and info.size > 0
+            )
+        )
+
     def _channel_size(
         self,
         definition: Channel[object] | ChannelMap[object],

{dex_python_sdk-0.1.2 → dex_python_sdk-0.1.3}/dex/_worker_dispatcher.py

@@ -32,8 +32,6 @@ from dex.step import (
 )
 from dex.wait import Wait, WaitKind
 
-_INTERNAL_CONDITION_PREFIX = "__dex_internal_condition_"
-
 
 class WorkerDispatcher:
     def __init__(
@@ -259,7 +257,8 @@ class WorkerDispatcher:
             for combination in wait.combinations:
                 waiting.condition_combinations.add(
                     condition_ids=[
-                        mapper.add(condition) for condition in combination.conditions
+                        mapper.add(condition, id_required=True)
+                        for condition in combination.conditions
                     ]
                 )
         else:
@@ -417,7 +416,6 @@ class _ConditionMapper:
         self._flow = flow
         self._ids: dict[int, str] = {}
         self._used: set[str] = set()
-        self._next_id = 0
         self.timers: list[pb.TimerCondition] = []
         self.channels: list[pb.ChannelCondition] = []
 
@@ -427,18 +425,22 @@ class _ConditionMapper:
         for condition in conditions:
             self.add(condition)
 
-    def add(self, condition: Condition) -> str:
+    def add(self, condition: Condition, *, id_required: bool = False) -> str:
         identity = id(condition)
         existing = self._ids.get(identity)
         if existing is not None:
             return existing
-        condition_id = condition.condition_id
-        if condition_id is None:
-            condition_id = f"{_INTERNAL_CONDITION_PREFIX}{self._next_id}"
-            self._next_id += 1
-        if not condition_id or condition_id in self._used:
-            raise ValueError("duplicate or empty Condition ID")
-        self._used.add(condition_id)
+        condition_id = condition.condition_id or ""
+        if id_required and not condition_id:
+            raise ValueError(
+                "any_combination_of requires every Condition to have an ID"
+            )
+        if condition.condition_id is not None and not condition_id:
+            raise ValueError("empty Condition ID")
+        if condition_id and condition_id in self._used:
+            raise ValueError("duplicate Condition ID")
+        if condition_id:
+            self._used.add(condition_id)
         if isinstance(condition, TimerCondition):
             seconds = condition.duration.total_seconds()
             if not seconds.is_integer():

{dex_python_sdk-0.1.2 → dex_python_sdk-0.1.3}/dex/async_client.py

@@ -787,6 +787,102 @@ class AsyncClient:
             "active",
         )
 
+    async def wait_for_attribute_equal(
+        self,
+        flow_id: str,
+        attribute: Attribute[ValueT],
+        expected: ValueT,
+        timeout: timedelta,
+    ) -> None:
+        """Await a scalar Attribute in the current run equaling ``expected``.
+
+        The Client generates a request ID. JSON, bytes, and null values raise
+        ``ValueError`` before transport. A remote expiry raises
+        ``LongPollTimeoutError``.
+
+        Args:
+            flow_id: The non-empty active Flow ID.
+            attribute: The registered scalar Attribute to observe.
+            expected: The string, bool, int, or float value to await.
+            timeout: The non-negative server-side wait duration.
+
+        Raises:
+            ValueError: If an identifier, timeout, or expected value is invalid.
+            LongPollTimeoutError: If equality is not observed before ``timeout``.
+            FlowNotActiveError: If the Flow closes first.
+            DexServiceError: If FlowService cannot perform the wait.
+        """
+        await self._wait_for_attribute_equal(
+            flow_id, attribute, None, expected, timeout
+        )
+
+    async def wait_for_attribute_map_equal(
+        self,
+        flow_id: str,
+        attribute: AttributeMap[ValueT],
+        instance: str,
+        expected: ValueT,
+        timeout: timedelta,
+    ) -> None:
+        """Await one scalar AttributeMap instance in the current run.
+
+        Scalar restrictions, request-ID generation, timeout behavior, and
+        service errors match :meth:`wait_for_attribute_equal`.
+
+        Args:
+            flow_id: The non-empty active Flow ID.
+            attribute: The registered AttributeMap to observe.
+            instance: The non-empty logical map key to observe.
+            expected: The string, bool, int, or float value to await.
+            timeout: The non-negative server-side wait duration.
+
+        Raises:
+            ValueError: If an identifier, timeout, or expected value is invalid.
+            LongPollTimeoutError: If equality is not observed before ``timeout``.
+            FlowNotActiveError: If the Flow closes first.
+            DexServiceError: If FlowService cannot perform the wait.
+        """
+        await self._wait_for_attribute_equal(
+            flow_id, attribute, instance, expected, timeout
+        )
+
+    async def _wait_for_attribute_equal(
+        self,
+        flow_id: str,
+        attribute: Attribute[Any] | AttributeMap[Any],
+        instance: str | None,
+        expected: object,
+        timeout: timedelta,
+    ) -> None:
+        encoded = self._values.encode(
+            expected,
+            self._values.codec(attribute.value_type),
+        )
+        if encoded.WhichOneof("kind") not in {
+            "string_value",
+            "bool_value",
+            "int_value",
+            "double_value",
+        }:
+            raise ValueError("wait_for_attribute_equal supports only scalar values")
+        await self._call(
+            self._service.WaitForAttribute,
+            pb.WaitForAttributeRequest(
+                flow_id=require_name(flow_id),
+                condition=pb.WaitForAttributeCondition(
+                    equal=pb.WaitForAttributeEqual(
+                        key=self._definition_name(attribute, instance),
+                        value=encoded,
+                    )
+                ),
+                wait_time_seconds=self._seconds32(timeout),
+                request_id=str(uuid4()),
+            ),
+            "wait_for_attribute_equal",
+            flow_id,
+            "active",
+        )
+
     async def update_flow_config(self, flow_id: str, config: FlowConfig) -> None:
         """Replace mutable configuration for an active Flow.
 

{dex_python_sdk-0.1.2 → dex_python_sdk-0.1.3}/dex/async_worker.py

@@ -135,13 +135,13 @@ class AsyncWorker:
             )
         except grpc.RpcError as failure:
             self._state = "stopped"
-            await self._flow_channel.close()
+            await self._flow_channel.close(None)
             self._stopped.set()
             raise RuntimeError("cannot synchronize Attribute indexes") from failure
         self._bound_port = self._server.add_insecure_port(self.options.bind_address)
         if self._bound_port == 0:
             self._state = "stopped"
-            await self._flow_channel.close()
+            await self._flow_channel.close(None)
             self._stopped.set()
             raise RuntimeError(
                 f"cannot bind Python AsyncWorker to {self.options.bind_address}"
@@ -164,7 +164,7 @@ class AsyncWorker:
             return
         self._state = "stopping"
         await self._server.stop(grace=5)
-        await self._flow_channel.close()
+        await self._flow_channel.close(None)
         if self._state != "closed":
             self._state = "stopped"
         self._stopped.set()

{dex_python_sdk-0.1.2 → dex_python_sdk-0.1.3}/dex/attribute.py

@@ -206,6 +206,28 @@ class AttributeMap(Generic[ValueT]):
         """
         context._delete_attribute(cast(AttributeMap[object], self), instance)
 
+    def get_map_size(self, context: Context) -> int:
+        """Return the number of existing instances, including buffered writes.
+
+        Args:
+            context: The current Step or RPC Context.
+
+        Returns:
+            The number of keys visible after decision-local writes and deletions.
+        """
+        return len(self.get_all_instance_keys(context))
+
+    def get_all_instance_keys(self, context: Context) -> tuple[str, ...]:
+        """Return decoded existing instance keys in ascending order.
+
+        Args:
+            context: The current Step or RPC Context.
+
+        Returns:
+            An immutable tuple reflecting decision-local writes and deletions.
+        """
+        return context._attribute_map_keys(cast(AttributeMap[object], self))
+
     def lock(self, instance: str) -> AttributeLock:
         """Return a lock request for one map instance.
 

{dex_python_sdk-0.1.2 → dex_python_sdk-0.1.3}/dex/channel.py

@@ -210,6 +210,28 @@ class ChannelMap(Generic[ValueT]):
         """
         return context._channel_size(cast(ChannelMap[object], self), instance)
 
+    def get_map_size(self, context: Context) -> int:
+        """Return the number of non-empty instances visible to the current RPC.
+
+        Args:
+            context: The current RPC Context.
+
+        Returns:
+            The number of keys after including publications buffered by this RPC.
+        """
+        return len(self.get_all_instance_keys(context))
+
+    def get_all_instance_keys(self, context: Context) -> tuple[str, ...]:
+        """Return decoded non-empty instance keys in ascending order.
+
+        Args:
+            context: The current RPC Context.
+
+        Returns:
+            An immutable tuple including publications buffered by this RPC.
+        """
+        return context._channel_map_keys(cast(ChannelMap[object], self))
+
     def results(self, context: Context, instance: str) -> Sequence[ValueT]:
         """Return values selected for one instance by the satisfied condition.
 

{dex_python_sdk-0.1.2 → dex_python_sdk-0.1.3}/dex/client.py

@@ -786,6 +786,99 @@ class Client:
             "active",
         )
 
+    def wait_for_attribute_equal(
+        self,
+        flow_id: str,
+        attribute: Attribute[ValueT],
+        expected: ValueT,
+        timeout: timedelta,
+    ) -> None:
+        """Wait for a scalar Attribute in the current run to equal ``expected``.
+
+        The Client generates a request ID and blocks for ``timeout``. JSON,
+        bytes, and null values raise ``ValueError`` before transport. A remote
+        expiry raises ``LongPollTimeoutError``.
+
+        Args:
+            flow_id: The non-empty active Flow ID.
+            attribute: The registered scalar Attribute to observe.
+            expected: The string, bool, int, or float value to await.
+            timeout: The non-negative server-side wait duration.
+
+        Raises:
+            ValueError: If an identifier, timeout, or expected value is invalid.
+            LongPollTimeoutError: If equality is not observed before ``timeout``.
+            FlowNotActiveError: If the Flow closes first.
+            DexServiceError: If FlowService cannot perform the wait.
+        """
+        self._wait_for_attribute_equal(flow_id, attribute, None, expected, timeout)
+
+    def wait_for_attribute_map_equal(
+        self,
+        flow_id: str,
+        attribute: AttributeMap[ValueT],
+        instance: str,
+        expected: ValueT,
+        timeout: timedelta,
+    ) -> None:
+        """Wait for one scalar AttributeMap instance in the current run.
+
+        ``instance`` is encoded as a map key. Scalar restrictions, request-ID
+        generation, timeout behavior, and service errors match
+        :meth:`wait_for_attribute_equal`.
+
+        Args:
+            flow_id: The non-empty active Flow ID.
+            attribute: The registered AttributeMap to observe.
+            instance: The non-empty logical map key to observe.
+            expected: The string, bool, int, or float value to await.
+            timeout: The non-negative server-side wait duration.
+
+        Raises:
+            ValueError: If an identifier, timeout, or expected value is invalid.
+            LongPollTimeoutError: If equality is not observed before ``timeout``.
+            FlowNotActiveError: If the Flow closes first.
+            DexServiceError: If FlowService cannot perform the wait.
+        """
+        self._wait_for_attribute_equal(flow_id, attribute, instance, expected, timeout)
+
+    def _wait_for_attribute_equal(
+        self,
+        flow_id: str,
+        attribute: Attribute[Any] | AttributeMap[Any],
+        instance: str | None,
+        expected: object,
+        timeout: timedelta,
+    ) -> None:
+        encoded = self._values.encode(
+            expected,
+            self._values.codec(attribute.value_type),
+        )
+        if encoded.WhichOneof("kind") not in {
+            "string_value",
+            "bool_value",
+            "int_value",
+            "double_value",
+        }:
+            raise ValueError("wait_for_attribute_equal supports only scalar values")
+        self._call(
+            self._service.WaitForAttribute,
+            pb.WaitForAttributeRequest(
+                flow_id=require_name(flow_id),
+                condition=pb.WaitForAttributeCondition(
+                    equal=pb.WaitForAttributeEqual(
+                        key=self._definition_name(attribute, instance),
+                        value=encoded,
+                    )
+                ),
+                wait_time_seconds=self._seconds32(timeout),
+                request_id=str(uuid4()),
+            ),
+            "wait_for_attribute_equal",
+            flow_id,
+            "active",
+        )
+
     def update_flow_config(self, flow_id: str, config: FlowConfig) -> None:
         """Replace mutable configuration for an active Flow.
 

{dex_python_sdk-0.1.2 → dex_python_sdk-0.1.3}/dex/context.py

@@ -149,6 +149,11 @@ class Context(Protocol):
         instance: str | None,
     ) -> None: ...
 
+    def _attribute_map_keys(
+        self,
+        definition: AttributeMap[object],
+    ) -> tuple[str, ...]: ...
+
     def _publish_channel(
         self,
         definition: Channel[ValueT] | ChannelMap[ValueT],
@@ -167,3 +172,8 @@ class Context(Protocol):
         definition: Channel[ValueT] | ChannelMap[ValueT],
         instance: str | None,
     ) -> Sequence[ValueT]: ...
+
+    def _channel_map_keys(
+        self,
+        definition: ChannelMap[object],
+    ) -> tuple[str, ...]: ...

{dex_python_sdk-0.1.2 → dex_python_sdk-0.1.3}/dex/step.py

@@ -383,7 +383,7 @@ def force_complete(output: object | None = None) -> StepDecision:
     return StepDecision(DecisionKind.FORCE_COMPLETE, output=output)
 
 
-def force_complete_when_channels_empty(
+def force_complete_if_channels_empty(
     output: object,
     fallback: StepMovement[Any],
     *channels: Channel[Any] | ChannelMap[Any],

{dex_python_sdk-0.1.2 → dex_python_sdk-0.1.3}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "dex-python-sdk"
 # Publish uses tag sdk-python/v*; CI stamps this for release builds.
-version = "0.1.2"
+version = "0.1.3"
 description = "Python SDK for the Dex workflow engine"
 authors = [{name = "Super Durable"}]
 readme = "README.md"