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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dex-python-sdk
-Version: 0.1.3
+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,6 +131,12 @@ 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.
@@ -141,14 +147,33 @@ instead of raw Flow, Step, or RPC strings.
 `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
+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
@@ -199,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.3 → 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,6 +115,12 @@ 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.
@@ -125,14 +131,33 @@ instead of raw Flow, Step, or RPC strings.
 `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
+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
@@ -183,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.3 → 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,
@@ -140,6 +141,7 @@ __all__ = [
     "RetryPolicy",
     "SearchFlowEntry",
     "SearchFlowsPage",
+    "StepCompletion",
     "StartFlowOptions",
     "StepExecutionId",
     "StepDecision",
@@ -156,6 +158,7 @@ __all__ = [
     "ValueMappingError",
     "Wait",
     "WaitForFailurePolicy",
+    "WaitForFlowResult",
     "WireKind",
     "Worker",
     "WorkerInvocationError",

{dex_python_sdk-0.1.3 → 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.3 → dex_python_sdk-0.1.4}/dex/_worker_dispatcher.py

@@ -279,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(
@@ -314,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,

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

@@ -40,10 +40,8 @@ from dex.flow_options import (
     StopFlowOptions,
     StopType,
 )
-from dex.runtime_errors import (
-    FlowErrorType,
-    FlowUncompletedError,
-)
+from dex.flow_result import StepCompletion, WaitForFlowResult
+from dex.runtime_errors import FlowErrorType, FlowUncompletedError
 from dex.step import RetryPolicy, StepDurability
 from dex.step_execution import StepExecutionId, TimerId
 
@@ -67,7 +65,7 @@ class AsyncClient:
     Examples:
         >>> async with AsyncClient(registry, cache) as client:
         ...     run_id = await client.start_flow(orders, "order-42", input)
-        ...     result = await client.wait_for_flow("order-42", OrderResult)
+        ...     result = (await client.wait_for_flow("order-42")).single_output(OrderResult)
     """
 
     def __init__(
@@ -500,54 +498,44 @@ class AsyncClient:
             "active",
         )
 
-    @overload
-    async def wait_for_flow(self, flow_id: str) -> None: ...
-
-    @overload
-    async def wait_for_flow(
-        self,
-        flow_id: str,
-        output_type: type[OutputT],
-        timeout: timedelta | None = None,
-    ) -> OutputT: ...
-
     async def wait_for_flow(
         self,
         flow_id: str,
-        output_type: type[Any] | None = None,
         timeout: timedelta | None = None,
-    ) -> Any:
-        """Await Flow closure and optionally decode its latest Step output.
+    ) -> WaitForFlowResult:
+        """Await Flow closure and return all output-bearing completions.
 
         ``timeout`` is a server-side long-poll duration, not a local task deadline.
-        A LongPollTimeoutError is retryable by awaiting this method again.
+        A LongPollTimeoutError is retryable by awaiting this method again. Parallel
+        completion order is not deterministic; select results by Step identity.
 
         Args:
             flow_id: The non-empty target Flow ID.
-            output_type: Optional Python type for the latest completed Step output.
             timeout: Optional non-negative server-side wait duration.
 
         Returns:
-            The decoded latest output, or ``None`` when no output type/value exists.
+            An immutable snapshot of every output-bearing Step completion.
 
         Raises:
             LongPollTimeoutError: If the Flow remains open when the wait expires.
             FlowUncompletedError: If the Flow closes without successful completion.
             FlowNotFoundError: If ``flow_id`` does not exist.
-            ValueMappingError: If a requested output cannot be decoded.
+            ValueMappingError: If Dex returns a malformed or incompatible hydrated value.
             DexServiceError: If FlowService cannot perform the wait.
         """
         response = await self._wait_for_flow_response(flow_id, timeout)
-        if output_type is None:
-            return None
-        codec = self._values.codec(output_type)
-        for result in reversed(response.results):
-            if result.HasField("completed_step_output"):
-                return self._values.decode(
-                    await self._hydrator.hydrate(result.completed_step_output),
-                    codec,
+        hydrated = await self._hydrator.step_outputs(list(response.results))
+        return WaitForFlowResult(
+            [
+                StepCompletion(
+                    result,
+                    lambda value, output_type: self._values.decode(
+                        value, self._values.codec(output_type)
+                    ),
                 )
-        return None
+                for result in hydrated
+            ]
+        )
 
     async def stop_flow(
         self,
@@ -700,8 +688,7 @@ class AsyncClient:
                 ResetType.STEP_EXECUTION_ID: pb.FLOW_RESET_TYPE_STEP_EXECUTION_ID,
             }[options.type],
             reason=options.reason or "",
-            skip_channel_messages_reapply=options.skip_channel_messages_reapply,
-            skip_locking_rpc_reapply=options.skip_locking_rpc_reapply,
+            skip_writes_reapply=options.skip_writes_reapply,
         )
         if options.history_event_id is not None:
             request.history_event_id = options.history_event_id
@@ -787,6 +774,7 @@ class AsyncClient:
             "active",
         )
 
+    @overload
     async def wait_for_attribute_equal(
         self,
         flow_id: str,
@@ -794,7 +782,7 @@ class AsyncClient:
         expected: ValueT,
         timeout: timedelta,
     ) -> None:
-        """Await a scalar Attribute in the current run equaling ``expected``.
+        """Await a singleton 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
@@ -802,7 +790,7 @@ class AsyncClient:
 
         Args:
             flow_id: The non-empty active Flow ID.
-            attribute: The registered scalar Attribute to observe.
+            attribute: The registered singleton Attribute to observe.
             expected: The string, bool, int, or float value to await.
             timeout: The non-negative server-side wait duration.
 
@@ -812,11 +800,10 @@ class AsyncClient:
             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(
+    @overload
+    async def wait_for_attribute_equal(
         self,
         flow_id: str,
         attribute: AttributeMap[ValueT],
@@ -824,9 +811,9 @@ class AsyncClient:
         expected: ValueT,
         timeout: timedelta,
     ) -> None:
-        """Await one scalar AttributeMap instance in the current run.
+        """Await one AttributeMap instance in the current run.
 
-        Scalar restrictions, request-ID generation, timeout behavior, and
+        Primitive-value restrictions, request-ID generation, timeout behavior, and
         service errors match :meth:`wait_for_attribute_equal`.
 
         Args:
@@ -842,6 +829,36 @@ class AsyncClient:
             FlowNotActiveError: If the Flow closes first.
             DexServiceError: If FlowService cannot perform the wait.
         """
+        ...
+
+    async def wait_for_attribute_equal(
+        self,
+        flow_id: str,
+        attribute: Attribute[Any] | AttributeMap[Any],
+        *args: object,
+        **kwargs: object,
+    ) -> None:
+        """Await a singleton Attribute or AttributeMap instance equaling a value.
+
+        Singleton form is ``wait_for_attribute_equal(flow_id, attribute, expected,
+        timeout)``; map form adds ``instance`` before ``expected``.
+
+        Args:
+            flow_id: The non-empty active Flow ID.
+            attribute: The registered Attribute or AttributeMap to observe.
+            *args: Positional expected value and timeout, optionally preceded by a map instance.
+            **kwargs: The same arguments supplied by name.
+
+        Raises:
+            TypeError: If arguments do not match the Attribute definition.
+            ValueError: If an identifier, timeout, or expected value is invalid.
+            LongPollTimeoutError: If equality is not observed before the timeout.
+            FlowNotActiveError: If the Flow closes first.
+            DexServiceError: If FlowService cannot perform the wait.
+        """
+        instance, expected, timeout = self._attribute_wait_arguments(
+            attribute, args, kwargs
+        )
         await self._wait_for_attribute_equal(
             flow_id, attribute, instance, expected, timeout
         )
@@ -864,7 +881,9 @@ class AsyncClient:
             "int_value",
             "double_value",
         }:
-            raise ValueError("wait_for_attribute_equal supports only scalar values")
+            raise ValueError(
+                "wait_for_attribute_equal supports only string, boolean, or number values"
+            )
         await self._call(
             self._service.WaitForAttribute,
             pb.WaitForAttributeRequest(
@@ -981,13 +1000,21 @@ class AsyncClient:
         if response.flow_status != pb.FLOW_STATUS_COMPLETED:
             info = await self.describe_flow(flow_id)
             results = await self._hydrator.step_outputs(list(response.results))
+            completions = [
+                StepCompletion(
+                    result,
+                    lambda value, output_type: self._values.decode(
+                        value, self._values.codec(output_type)
+                    ),
+                )
+                for result in results
+            ]
             raise FlowUncompletedError(
                 info.run_id,
                 self._map_flow_status(response.flow_status),
                 self._map_flow_error_type(response.error_type),
                 response.error_message or None,
-                results,
-                self._values,
+                completions,
             )
         return response
 
@@ -1126,6 +1153,38 @@ class AsyncClient:
             return args[0], args[1]
         raise TypeError("set_attribute received invalid arguments")
 
+    @staticmethod
+    def _attribute_wait_arguments(
+        definition: Attribute[Any] | AttributeMap[Any],
+        args: tuple[object, ...],
+        kwargs: dict[str, object],
+    ) -> tuple[str | None, object, timedelta]:
+        parameter_names: tuple[str, ...]
+        if isinstance(definition, Attribute):
+            parameter_names = ("expected", "timeout")
+        elif isinstance(definition, AttributeMap):
+            parameter_names = ("instance", "expected", "timeout")
+        else:
+            raise TypeError("wait_for_attribute_equal received invalid arguments")
+        if len(args) > len(parameter_names):
+            raise TypeError("wait_for_attribute_equal received invalid arguments")
+        arguments = dict(zip(parameter_names, args))
+        for name, value in kwargs.items():
+            if name not in parameter_names or name in arguments:
+                raise TypeError("wait_for_attribute_equal received invalid arguments")
+            arguments[name] = value
+        if set(arguments) != set(parameter_names):
+            raise TypeError("wait_for_attribute_equal received invalid arguments")
+        timeout = arguments["timeout"]
+        if not isinstance(timeout, timedelta):
+            raise TypeError("wait_for_attribute_equal received invalid arguments")
+        if isinstance(definition, Attribute):
+            return None, arguments["expected"], timeout
+        instance = arguments["instance"]
+        if not isinstance(instance, str):
+            raise TypeError("wait_for_attribute_equal received invalid arguments")
+        return instance, arguments["expected"], timeout
+
     @staticmethod
     def _seconds32(duration: timedelta) -> int:
         seconds = duration.total_seconds()