dex-python-sdk 0.2.11__tar.gz → 0.3.2__tar.gz

{dex_python_sdk-0.2.11 → dex_python_sdk-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dex-python-sdk
-Version: 0.2.11
+Version: 0.3.2
 Requires-Dist: grpcio>=1.83.0
 Requires-Dist: grpcio-status>=1.83.0
 Requires-Dist: protobuf>=7.35.1
@@ -59,6 +59,29 @@ atomic commit and Channel deletion validation. Attribute locks add isolation
 only among cooperating Steps and RPCs using the same lock. Write-only publish
 and delete operations do not require loading.
 
+## Step and timeout-handler state loading
+
+`StepOptions` provides the same five selections independently for `wait_for` and
+`execute`: all AttributeMap instances, exact AttributeMap instances, Channels,
+all ChannelMap instances, and exact ChannelMap instances. The methods receive
+independent snapshots. Execute reads after the winning Wait consumes messages;
+retries of one logical method call reuse its first snapshot.
+
+`FlowTimeoutHandlerOptions` provides Execute-style timeouts, heartbeat detection,
+retry, durability, Attribute locks, and the same state selections. Set it on
+`StartFlowOptions` or `SubFlowOptions` only for a positive timeout using `HANDLER`.
+Exhausted retries may proceed to a registered `Step[None]`; read the final
+failure from `Context.recovery_error`.
+
+```python
+class TimeoutRecoveryStep(Step[None]):
+    def execute(self, context: Context, input: None) -> StepDecision:
+        failure = context.recovery_error
+        if failure is None:
+            return force_fail("timeout recovery has no failure")
+        return force_fail(failure.detail)
+```
+
 Python SDK for [Dex workflow engine](https://github.com/superdurable/dex)
 
 ## New user contracts

{dex_python_sdk-0.2.11 → dex_python_sdk-0.3.2}/README.md

@@ -43,6 +43,29 @@ atomic commit and Channel deletion validation. Attribute locks add isolation
 only among cooperating Steps and RPCs using the same lock. Write-only publish
 and delete operations do not require loading.
 
+## Step and timeout-handler state loading
+
+`StepOptions` provides the same five selections independently for `wait_for` and
+`execute`: all AttributeMap instances, exact AttributeMap instances, Channels,
+all ChannelMap instances, and exact ChannelMap instances. The methods receive
+independent snapshots. Execute reads after the winning Wait consumes messages;
+retries of one logical method call reuse its first snapshot.
+
+`FlowTimeoutHandlerOptions` provides Execute-style timeouts, heartbeat detection,
+retry, durability, Attribute locks, and the same state selections. Set it on
+`StartFlowOptions` or `SubFlowOptions` only for a positive timeout using `HANDLER`.
+Exhausted retries may proceed to a registered `Step[None]`; read the final
+failure from `Context.recovery_error`.
+
+```python
+class TimeoutRecoveryStep(Step[None]):
+    def execute(self, context: Context, input: None) -> StepDecision:
+        failure = context.recovery_error
+        if failure is None:
+            return force_fail("timeout recovery has no failure")
+        return force_fail(failure.detail)
+```
+
 Python SDK for [Dex workflow engine](https://github.com/superdurable/dex)
 
 ## New user contracts

{dex_python_sdk-0.2.11 → dex_python_sdk-0.3.2}/dex/__init__.py

@@ -36,7 +36,7 @@ from dex.codec import (
     WireKind,
 )
 from dex.condition import ConditionCombination
-from dex.context import AsyncContext, Context
+from dex.context import AsyncContext, Context, RecoveryErrorInfo
 from dex.flow import Flow, PersistenceSchema, Registry, RPCResult, rpc
 from dex.flow_config import ActiveStepSearchMode, FlowConfig
 from dex.flow_info import (
@@ -47,6 +47,7 @@ from dex.flow_info import (
     SearchFlowsPage,
 )
 from dex.flow_options import (
+    FlowTimeoutHandlerOptions,
     FlowTimeoutPolicy,
     IdReusePolicy,
     StartFlowOptions,
@@ -152,6 +153,7 @@ __all__ = [
     "FlowNotActiveError",
     "FlowNotFoundError",
     "FlowStatus",
+    "FlowTimeoutHandlerOptions",
     "FlowTimeoutPolicy",
     "HealthInfo",
     "IdReusePolicy",
@@ -161,6 +163,7 @@ __all__ = [
     "LongPollTimeoutError",
     "PersistenceSchema",
     "RPCResult",
+    "RecoveryErrorInfo",
     "RetryAfterError",
     "RpcLockConflictError",
     "Registry",

{dex_python_sdk-0.2.11 → dex_python_sdk-0.3.2}/dex/_async_value_hydrator.py

@@ -80,12 +80,25 @@ class AsyncValueHydrator:
         if has_heartbeat:
             values.append(request.context.last_heartbeat_value)
         values.extend(entry.value for entry in request.attributes)
+        channel_messages = [
+            message
+            for channel_values in request.loaded_channel_messages.values()
+            for message in channel_values.messages
+        ]
+        values.extend(message.value for message in channel_messages)
         hydrated = iter(await self.hydrate_all(values))
         result.step_input.CopyFrom(next(hydrated))
         if has_heartbeat:
             result.context.last_heartbeat_value.CopyFrom(next(hydrated))
-        for entry, value in zip(result.attributes, hydrated):
-            entry.value.CopyFrom(value)
+        for entry in result.attributes:
+            entry.value.CopyFrom(next(hydrated))
+        result_messages = [
+            message
+            for channel_values in result.loaded_channel_messages.values()
+            for message in channel_values.messages
+        ]
+        for message in result_messages:
+            message.value.CopyFrom(next(hydrated))
         return result
 
     async def execute_request(
@@ -101,6 +114,12 @@ class AsyncValueHydrator:
             values.append(request.context.last_heartbeat_value)
         values.extend(entry.value for entry in request.attributes)
         values.extend(entry.value for entry in request.step_exe_locals)
+        channel_messages = [
+            message
+            for channel_values in request.loaded_channel_messages.values()
+            for message in channel_values.messages
+        ]
+        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))
@@ -112,6 +131,13 @@ class AsyncValueHydrator:
             entry.value.CopyFrom(next(hydrated))
         for entry in result.step_exe_locals:
             entry.value.CopyFrom(next(hydrated))
+        result_messages = [
+            message
+            for channel_values in result.loaded_channel_messages.values()
+            for message in channel_values.messages
+        ]
+        for message in result_messages:
+            message.value.CopyFrom(next(hydrated))
         for channel_result in result.condition_results.channel_results:
             for value in channel_result.values:
                 value.CopyFrom(next(hydrated))

{dex_python_sdk-0.2.11 → dex_python_sdk-0.3.2}/dex/_async_worker_dispatcher.py

@@ -100,6 +100,11 @@ class AsyncWorkerDispatcher(WorkerDispatcher):
             request.context,
             self._values,
             request.attributes,
+            channel_infos=dict(request.channel_infos),
+            loaded_channel_messages=dict(request.loaded_channel_messages),
+            loaded_attribute_map_instances=request.loaded_attribute_map_instances,
+            loaded_channel_names=request.loaded_channel_names,
+            loaded_channel_map_instances=request.loaded_channel_map_instances,
             is_active=is_active,
             output_emitter=emitter,
         )
@@ -126,6 +131,7 @@ class AsyncWorkerDispatcher(WorkerDispatcher):
                 upsert_step_exe_locals=list(context.local_writes.values()),
                 record_events=context.events,
                 publish_to_channel=context.publications,
+                delete_from_channel=context.channel_deletions,
             )
             waiting = self._map_wait(flow, wait)
             if waiting is not None:
@@ -153,8 +159,16 @@ class AsyncWorkerDispatcher(WorkerDispatcher):
         is_active: Callable[[], bool] | None = None,
     ) -> AsyncGenerator[pb.InvokeExecuteMethodOutput, None]:
         if original.step_type == _TIMEOUT_HANDLER_STEP_TYPE:
-            response = await self._invoke_timeout_handler_async(original)
-            yield pb.InvokeExecuteMethodOutput(result=response)
+            emitter = _AsyncStepOutputEmitter()
+            handler = asyncio.create_task(
+                self._invoke_timeout_handler_async(original, emitter, is_active)
+            )
+            try:
+                async for output in self._drain_outputs(emitter, handler):
+                    yield self._map_execute_output(output)
+                yield pb.InvokeExecuteMethodOutput(result=await handler)
+            finally:
+                await self._close_invocation(emitter, handler)
             return
         emitter = _AsyncStepOutputEmitter()
         handler = asyncio.create_task(
@@ -187,6 +201,11 @@ class AsyncWorkerDispatcher(WorkerDispatcher):
             request.attributes,
             request.step_exe_locals,
             condition_results,
+            channel_infos=dict(request.channel_infos),
+            loaded_channel_messages=dict(request.loaded_channel_messages),
+            loaded_attribute_map_instances=request.loaded_attribute_map_instances,
+            loaded_channel_names=request.loaded_channel_names,
+            loaded_channel_map_instances=request.loaded_channel_map_instances,
             is_active=is_active,
             output_emitter=emitter,
         )
@@ -214,6 +233,7 @@ class AsyncWorkerDispatcher(WorkerDispatcher):
                 record_events=context.events,
                 upsert_step_exe_locals=list(context.local_writes.values()),
                 publish_to_channel=context.publications,
+                delete_from_channel=context.channel_deletions,
             )
         except InvalidStepResultError as error:
             failure = error
@@ -235,6 +255,8 @@ class AsyncWorkerDispatcher(WorkerDispatcher):
     async def _invoke_timeout_handler_async(
         self,
         original: pb.InvokeExecuteMethodRequest,
+        emitter: _AsyncStepOutputEmitter,
+        is_active: Callable[[], bool] | None,
     ) -> pb.InvokeExecuteMethodResponse:
         request = await self._async_hydrator.execute_request(original)
         flow = self._registry._flow_by_type(request.flow_type)
@@ -260,24 +282,55 @@ class AsyncWorkerDispatcher(WorkerDispatcher):
             request.attributes,
             request.step_exe_locals,
             condition_results,
+            channel_infos=dict(request.channel_infos),
+            loaded_channel_messages=dict(request.loaded_channel_messages),
+            loaded_attribute_map_instances=request.loaded_attribute_map_instances,
+            loaded_channel_names=request.loaded_channel_names,
+            loaded_channel_map_instances=request.loaded_channel_map_instances,
+            is_active=is_active,
+            output_emitter=emitter,
         )
-        decision: Any = flow.flow.handle_timeout(context)
-        if isawaitable(decision):
-            decision = await decision
+        response: pb.InvokeExecuteMethodResponse | None = None
+        failure: BaseException | None = None
+        cause: BaseException | None = None
         try:
+            decision: Any = flow.flow.handle_timeout(context)
+            if isgenerator(decision):
+                decision.close()
+                raise InvalidStepResultError(
+                    flow.name,
+                    _TIMEOUT_HANDLER_STEP_TYPE,
+                    "execute",
+                    "synchronous generators require Worker",
+                )
+            if isawaitable(decision):
+                decision = await decision
             if not isinstance(decision, StepDecision):
                 raise TypeError("handle_timeout must return StepDecision")
-            return pb.InvokeExecuteMethodResponse(
+            response = pb.InvokeExecuteMethodResponse(
                 step_decision=self._map_decision(flow, decision),
                 upsert_attributes=list(context.attribute_writes.values()),
                 record_events=context.events,
                 upsert_step_exe_locals=list(context.local_writes.values()),
                 publish_to_channel=context.publications,
+                delete_from_channel=context.channel_deletions,
             )
+        except InvalidStepResultError as error:
+            failure = error
         except (TypeError, ValueError) as error:
-            raise InvalidStepResultError(
+            failure = InvalidStepResultError(
                 flow.name, _TIMEOUT_HANDLER_STEP_TYPE, "execute", str(error)
-            ) from error
+            )
+            cause = error
+        except BaseException as error:
+            failure = error
+        combined = context._finalize_step_outputs(failure)
+        if combined is not None:
+            if cause is not None:
+                raise combined from cause
+            raise combined
+        assert response is not None
+        return response
 
     async def invoke_rpc(  # type: ignore[override]
         self,

{dex_python_sdk-0.2.11 → dex_python_sdk-0.3.2}/dex/_invocation_context.py

@@ -17,6 +17,7 @@ from dex._value_mapper import ValueMapper
 from dex.attribute import Attribute, AttributeMap, _apply_attribute_store_sync
 from dex.channel import Channel, ChannelMap, ChannelMessage
 from dex.codec import Codec
+from dex.context import RecoveryErrorInfo
 from dex.dexpb import dex_pb2 as pb
 from dex.flow import Registry, _RegisteredFlow
 from dex.flow_result import FlowResult, flow_result_from_proto
@@ -116,6 +117,15 @@ class InvocationContext:
     def from_step_execution_id(self) -> str:
         return self._metadata.from_step_execution_id
 
+    @property
+    def recovery_error(self) -> RecoveryErrorInfo | None:
+        if not self._metadata.HasField("recovery_error"):
+            return None
+        return RecoveryErrorInfo(
+            detail=self._metadata.recovery_error.detail,
+            error_type=self._metadata.recovery_error.error_type,
+        )
+
     @property
     def attempt(self) -> int:
         return self._metadata.attempt
@@ -139,7 +149,12 @@ class InvocationContext:
 
     async def heartbeat(self, value: object = _NO_HEARTBEAT_VALUE) -> None:
         if (
-            self._method not in (InvocationMethod.WAIT_FOR, InvocationMethod.EXECUTE)
+            self._method
+            not in (
+                InvocationMethod.WAIT_FOR,
+                InvocationMethod.EXECUTE,
+                InvocationMethod.TIMEOUT,
+            )
             or self._output_emitter is None
         ):
             raise ValueError("heartbeat requires an asynchronous Step Context")
@@ -226,7 +241,11 @@ class InvocationContext:
         definition: Stream[ValueT],
         value: ValueT,
     ) -> StepOutput | None:
-        if self._method not in (InvocationMethod.WAIT_FOR, InvocationMethod.EXECUTE):
+        if self._method not in (
+            InvocationMethod.WAIT_FOR,
+            InvocationMethod.EXECUTE,
+            InvocationMethod.TIMEOUT,
+        ):
             raise ValueError("Stream writes require a Step Context")
         self._require_registered(definition)
         output = _StreamStepOutput(
@@ -245,7 +264,11 @@ class InvocationContext:
         return None
 
     def _prepare_buffered_stream(self, definition: Stream[object]) -> bool:
-        if self._method not in (InvocationMethod.WAIT_FOR, InvocationMethod.EXECUTE):
+        if self._method not in (
+            InvocationMethod.WAIT_FOR,
+            InvocationMethod.EXECUTE,
+            InvocationMethod.TIMEOUT,
+        ):
             raise ValueError("Buffered Streams require a Step Context")
         self._require_registered(definition)
         return self._output_emitter is not None
@@ -357,11 +380,10 @@ class InvocationContext:
                 ),
             )
         )
