dex-python-sdk 0.6.0__tar.gz → 0.7.0__tar.gz

{dex_python_sdk-0.6.0 → dex_python_sdk-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dex-python-sdk
-Version: 0.6.0
+Version: 0.7.0
 Requires-Dist: grpcio>=1.83.0
 Requires-Dist: grpcio-status>=1.83.0
 Requires-Dist: protobuf>=7.35.1
@@ -361,6 +361,17 @@ 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.
 
+Request IDs are optional for both durable waits. When omitted, the server
+derives a namespaced stable ID from the Step execution or Attribute condition,
+such as `wait-for-attribute:myInt>10`. Reuse an override only for the same
+logical wait. The Client automatically reattaches transport long polls. If an
+earlier Update with that ID exhausted its handler budget, the server appends an
+increasing `-N` suffix and starts a new Update. `maximum_wait_time` is optional
+and is the total handler budget across reattachments; zero waits indefinitely.
+A positive budget expiry raises `WaitHandlerTimeoutError`. An abandoned infinite
+wait remains accepted and counts against Temporal's in-flight Update limit until
+it completes or the Flow closes.
+
 `Client.wait_for_flow` and `AsyncClient.wait_for_flow` return a
 `FlowResult` after hydrating every output-bearing completion. Use
 `single_output` only when the Flow contract produces exactly one output:

{dex_python_sdk-0.6.0 → dex_python_sdk-0.7.0}/README.md

@@ -345,6 +345,17 @@ 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.
 
+Request IDs are optional for both durable waits. When omitted, the server
+derives a namespaced stable ID from the Step execution or Attribute condition,
+such as `wait-for-attribute:myInt>10`. Reuse an override only for the same
+logical wait. The Client automatically reattaches transport long polls. If an
+earlier Update with that ID exhausted its handler budget, the server appends an
+increasing `-N` suffix and starts a new Update. `maximum_wait_time` is optional
+and is the total handler budget across reattachments; zero waits indefinitely.
+A positive budget expiry raises `WaitHandlerTimeoutError`. An abandoned infinite
+wait remains accepted and counts against Temporal's in-flight Update limit until
+it completes or the Flow closes.
+
 `Client.wait_for_flow` and `AsyncClient.wait_for_flow` return a
 `FlowResult` after hydrating every output-bearing completion. Use
 `single_output` only when the Flow contract produces exactly one output:

{dex_python_sdk-0.6.0 → dex_python_sdk-0.7.0}/dex/__init__.py

@@ -62,10 +62,11 @@ from dex.flow_options import (
 )
 from dex.flow_result import FlowResult, StepCompletion
 from dex.runtime_errors import (
-    DexServiceError,
-    ErrorSubStatus,
     AttributeMapNotLoadedError,
+    ChannelMessageNotFoundError,
     ChannelMessagesNotLoadedError,
+    DexServiceError,
+    ErrorSubStatus,
     FlowAlreadyStartedError,
     FlowDefinitionError,
     FlowErrorType,
@@ -73,9 +74,9 @@ from dex.runtime_errors import (
     FlowNotFoundError,
     InvalidStepResultError,
     LongPollTimeoutError,
-    ChannelMessageNotFoundError,
     RpcLockConflictError,
     ValueMappingError,
+    WaitHandlerTimeoutError,
     WorkerInvocationError,
 )
 from dex.step import (
@@ -108,6 +109,7 @@ from dex.stream import (
 from dex.subflow import SubFlow
 from dex.timer import Timer
 from dex.wait import Wait
+from dex.wait_options import WaitForAttributeOptions, WaitForStepCompletionOptions
 from dex.worker import Worker
 from dex.worker_options import WorkerOptions, WorkerTarget
 
@@ -164,6 +166,7 @@ __all__ = [
     "IndexType",
     "JsonCodec",
     "LongPollTimeoutError",
+    "WaitHandlerTimeoutError",
     "PersistenceSchema",
     "RPCResult",
     "RecoveryErrorInfo",
@@ -205,6 +208,8 @@ __all__ = [
     "WorkerInvocationError",
     "WorkerOptions",
     "WorkerTarget",
+    "WaitForAttributeOptions",
+    "WaitForStepCompletionOptions",
     "dead_end",
     "force_complete",
     "force_complete_if_channels_empty",

{dex_python_sdk-0.6.0 → dex_python_sdk-0.7.0}/dex/_grpc_errors.py

@@ -27,12 +27,17 @@ from dex.runtime_errors import (
     FlowNotFoundError,
     LongPollTimeoutError,
     RpcLockConflictError,
+    WaitHandlerTimeoutError,
     WorkerInvocationError,
 )
 
 FlowTargetRequirement = Literal["none", "existing", "active"]
 
-MAX_WORKER_STACK_TRACE_BYTES = 16 * 1024
+MAX_WORKER_ERROR_DETAIL_BYTES = 1024
+MAX_WORKER_ERROR_TYPE_BYTES = 256
+MAX_WORKER_STACK_TRACE_BYTES = 4 * 1024
+_ERROR_DETAIL_TRUNCATION_MARKER = b"\n... error detail truncated by Dex Python SDK ..."
+_ERROR_TYPE_TRUNCATION_MARKER = b"\n... error type truncated by Dex Python SDK ..."
 _STACK_TRACE_TRUNCATION_MARKER = b"\n... stack trace truncated by Dex Python SDK ..."
 
 
@@ -139,6 +144,8 @@ def translate_rpc_error(
         return LongPollTimeoutError(*parameters)
     if sub_status is ErrorSubStatus.CHANNEL_MESSAGE_NOT_FOUND:
         return ChannelMessageNotFoundError(*parameters)
+    if sub_status is ErrorSubStatus.WAIT_HANDLER_TIMEOUT:
+        return WaitHandlerTimeoutError(*parameters)
     return DexServiceError(*parameters)
 
 
@@ -179,11 +186,19 @@ def _worker_error_status(error: BaseException) -> status_pb2.Status:
         retry_after_error = error
         reported = error.cause
 
-    message = str(reported) or type(reported).__name__
+    message = _truncate_worker_failure_field(
+        str(reported) or type(reported).__name__,
+        MAX_WORKER_ERROR_DETAIL_BYTES,
+        _ERROR_DETAIL_TRUNCATION_MARKER,
+    )
     stack_trace_source = error if retry_after_error is not None else reported
     worker_error = pb.WorkerErrorResponse(
         detail=message,
-        error_type=f"{type(reported).__module__}.{type(reported).__qualname__}",
+        error_type=_truncate_worker_failure_field(
+            f"{type(reported).__module__}.{type(reported).__qualname__}",
+            MAX_WORKER_ERROR_TYPE_BYTES,
+            _ERROR_TYPE_TRUNCATION_MARKER,
+        ),
         stack_trace=_worker_stack_trace(stack_trace_source),
     )
     if retry_after_error is not None:
@@ -201,16 +216,25 @@ def _worker_stack_trace(error: BaseException) -> str:
     if error.__traceback__ is None:
         return ""
     lines = traceback.format_exception(type(error), error, error.__traceback__)
-    encoded = "".join(lines).encode()
-    if len(encoded) <= MAX_WORKER_STACK_TRACE_BYTES:
-        return encoded.decode()
-    prefix_length = MAX_WORKER_STACK_TRACE_BYTES - len(_STACK_TRACE_TRUNCATION_MARKER)
+    return _truncate_worker_failure_field(
+        "".join(lines),
+        MAX_WORKER_STACK_TRACE_BYTES,
+        _STACK_TRACE_TRUNCATION_MARKER,
+    )
+
+
+def _truncate_worker_failure_field(
+    value: str,
+    maximum_bytes: int,
+    truncation_marker: bytes,
+) -> str:
+    encoded = value.encode()
+    if len(encoded) <= maximum_bytes:
+        return value
+    prefix_length = maximum_bytes - len(truncation_marker)
     while prefix_length > 0 and (encoded[prefix_length] & 0xC0) == 0x80:
         prefix_length -= 1
-    return (
-        encoded[:prefix_length].decode(errors="replace")
-        + _STACK_TRACE_TRUNCATION_MARKER.decode()
-    )
+    return encoded[:prefix_length].decode() + truncation_marker.decode()
 
 
 def _map_sub_status(value: int) -> ErrorSubStatus:
@@ -225,5 +249,8 @@ def _map_sub_status(value: int) -> ErrorSubStatus:
         int(
             pb.ERROR_SUB_STATUS_CHANNEL_MESSAGE_NOT_FOUND
         ): ErrorSubStatus.CHANNEL_MESSAGE_NOT_FOUND,
+        int(
+            pb.ERROR_SUB_STATUS_WAIT_HANDLER_TIME_OUT
+        ): ErrorSubStatus.WAIT_HANDLER_TIMEOUT,
     }
     return statuses.get(value, ErrorSubStatus.UNCATEGORIZED)

{dex_python_sdk-0.6.0 → dex_python_sdk-0.7.0}/dex/async_client.py

@@ -45,10 +45,15 @@ from dex.flow_options import (
     _resolve_flow_timeout_policy,
 )
 from dex.flow_result import FlowResult, flow_result_from_proto
-from dex.runtime_errors import FlowErrorType
+from dex.runtime_errors import FlowErrorType, LongPollTimeoutError
 from dex.step import RetryPolicy, StepDurability
 from dex.step_execution import StepExecutionId, TimerId
 from dex.stream import Stream, StreamMessage, StreamMessagesPage
+from dex.wait_options import (
+    WaitForAttributeOptions,
+    WaitForStepCompletionOptions,
+    _ClientWaitBudget,
+)
 
 InputT = TypeVar("InputT")
 OutputT = TypeVar("OutputT")
@@ -723,33 +728,45 @@ class AsyncClient:
         self,
         flow_id: str,
         step_execution_id: StepExecutionId,
-        timeout: timedelta,
+        options: WaitForStepCompletionOptions,
     ) -> None:
-        """Await one Step execution's completion or a long-poll timeout.
+        """Await one Step execution's completion or its handler budget expiry.
+
+        The server derives a stable Request ID from the Step execution when none
+        is supplied. Transport long polls automatically reattach to the same wait.
 
         Args:
             flow_id: The non-empty active Flow ID.
             step_execution_id: The Step type and positive execution number.
-            timeout: The non-negative server-side wait duration.
+            options: The optional Request ID override and total handler wait budget.
 
         Raises:
-            LongPollTimeoutError: If completion is not observed before ``timeout``.
+            ValueError: If the Request ID or handler wait budget is invalid.
+            WaitHandlerTimeoutError: If a positive handler budget expires first.
             FlowNotActiveError: If the Flow closes first.
             DexServiceError: If FlowService cannot perform the wait.
         """
-        await self._call(
-            self._service.WaitForStepCompletion,
-            pb.WaitForStepCompletionRequest(
-                flow_id=require_name(flow_id),
-                step_type=step_execution_id.step_type,
-                step_execution_number=str(step_execution_id.number),
-                wait_time_seconds=self._seconds32(timeout),
-                request_id=str(uuid4()),
-            ),
-            "wait_for_step_completion",
-            flow_id,
-            "active",
-        )
+        wait_budget = _ClientWaitBudget(options.maximum_wait_time)
+        while True:
+            try:
+                await self._call(
+                    self._service.WaitForStepCompletion,
+                    pb.WaitForStepCompletionRequest(
+                        flow_id=require_name(flow_id),
+                        step_type=step_execution_id.step_type,
+                        step_execution_number=str(step_execution_id.number),
+                        wait_time_seconds=wait_budget.remaining_seconds(
+                            "wait_for_step_completion", flow_id
+                        ),
+                        request_id=options.request_id,
+                    ),
+                    "wait_for_step_completion",
+                    flow_id,
+                    "active",
+                )
+                return
+            except LongPollTimeoutError:
+                continue
 
     @overload
     async def wait_for_attribute_match(
@@ -757,26 +774,26 @@ class AsyncClient:
         flow_id: str,
         attribute: Attribute[ValueT],
         match: AttributeMatch[ValueT],
-        timeout: timedelta,
+        options: WaitForAttributeOptions,
     ) -> ValueT:
         """Await a singleton Attribute in the current run satisfying ``match``.
 
-        The Client returns the value observed by the successful wait. JSON,
-        bytes, and null operands raise ``ValueError`` before transport. A remote
-        expiry raises ``LongPollTimeoutError``.
+        The Client returns the value observed by the successful wait. The server
+        derives a stable Request ID from the condition when none is supplied.
+        JSON, bytes, and null operands raise ``ValueError`` before transport.
 
         Args:
             flow_id: The non-empty active Flow ID.
             attribute: The registered singleton Attribute to observe.
             match: The scalar predicate to await.
-            timeout: The non-negative server-side wait duration.
+            options: The optional Request ID override and total handler wait budget.
 
         Returns:
             The current Attribute value that satisfied ``match``.
 
         Raises:
-            ValueError: If an identifier, timeout, or match operand is invalid.
-            LongPollTimeoutError: If the match is not observed before ``timeout``.
+            ValueError: If an identifier, option, or match operand is invalid.
+            WaitHandlerTimeoutError: If a positive handler budget expires first.
             FlowNotActiveError: If the Flow closes first.
             DexServiceError: If FlowService cannot perform the wait.
         """
@@ -789,11 +806,11 @@ class AsyncClient:
         attribute: AttributeMap[ValueT],
         instance: str,
         match: AttributeMatch[ValueT],
-        timeout: timedelta,
+        options: WaitForAttributeOptions,
     ) -> ValueT:
         """Await one AttributeMap instance in the current run satisfying a match.
 
-        Match restrictions, request-ID generation, timeout behavior, and service
+        Match restrictions, Request ID, handler-budget behavior, and service
         errors match :meth:`wait_for_attribute_match`.
 
         Args:
@@ -801,14 +818,14 @@ class AsyncClient:
             attribute: The registered AttributeMap to observe.
             instance: The map instance to observe. Slash is prohibited because it is a reserved character.
             match: The scalar predicate to await.
-            timeout: The non-negative server-side wait duration.
+            options: The optional Request ID override and total handler wait budget.
 
         Returns:
             The current AttributeMap value that satisfied ``match``.
 
         Raises:
-            ValueError: If an identifier, timeout, or match operand is invalid.
-            LongPollTimeoutError: If the match is not observed before ``timeout``.
+            ValueError: If an identifier, option, or match operand is invalid.
+            WaitHandlerTimeoutError: If a positive handler budget expires first.
             FlowNotActiveError: If the Flow closes first.
             DexServiceError: If FlowService cannot perform the wait.
         """
@@ -824,12 +841,12 @@ class AsyncClient:
         """Await a singleton Attribute or AttributeMap instance satisfying a match.
 
         Singleton form is ``wait_for_attribute_match(flow_id, attribute, match,
-        timeout)``; map form adds ``instance`` before ``match``.
+        options)``; map form adds ``instance`` before ``match``.
 
         Args:
             flow_id: The non-empty active Flow ID.
             attribute: The registered Attribute or AttributeMap to observe.
-            *args: Positional match and timeout, optionally preceded by a map instance.
+            *args: Positional match and options, optionally preceded by a map instance.
             **kwargs: The same arguments supplied by name.
 
         Returns:
@@ -837,16 +854,16 @@ class AsyncClient:
 
         Raises:
             TypeError: If arguments do not match the Attribute definition.
-            ValueError: If an identifier, timeout, or expected value is invalid.
-            LongPollTimeoutError: If the match is not observed before the timeout.
+            ValueError: If an identifier, option, or expected value is invalid.
+            WaitHandlerTimeoutError: If a positive handler budget expires first.
             FlowNotActiveError: If the Flow closes first.
             DexServiceError: If FlowService cannot perform the wait.
         """
-        instance, match, timeout = self._attribute_wait_arguments(
+        instance, match, options = self._attribute_wait_arguments(
             attribute, args, kwargs
         )
         return await self._wait_for_attribute_match(
-            flow_id, attribute, instance, match, timeout
+            flow_id, attribute, instance, match, options
         )
 
     async def _wait_for_attribute_match(
@@ -855,7 +872,7 @@ class AsyncClient:
         attribute: Attribute[Any] | AttributeMap[Any],
         instance: str | None,
         match: object,
-        timeout: timedelta,
+        options: WaitForAttributeOptions,
     ) -> Any:
         encoded_match = _encode_attribute_match(
             cast(AttributeMatch[Any], match),
@@ -863,27 +880,34 @@ class AsyncClient:
             self._values.codec(attribute.value_type),
         )
         encoded_match.key = self._definition_name(attribute, instance)
-        response = cast(
-            pb.WaitForAttributeResponse,
-            await self._call(
-                self._service.WaitForAttribute,
-                pb.WaitForAttributeRequest(
-                    flow_id=require_name(flow_id),
-                    match=encoded_match,
-                    wait_time_seconds=self._seconds32(timeout),
-                    request_id=str(uuid4()),
-                ),
-                "wait_for_attribute_match",
-                flow_id,
-                "active",
-            ),
-        )
-        if not response.HasField("matched_value"):
-            raise ValueError("wait_for_attribute_match response is incomplete")
-        return self._values.decode(
-            response.matched_value,
-            self._values.codec(attribute.value_type),
-        )
+        wait_budget = _ClientWaitBudget(options.maximum_wait_time)
+        while True:
+            try:
+                response = cast(
+                    pb.WaitForAttributeResponse,
+                    await self._call(
+                        self._service.WaitForAttribute,
+                        pb.WaitForAttributeRequest(
+                            flow_id=require_name(flow_id),
+                            match=encoded_match,
+                            wait_time_seconds=wait_budget.remaining_seconds(
+                                "wait_for_attribute_match", flow_id
+                            ),
+                            request_id=options.request_id,
+                        ),
+                        "wait_for_attribute_match",
+                        flow_id,
+                        "active",
+                    ),
+                )
+                if not response.HasField("matched_value"):
+                    raise ValueError("wait_for_attribute_match response is incomplete")
+                return self._values.decode(
+                    response.matched_value,
+                    self._values.codec(attribute.value_type),
+                )
+            except LongPollTimeoutError:
+                continue
 
     async def update_flow_config(self, flow_id: str, config: FlowConfig) -> None:
         """Replace mutable configuration for an active Flow.
@@ -1108,12 +1132,12 @@ class AsyncClient:
         definition: Attribute[Any] | AttributeMap[Any],
         args: tuple[object, ...],
         kwargs: dict[str, object],
-    ) -> tuple[str | None, object, timedelta]:
+    ) -> tuple[str | None, object, WaitForAttributeOptions]:
         parameter_names: tuple[str, ...]
         if isinstance(definition, Attribute):
-            parameter_names = ("match", "timeout")
+            parameter_names = ("match", "options")
         elif isinstance(definition, AttributeMap):
-            parameter_names = ("instance", "match", "timeout")
+            parameter_names = ("instance", "match", "options")
         else:
             raise TypeError("wait_for_attribute_match received invalid arguments")
         if len(args) > len(parameter_names):
@@ -1125,15 +1149,15 @@ class AsyncClient:
             arguments[name] = value
         if set(arguments) != set(parameter_names):
             raise TypeError("wait_for_attribute_match received invalid arguments")
-        timeout = arguments["timeout"]
-        if not isinstance(timeout, timedelta):
+        options = arguments["options"]
+        if not isinstance(options, WaitForAttributeOptions):
             raise TypeError("wait_for_attribute_match received invalid arguments")
         if isinstance(definition, Attribute):
-            return None, arguments["match"], timeout
+            return None, arguments["match"], options
         instance = arguments["instance"]
         if not isinstance(instance, str):
             raise TypeError("wait_for_attribute_match received invalid arguments")
-        return instance, arguments["match"], timeout
+        return instance, arguments["match"], options
 
     @staticmethod
     def _resolve_timeout_policy(