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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dex-python-sdk
-Version: 0.3.1
+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.3.1 → 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.3.1 → 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 (
@@ -163,6 +163,7 @@ __all__ = [
     "LongPollTimeoutError",
     "PersistenceSchema",
     "RPCResult",
+    "RecoveryErrorInfo",
     "RetryAfterError",
     "RpcLockConflictError",
     "Registry",

{dex_python_sdk-0.3.1 → 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

{dex_python_sdk-0.3.1 → dex_python_sdk-0.3.2}/dex/context.py

@@ -10,6 +10,7 @@
 
 from __future__ import annotations
 
+from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Protocol, Sequence, TypeVar
 
 if TYPE_CHECKING:
@@ -27,6 +28,19 @@ if TYPE_CHECKING:
 ValueT = TypeVar("ValueT")
 
 
+@dataclass(frozen=True)
+class RecoveryErrorInfo:
+    """Describe the final failure that selected a recovery path.
+
+    Attributes:
+        detail: Failure message supplied by the Worker or backend.
+        error_type: Original Worker error type or backend failure type.
+    """
+
+    detail: str
+    error_type: str
+
+
 class Context(Protocol):
     """Expose execution metadata and decision-local Step operations.
 
@@ -72,6 +86,15 @@ class Context(Protocol):
         """
         ...
 
+    @property
+    def recovery_error(self) -> RecoveryErrorInfo | None:
+        """Return the final failure that selected this recovery path.
+
+        Returns:
+            Recovery information, or ``None`` outside a recovery path.
+        """
+        ...
+
     @property
     def attempt(self) -> int:
         """Return the one-based handler retry attempt.

{dex_python_sdk-0.3.1 → dex_python_sdk-0.3.2}/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.3.1"
+version = "0.3.2"
 description = "Python SDK for the Dex workflow engine"
 authors = [{name = "Super Durable"}]
 readme = "README.md"