-        if self._method is InvocationMethod.RPC:
-            current = self._channel_infos.get(name)
-            self._channel_infos[name] = pb.ChannelInfo(
-                size=(current.size if current is not None else 0) + 1
-            )
+        current = self._channel_infos.get(name)
+        self._channel_infos[name] = pb.ChannelInfo(
+            size=(current.size if current is not None else 0) + 1
+        )
 
     def _delete_channel_message(
         self,
@@ -369,8 +391,6 @@ class InvocationContext:
         instance: str | None,
         message_id: str,
     ) -> None:
-        if self._method is not InvocationMethod.RPC:
-            raise ValueError("Channel message deletion requires an RPC Context")
         self._require_registered(definition)
         name = self._physical_name(definition, instance)
         self.channel_deletions.append(
@@ -410,8 +430,6 @@ class InvocationContext:
         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(
@@ -435,8 +453,6 @@ class InvocationContext:
         definition: Channel[ValueT] | ChannelMap[ValueT],
         instance: str | None,
     ) -> tuple[ChannelMessage[ValueT], ...]:
-        if self._method is not InvocationMethod.RPC:
-            raise ValueError("pending Channel messages require an RPC Context")
         self._require_registered(definition)
         if isinstance(definition, ChannelMap):
             channel_name = self._physical_name(definition, instance)
@@ -449,7 +465,7 @@ class InvocationContext:
             is_loaded = definition.name in self._loaded_channel_names
         if not is_loaded:
             raise ChannelMessagesNotLoadedError(
-                f"Channel messages were not loaded for RPC: {definition.name}"
+                f"Channel messages were not loaded for this invocation: {definition.name}"
             )
         values = self._loaded_channel_messages.get(channel_name)
         if values is None:
@@ -489,9 +505,7 @@ class InvocationContext:
         definition: Attribute[Any] | AttributeMap[Any],
         instance: str | None,
     ) -> None:
