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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dex-python-sdk
-Version: 0.1.2
+Version: 0.1.4
 Requires-Dist: grpcio>=1.83.0
 Requires-Dist: grpcio-status>=1.83.0
 Requires-Dist: protobuf>=7.35.1
@@ -71,7 +71,7 @@ registry = dex.Registry((flow,))
 ```
 
 Registry derives codecs from declared Python types and handler annotations.
-Built-in scalar types and dataclasses need no codec arguments. Register an
+Built-in primitive types and dataclasses need no codec arguments. Register an
 explicit codec only for a custom encoding or a type Registry cannot derive.
 `PersistenceSchema.of(...)` accepts attributes and channels together and
 partitions them by definition type.
@@ -131,10 +131,49 @@ Applications implement two generic interfaces from [`dex`](dex/):
 `StepOptions.wait_for_method_timeout` and `execute_method_timeout` bound the
 two handler calls. Timer and channel conditions determine how long a Step waits.
 
+`wait_for_retry` and `execute_retry` limit one logical handler execution. With
+`StepDurability.ASYNC`, local and fallback regular activities share maximum
+attempts, total duration, and 1-based attempt numbers. Fallback starts
+immediately; later regular retries continue the backoff sequence at the
+cumulative attempt.
+
 `Registry` validates every Flow, Step, RPC signature, durable name, lock, and
 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 singleton and AttributeMap-instance
+overloads of `wait_for_attribute_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.
+
+`Client.wait_for_flow` and `AsyncClient.wait_for_flow` return a
+`WaitForFlowResult` after hydrating every output-bearing completion. Use
+`single_output` only when the Flow contract produces exactly one output:
+
+```python
+output = client.wait_for_flow(flow_id).single_output(OrderResult)
+
+result = client.wait_for_flow(flow_id)
+for completion in result.completions:
+    if completion.step_execution_id == expected_execution_id:
+        output = completion.decode(OrderResult)
+```
+
+`completions` is an immutable tuple in server collection order. Parallel branch
+order is not deterministic, so select by `step_type` or `step_execution_id`.
+No-output Flows return an empty tuple; `single_output` raises `ValueError` for
+zero or multiple completions. `FlowUncompletedError.completions` uses the same
+hydrated model for partial outputs.
+
 ### Errors
 
 Client calls raise concrete `DexServiceError` subclasses. Existing-Flow reads
@@ -185,22 +224,17 @@ implemented. Python owns its gRPC transport; the native bridge is limited to
 the shared BlobCache. Design notes:
 [`docs/design/plan/python-sdk-async-apis.md`](../docs/design/plan/python-sdk-async-apis.md).
 
-## Running dex-server locally
+## Running Dex locally
 