-        if self._method is not InvocationMethod.RPC or not isinstance(
-            definition, AttributeMap
-        ):
+        if not isinstance(definition, AttributeMap):
             return
         physical_name = self._physical_name(definition, instance)
         if (
@@ -499,19 +513,16 @@ class InvocationContext:
             and physical_name not in self._loaded_attribute_map_instances
         ):
             raise AttributeMapNotLoadedError(
-                f"AttributeMap instance was not loaded for RPC: {physical_name}"
+                f"AttributeMap instance was not loaded for this invocation: {physical_name}"
             )
 
     def _require_attribute_map_all_loaded(
         self,
         definition: AttributeMap[object],
     ) -> None:
-        if (
-            self._method is InvocationMethod.RPC
-            and f"{definition.name}/" not in self._loaded_attribute_map_instances
-        ):
+        if f"{definition.name}/" not in self._loaded_attribute_map_instances:
             raise AttributeMapNotLoadedError(
-                f"all AttributeMap instances were not loaded for RPC: {definition.name}"
+                f"all AttributeMap instances were not loaded for this invocation: {definition.name}"
             )
 
     def _require_registered(self, definition: _Definition) -> None:

{dex_python_sdk-0.2.11 → dex_python_sdk-0.3.2}/dex/_value_hydrator.py

@@ -80,12 +80,25 @@ class ValueHydrator:
         if has_heartbeat:
             values.append(request.context.last_heartbeat_value)
         values.extend(entry.value for entry in request.attributes)
+        channel_messages = [
+            message
+            for channel_values in request.loaded_channel_messages.values()
+            for message in channel_values.messages
+        ]
+        values.extend(message.value for message in channel_messages)
         hydrated = iter(self.hydrate_all(values))
         result.step_input.CopyFrom(next(hydrated))
         if has_heartbeat:
             result.context.last_heartbeat_value.CopyFrom(next(hydrated))
-        for entry, value in zip(result.attributes, hydrated):
-            entry.value.CopyFrom(value)
+        for entry in result.attributes:
+            entry.value.CopyFrom(next(hydrated))
+        result_messages = [
+            message
+            for channel_values in result.loaded_channel_messages.values()
+            for message in channel_values.messages
+        ]
+        for message in result_messages:
+            message.value.CopyFrom(next(hydrated))
         return result
 
     def execute_request(
@@ -101,6 +114,12 @@ class ValueHydrator:
             values.append(request.context.last_heartbeat_value)
         values.extend(entry.value for entry in request.attributes)
         values.extend(entry.value for entry in request.step_exe_locals)
+        channel_messages = [
+            message
+            for channel_values in request.loaded_channel_messages.values()
+            for message in channel_values.messages
+        ]
+        values.extend(message.value for message in channel_messages)
         for channel_result in request.condition_results.channel_results:
             values.extend(channel_result.values)
         for flow_result in request.condition_results.sub_flow_results:
@@ -116,6 +135,13 @@ class ValueHydrator:
             entry.value.CopyFrom(next(hydrated))
         for entry in result.step_exe_locals:
             entry.value.CopyFrom(next(hydrated))
+        result_messages = [
+            message
+            for channel_values in result.loaded_channel_messages.values()
+            for message in channel_values.messages
+        ]
+        for message in result_messages:
+            message.value.CopyFrom(next(hydrated))
         for channel_result in result.condition_results.channel_results:
             for value in channel_result.values:
                 value.CopyFrom(next(hydrated))