-### Option 1: use docker compose
-See [dex README](https://github.com/superdurable/dex#using-docker-image--docker-compose)
+Install and start the complete local environment with `dexcli`:
 
-### Option 2: VSCode Dev Container
+```bash
+brew install superdurable/tap/dexcli
+dexcli dev
+```
 
-Dev Container is an easy way to get dex-server running locally. Follow these steps to launch a dev container:
-- Install Docker, VSCode, and [VSCode Dev Container plugin](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
-- Open the project in VSCode.
-    ```bash
-    cd dex-python-sdk
-    code .
-    ```
-- Launch the Remote-Containers: Reopen in Container command from Command Palette (Ctrl + Shift + P). You can also click in the bottom left corner to access the remote container menu.
-- Once the dev container starts, dex-server will be listening on port 8801.
+Dex Server listens on `127.0.0.1:8801`. See the
+[CLI README](../cli/README.md) for endpoints and persistence options.
 
 ## How To Contribute
 

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

@@ -55,7 +55,7 @@ registry = dex.Registry((flow,))
 ```
 
 Registry derives codecs from declared Python types and handler annotations.
-Built-in scalar types and dataclasses need no codec arguments. Register an
+Built-in primitive types and dataclasses need no codec arguments. Register an
 explicit codec only for a custom encoding or a type Registry cannot derive.
 `PersistenceSchema.of(...)` accepts attributes and channels together and
 partitions them by definition type.
@@ -115,10 +115,49 @@ Applications implement two generic interfaces from [`dex`](dex/):
 `StepOptions.wait_for_method_timeout` and `execute_method_timeout` bound the
 two handler calls. Timer and channel conditions determine how long a Step waits.
 
+`wait_for_retry` and `execute_retry` limit one logical handler execution. With
+`StepDurability.ASYNC`, local and fallback regular activities share maximum
+attempts, total duration, and 1-based attempt numbers. Fallback starts
+immediately; later regular retries continue the backoff sequence at the
+cumulative attempt.
+
 `Registry` validates every Flow, Step, RPC signature, durable name, lock, and
 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 singleton and AttributeMap-instance
+overloads of `wait_for_attribute_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.
+
+`Client.wait_for_flow` and `AsyncClient.wait_for_flow` return a
+`WaitForFlowResult` after hydrating every output-bearing completion. Use
+`single_output` only when the Flow contract produces exactly one output:
+
+```python
+output = client.wait_for_flow(flow_id).single_output(OrderResult)
+
+result = client.wait_for_flow(flow_id)
+for completion in result.completions:
+    if completion.step_execution_id == expected_execution_id:
+        output = completion.decode(OrderResult)
+```
+
+`completions` is an immutable tuple in server collection order. Parallel branch
+order is not deterministic, so select by `step_type` or `step_execution_id`.
+No-output Flows return an empty tuple; `single_output` raises `ValueError` for
+zero or multiple completions. `FlowUncompletedError.completions` uses the same
+hydrated model for partial outputs.
+
 ### Errors
 
 Client calls raise concrete `DexServiceError` subclasses. Existing-Flow reads
@@ -169,22 +208,17 @@ implemented. Python owns its gRPC transport; the native bridge is limited to
 the shared BlobCache. Design notes:
 [`docs/design/plan/python-sdk-async-apis.md`](../docs/design/plan/python-sdk-async-apis.md).
 
-## Running dex-server locally
+## Running Dex locally
 
-### Option 1: use docker compose
-See [dex README](https://github.com/superdurable/dex#using-docker-image--docker-compose)
+Install and start the complete local environment with `dexcli`:
 
-### Option 2: VSCode Dev Container
+```bash
+brew install superdurable/tap/dexcli
+dexcli dev
+```
 
-Dev Container is an easy way to get dex-server running locally. Follow these steps to launch a dev container:
-- Install Docker, VSCode, and [VSCode Dev Container plugin](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
-- Open the project in VSCode.
-    ```bash
-    cd dex-python-sdk
-    code .
-    ```
-- Launch the Remote-Containers: Reopen in Container command from Command Palette (Ctrl + Shift + P). You can also click in the bottom left corner to access the remote container menu.
-- Once the dev container starts, dex-server will be listening on port 8801.
+Dex Server listens on `127.0.0.1:8801`. See the
+[CLI README](../cli/README.md) for endpoints and persistence options.
 
 ## How To Contribute
 

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

@@ -8,6 +8,8 @@
 # Legacy Materials remain under their original licenses.
 # See LICENSE and LEGACY_NOTICES.md.
 
+from dex.async_client import AsyncClient
+from dex.async_worker import AsyncWorker
 from dex.attribute import (
     Attribute,
     AttributeIndex,
@@ -17,8 +19,6 @@ from dex.attribute import (
 )
 from dex.blob_cache import BlobCache, BlobCacheConfig, open_blob_cache
 from dex.channel import Channel, ChannelMap
-from dex.async_client import AsyncClient
-from dex.async_worker import AsyncWorker
 from dex.client import Client
 from dex.client_options import ClientOptions
 from dex.codec import (
@@ -52,6 +52,7 @@ from dex.flow_options import (
     StopFlowOptions,
     StopType,
 )
+from dex.flow_result import StepCompletion, WaitForFlowResult
 from dex.runtime_errors import (
     DexServiceError,
     ErrorSubStatus,
@@ -78,7 +79,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,
@@ -140,6 +141,7 @@ __all__ = [
     "RetryPolicy",
     "SearchFlowEntry",
     "SearchFlowsPage",
+    "StepCompletion",
     "StartFlowOptions",
     "StepExecutionId",
     "StepDecision",
@@ -156,6 +158,7 @@ __all__ = [
     "ValueMappingError",
     "Wait",
     "WaitForFailurePolicy",
+    "WaitForFlowResult",
     "WireKind",
     "Worker",
     "WorkerInvocationError",
@@ -163,7 +166,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.4}/dex/_grpc_errors.py

@@ -36,12 +36,12 @@ def translate_rpc_error(
     flow_id: str | None,
     requirement: FlowTargetRequirement,
 ) -> DexServiceError:
-    details: pb.ErrorResponse | None = None
+    details: pb.ServiceErrorResponse | None = None
     try:
         status = rpc_status.from_call(cast(grpc.Call, error))
         if status is not None:
             for packed in status.details:
-                candidate = pb.ErrorResponse()
+                candidate = pb.ServiceErrorResponse()
                 if packed.Is(candidate.DESCRIPTOR):
                     packed.Unpack(candidate)
                     details = candidate
@@ -87,7 +87,7 @@ def translate_rpc_error(
     return DexServiceError(*parameters)
 
 
-def _worker_code(details: pb.ErrorResponse | None) -> grpc.StatusCode | None:
+def _worker_code(details: pb.ServiceErrorResponse | None) -> grpc.StatusCode | None:
     if details is None or details.original_worker_error_status == 0:
         return None
     return next(

{dex_python_sdk-0.1.2 → dex_python_sdk-0.1.4}/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.4}/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:
@@ -280,11 +279,19 @@ class WorkerDispatcher:
             mapped.next_steps.extend(self._map_movements(flow, decision.movements))
         elif decision.kind is DecisionKind.GRACEFUL_COMPLETE:
             mapped.close_decision.CopyFrom(
-                self._close(pb.CLOSE_DECISION_TYPE_GRACEFUL_COMPLETE, decision.output)
+                self._close(
+                    pb.CLOSE_DECISION_TYPE_GRACEFUL_COMPLETE,
+                    decision.output,
+                    decision._has_output(),
+                )
             )
         elif decision.kind is DecisionKind.FORCE_COMPLETE:
             mapped.close_decision.CopyFrom(
-                self._close(pb.CLOSE_DECISION_TYPE_FORCE_COMPLETE, decision.output)
+                self._close(
+                    pb.CLOSE_DECISION_TYPE_FORCE_COMPLETE,
+                    decision.output,
+                    decision._has_output(),
+                )
             )
         elif decision.kind is DecisionKind.FORCE_FAIL:
             mapped.close_decision.CopyFrom(
@@ -315,11 +322,16 @@ class WorkerDispatcher:
             raise ValueError("unsupported StepDecision kind")
         return mapped
 
-    def _close(self, close_type: int, output: object) -> pb.CloseDecision:
-        return pb.CloseDecision(
-            close_decision_type=cast(Any, close_type),
-            close_input=self._values.encode_dynamic(output),
-        )
+    def _close(
+        self,
+        close_type: int,
+        output: object,
+        has_output: bool = True,
+    ) -> pb.CloseDecision:
+        close = pb.CloseDecision(close_decision_type=cast(Any, close_type))
+        if has_output:
+            close.close_input.CopyFrom(self._values.encode_dynamic(output))
+        return close
 
     def _map_movements(
         self,
@@ -417,7 +429,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 +438,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():