dex-python-sdk 0.11.2__tar.gz → 0.12.1__tar.gz

{dex_python_sdk-0.11.2 → dex_python_sdk-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dex-python-sdk
-Version: 0.11.2
+Version: 0.12.1
 Requires-Dist: grpcio>=1.83.0
 Requires-Dist: grpcio-status>=1.83.0
 Requires-Dist: protobuf>=7.35.1
@@ -363,11 +363,16 @@ sorted. Use `force_complete_if_channels_empty(...)` for conditional completion.
 
 Request IDs are optional for both durable waits. When omitted, the server
 derives a stable ID from the Step execution or Attribute condition. Reuse an
-override only for the same wait. `maximum_wait_time` is optional. Leave it at
-zero for normal use and bound one response with the caller deadline. Positive
-values are an exceptional safety valve: short budgets can add many Temporal
-Update events to Workflow history. If a positive value is truly needed, prefer
-at least one minute. A positive expiry raises `WaitHandlerTimeoutError`.
+override only for the same wait. `request_timeout` is the total SDK call budget
+across transparent transport reattachments. Zero waits indefinitely.
+Temporal permits 10 in-flight Updates and 2,000 total Updates in History per
+Workflow Execution. A caller timeout or cancellation does not finish an
+accepted durable wait, so an abandoned handler can retain one in-flight slot.
+Set `internal_handler_timeout` only when abandoned waits can approach that
+limit. An active call transparently starts another generation, which counts
+toward the 2,000-Update history limit. Prefer a value comfortably longer than
+normal request timeouts and reconnect gaps. Zero disables timed rollover.
+Request expiry raises `RequestTimeoutError`.
 
 `Client.wait_for_flow` and `AsyncClient.wait_for_flow` return a
 `FlowResult` after hydrating every output-bearing completion. Use

{dex_python_sdk-0.11.2 → dex_python_sdk-0.12.1}/README.md

@@ -347,11 +347,16 @@ sorted. Use `force_complete_if_channels_empty(...)` for conditional completion.
 
 Request IDs are optional for both durable waits. When omitted, the server
 derives a stable ID from the Step execution or Attribute condition. Reuse an
-override only for the same wait. `maximum_wait_time` is optional. Leave it at
-zero for normal use and bound one response with the caller deadline. Positive
-values are an exceptional safety valve: short budgets can add many Temporal
-Update events to Workflow history. If a positive value is truly needed, prefer
-at least one minute. A positive expiry raises `WaitHandlerTimeoutError`.
+override only for the same wait. `request_timeout` is the total SDK call budget
+across transparent transport reattachments. Zero waits indefinitely.
+Temporal permits 10 in-flight Updates and 2,000 total Updates in History per
+Workflow Execution. A caller timeout or cancellation does not finish an
+accepted durable wait, so an abandoned handler can retain one in-flight slot.
+Set `internal_handler_timeout` only when abandoned waits can approach that
+limit. An active call transparently starts another generation, which counts
+toward the 2,000-Update history limit. Prefer a value comfortably longer than
+normal request timeouts and reconnect gaps. Zero disables timed rollover.
+Request expiry raises `RequestTimeoutError`.
 
 `Client.wait_for_flow` and `AsyncClient.wait_for_flow` return a
 `FlowResult` after hydrating every output-bearing completion. Use

{dex_python_sdk-0.11.2 → dex_python_sdk-0.12.1}/dex/__init__.py

@@ -74,9 +74,9 @@ from dex.runtime_errors import (
     FlowNotFoundError,
     InvalidStepResultError,
     LongPollTimeoutError,
+    RequestTimeoutError,
     RpcLockConflictError,
     ValueMappingError,
-    WaitHandlerTimeoutError,
     WorkerInvocationError,
 )
 from dex.step import (
@@ -166,7 +166,7 @@ __all__ = [
     "IndexType",
     "JsonCodec",
     "LongPollTimeoutError",
-    "WaitHandlerTimeoutError",
+    "RequestTimeoutError",
     "PersistenceSchema",
     "RPCResult",
     "RecoveryErrorInfo",

{dex_python_sdk-0.11.2 → dex_python_sdk-0.12.1}/dex/_grpc_errors.py

@@ -26,8 +26,8 @@ from dex.runtime_errors import (
     FlowNotActiveError,
     FlowNotFoundError,
     LongPollTimeoutError,
+    RequestTimeoutError,
     RpcLockConflictError,
-    WaitHandlerTimeoutError,
     WorkerInvocationError,
 )
 
@@ -144,8 +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)
+    if sub_status is ErrorSubStatus.REQUEST_TIMEOUT:
+        return RequestTimeoutError(*parameters)
     return DexServiceError(*parameters)
 
 
@@ -249,8 +249,6 @@ 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,
+        int(pb.ERROR_SUB_STATUS_REQUEST_TIMEOUT): ErrorSubStatus.REQUEST_TIMEOUT,
     }
     return statuses.get(value, ErrorSubStatus.UNCATEGORIZED)

{dex_python_sdk-0.11.2 → dex_python_sdk-0.12.1}/dex/async_client.py

@@ -45,14 +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, LongPollTimeoutError
+from dex.runtime_errors import DexServiceError, 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,
+    _ClientRequestBudget,
+    _duration_seconds32,
 )
 
 InputT = TypeVar("InputT")
@@ -738,27 +739,33 @@ class AsyncClient:
         step_execution_id: StepExecutionId,
         options: WaitForStepCompletionOptions,
     ) -> None:
-        """Await one Step execution's completion or its wait budget expiry.
+        """Await one Step execution completion or its request timeout expiry.
 
         The server derives a stable Request ID from the Step execution when none
-        is supplied. Leave the maximum wait time at zero for normal use. Positive
-        values are exceptional because short budgets can add many Temporal Update
-        events to Workflow history; prefer at least one minute when nonzero. A
-        positive value bounds the caller-visible wait.
+        is supplied. Request timeout covers transparent transport reattachments.
+        Internal handler timeout controls Update generation rollover without ending
+        this request.
 
         Args:
             flow_id: The non-empty active Flow ID.
             step_execution_id: The Step type and positive execution number.
-            options: The optional Request ID override and total wait budget.
+            options: The optional Request ID, request timeout, and internal handler
+                timeout controls.
 
         Raises:
-            ValueError: If the Request ID or wait budget is invalid.
-            WaitHandlerTimeoutError: If a positive wait budget expires first.
+            ValueError: If the Request ID or request timeout is invalid.
+            RequestTimeoutError: If a positive request timeout expires first.
             FlowNotActiveError: If the Flow closes first.
             DexServiceError: If FlowService cannot perform the wait.
         """
-        wait_budget = _ClientWaitBudget(options.maximum_wait_time)
+        request_budget = _ClientRequestBudget(options.request_timeout)
+        internal_handler_timeout_seconds = _duration_seconds32(
+            options.internal_handler_timeout
+        )
         while True:
+            request_attempt = request_budget.next_attempt(
+                "wait_for_step_completion", flow_id
+            )
             try:
                 await self._call(
                     self._service.WaitForStepCompletion,
@@ -766,18 +773,29 @@ class AsyncClient:
                         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_timeout_seconds=request_attempt.request_timeout_seconds,
+                        internal_handler_timeout_seconds=(
+                            internal_handler_timeout_seconds
                         ),
                         request_id=options.request_id,
                     ),
                     "wait_for_step_completion",
                     flow_id,
                     "active",
+                    request_attempt.transport_timeout_seconds,
                 )
                 return
             except LongPollTimeoutError:
                 continue
+            except DexServiceError as error:
+                if (
+                    error.code is grpc.StatusCode.DEADLINE_EXCEEDED
+                    and request_budget.has_expired()
+                ):
+                    raise request_budget.timeout_error(
+                        "wait_for_step_completion", flow_id
+                    ) from error
+                raise
 
     @overload
     async def wait_for_attribute_match(
@@ -791,24 +809,23 @@ class AsyncClient:
 
         The Client returns the value observed by the successful wait. The server
         derives a stable Request ID from the condition when none is supplied.
-        Leave the maximum wait time at zero for normal use. Positive values are
-        exceptional because short budgets can add many Temporal Update events to
-        Workflow history; prefer at least one minute when nonzero. A positive value
-        bounds the caller-visible wait.
+        Request timeout covers transparent transport reattachments. Internal handler
+        timeout controls Update generation rollover without ending this request.
         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.
-            options: The optional Request ID override and total wait budget.
+            options: The optional Request ID, request timeout, and internal handler
+                timeout controls.
 
         Returns:
             The current Attribute value that satisfied ``match``.
 
         Raises:
             ValueError: If an identifier, option, or match operand is invalid.
-            WaitHandlerTimeoutError: If a positive wait budget expires first.
+            RequestTimeoutError: If a positive request timeout expires first.
             FlowNotActiveError: If the Flow closes first.
             DexServiceError: If FlowService cannot perform the wait.
         """
@@ -825,7 +842,7 @@ class AsyncClient:
     ) -> ValueT:
         """Await one AttributeMap instance in the current run satisfying a match.
 
-        Match restrictions, Request ID, handler-budget behavior, and service
+        Match restrictions, Request ID, request-timeout and handler-generation behavior, and service
         errors match :meth:`wait_for_attribute_match`.
 
         Args:
@@ -833,14 +850,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.
-            options: The optional Request ID override and total handler wait budget.
+            options: The optional Request ID override and total handler request timeout.
 
         Returns:
             The current AttributeMap value that satisfied ``match``.
 
         Raises:
             ValueError: If an identifier, option, or match operand is invalid.
-            WaitHandlerTimeoutError: If a positive wait budget expires first.
+            RequestTimeoutError: If a positive request timeout expires first.
             FlowNotActiveError: If the Flow closes first.
             DexServiceError: If FlowService cannot perform the wait.
         """
@@ -870,7 +887,7 @@ class AsyncClient:
         Raises:
             TypeError: If arguments do not match the Attribute definition.
             ValueError: If an identifier, option, or expected value is invalid.
-            WaitHandlerTimeoutError: If a positive wait budget expires first.
+            RequestTimeoutError: If a positive request timeout expires first.
             FlowNotActiveError: If the Flow closes first.
             DexServiceError: If FlowService cannot perform the wait.
         """
@@ -895,8 +912,14 @@ class AsyncClient:
             self._values.codec(attribute.value_type),
         )
         encoded_match.key = self._definition_name(attribute, instance)
-        wait_budget = _ClientWaitBudget(options.maximum_wait_time)
+        request_budget = _ClientRequestBudget(options.request_timeout)
+        internal_handler_timeout_seconds = _duration_seconds32(
+            options.internal_handler_timeout
+        )
         while True:
+            request_attempt = request_budget.next_attempt(
+                "wait_for_attribute_match", flow_id
+            )
             try:
                 response = cast(
                     pb.WaitForAttributeResponse,
@@ -905,14 +928,18 @@ class AsyncClient:
                         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_timeout_seconds=(
+                                request_attempt.request_timeout_seconds
+                            ),
+                            internal_handler_timeout_seconds=(
+                                internal_handler_timeout_seconds
                             ),
                             request_id=options.request_id,
                         ),
                         "wait_for_attribute_match",
                         flow_id,
                         "active",
+                        request_attempt.transport_timeout_seconds,
                     ),
                 )
                 if not response.HasField("matched_value"):
@@ -923,6 +950,15 @@ class AsyncClient:
                 )
             except LongPollTimeoutError:
                 continue
+            except DexServiceError as error:
+                if (
+                    error.code is grpc.StatusCode.DEADLINE_EXCEEDED
+                    and request_budget.has_expired()
+                ):
+                    raise request_budget.timeout_error(
+                        "wait_for_attribute_match", flow_id
+                    ) from error
+                raise
 
     async def update_flow_config(self, flow_id: str, config: FlowConfig) -> None:
         """Replace mutable configuration for an active Flow.
@@ -1245,13 +1281,16 @@ class AsyncClient:
 
     @staticmethod
     async def _call(
-        method: Callable[[Any], Any],
+        method: Callable[..., Any],
         request: Any,
         operation: str,
         flow_id: str | None,
         requirement: FlowTargetRequirement,
+        timeout: float | None = None,
     ) -> Any:
         try:
-            return await method(request)
+            if timeout is None:
+                return await method(request)
+            return await method(request, timeout=timeout)
         except grpc.RpcError as error:
             raise translate_rpc_error(error, operation, flow_id, requirement) from error

{dex_python_sdk-0.11.2 → dex_python_sdk-0.12.1}/dex/client.py

@@ -45,14 +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, LongPollTimeoutError
+from dex.runtime_errors import DexServiceError, 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,
+    _ClientRequestBudget,
+    _duration_seconds32,
 )
 
 InputT = TypeVar("InputT")
@@ -734,27 +735,33 @@ class Client:
         step_execution_id: StepExecutionId,
         options: WaitForStepCompletionOptions,
     ) -> None:
-        """Block until one Step execution completes or its wait budget expires.
+        """Block until one Step execution completes or its request timeout expires.
 
         The server derives a stable Request ID from the Step execution when none
-        is supplied. Leave the maximum wait time at zero for normal use. Positive
-        values are exceptional because short budgets can add many Temporal Update
-        events to Workflow history; prefer at least one minute when nonzero. A
-        positive value bounds the caller-visible wait.
+        is supplied. Request timeout covers transparent transport reattachments.
+        Internal handler timeout controls Update generation rollover without ending
+        this request.
 
         Args:
             flow_id: The non-empty active Flow ID.
             step_execution_id: The Step type and positive execution number.
-            options: The optional Request ID override and total wait budget.
+            options: The optional Request ID, request timeout, and internal handler
+                timeout controls.
 
         Raises:
-            ValueError: If the Request ID or wait budget is invalid.
-            WaitHandlerTimeoutError: If a positive wait budget expires first.
+            ValueError: If the Request ID or request timeout is invalid.
+            RequestTimeoutError: If a positive request timeout expires first.
             FlowNotActiveError: If the Flow closes first.
             DexServiceError: If FlowService cannot perform the wait.
         """
-        wait_budget = _ClientWaitBudget(options.maximum_wait_time)
+        request_budget = _ClientRequestBudget(options.request_timeout)
+        internal_handler_timeout_seconds = _duration_seconds32(
+            options.internal_handler_timeout
+        )
         while True:
+            request_attempt = request_budget.next_attempt(
+                "wait_for_step_completion", flow_id
+            )
             try:
                 self._call(
                     self._service.WaitForStepCompletion,
@@ -762,18 +769,29 @@ class Client:
                         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_timeout_seconds=request_attempt.request_timeout_seconds,
+                        internal_handler_timeout_seconds=(
+                            internal_handler_timeout_seconds
                         ),
                         request_id=options.request_id,
                     ),
                     "wait_for_step_completion",
                     flow_id,
                     "active",
+                    request_attempt.transport_timeout_seconds,
                 )
                 return
             except LongPollTimeoutError:
                 continue
+            except DexServiceError as error:
+                if (
+                    error.code is grpc.StatusCode.DEADLINE_EXCEEDED
+                    and request_budget.has_expired()
+                ):
+                    raise request_budget.timeout_error(
+                        "wait_for_step_completion", flow_id
+                    ) from error
+                raise
 
     @overload
     def wait_for_attribute_match(
@@ -787,24 +805,23 @@ class Client:
 
         The Client returns the value observed by the successful wait. The server
         derives a stable Request ID from the condition when none is supplied.
-        Leave the maximum wait time at zero for normal use. Positive values are
-        exceptional because short budgets can add many Temporal Update events to
-        Workflow history; prefer at least one minute when nonzero. A positive value
-        bounds the caller-visible wait.
+        Request timeout covers transparent transport reattachments. Internal handler
+        timeout controls Update generation rollover without ending this request.
         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.
-            options: The optional Request ID override and total wait budget.
+            options: The optional Request ID, request timeout, and internal handler
+                timeout controls.
 
         Returns:
             The current Attribute value that satisfied ``match``.
 
         Raises:
             ValueError: If an identifier, option, or match operand is invalid.
-            WaitHandlerTimeoutError: If a positive wait budget expires first.
+            RequestTimeoutError: If a positive request timeout expires first.
             FlowNotActiveError: If the Flow closes first.
             DexServiceError: If FlowService cannot perform the wait.
         """
@@ -822,7 +839,7 @@ class Client:
         """Wait for one AttributeMap instance in the current run to match.
 
         ``instance`` is encoded as a map key. Match restrictions, Request ID,
-        handler-budget behavior, and service errors match
+        request-timeout and handler-generation behavior, and service errors match
         :meth:`wait_for_attribute_match`.
 
         Args:
@@ -830,14 +847,14 @@ class Client:
             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.
-            options: The optional Request ID override and total handler wait budget.
+            options: The optional Request ID override and total handler request timeout.
 
         Returns:
             The current AttributeMap value that satisfied ``match``.
 
         Raises:
             ValueError: If an identifier, option, or match operand is invalid.
-            WaitHandlerTimeoutError: If a positive wait budget expires first.
+            RequestTimeoutError: If a positive request timeout expires first.
             FlowNotActiveError: If the Flow closes first.
             DexServiceError: If FlowService cannot perform the wait.
         """
@@ -867,7 +884,7 @@ class Client:
         Raises:
             TypeError: If arguments do not match the Attribute definition.
             ValueError: If an identifier, option, or expected value is invalid.
-            WaitHandlerTimeoutError: If a positive wait budget expires first.
+            RequestTimeoutError: If a positive request timeout expires first.
             FlowNotActiveError: If the Flow closes first.
             DexServiceError: If FlowService cannot perform the wait.
         """
@@ -892,8 +909,14 @@ class Client:
             self._values.codec(attribute.value_type),
         )
         encoded_match.key = self._definition_name(attribute, instance)
-        wait_budget = _ClientWaitBudget(options.maximum_wait_time)
+        request_budget = _ClientRequestBudget(options.request_timeout)
+        internal_handler_timeout_seconds = _duration_seconds32(
+            options.internal_handler_timeout
+        )
         while True:
+            request_attempt = request_budget.next_attempt(
+                "wait_for_attribute_match", flow_id
+            )
             try:
                 response = cast(
                     pb.WaitForAttributeResponse,
@@ -902,14 +925,18 @@ class Client:
                         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_timeout_seconds=(
+                                request_attempt.request_timeout_seconds
+                            ),
+                            internal_handler_timeout_seconds=(
+                                internal_handler_timeout_seconds
                             ),
                             request_id=options.request_id,
                         ),
                         "wait_for_attribute_match",
                         flow_id,
                         "active",
+                        request_attempt.transport_timeout_seconds,
                     ),
                 )
                 if not response.HasField("matched_value"):
@@ -920,6 +947,15 @@ class Client:
                 )
             except LongPollTimeoutError:
                 continue
+            except DexServiceError as error:
+                if (
+                    error.code is grpc.StatusCode.DEADLINE_EXCEEDED
+                    and request_budget.has_expired()
+                ):
+                    raise request_budget.timeout_error(
+                        "wait_for_attribute_match", flow_id
+                    ) from error
+                raise
 
     def update_flow_config(self, flow_id: str, config: FlowConfig) -> None:
         """Replace mutable configuration for an active Flow.
@@ -1242,13 +1278,16 @@ class Client:
 
     @staticmethod
     def _call(
-        method: Callable[[Any], Any],
+        method: Callable[..., Any],
         request: Any,
         operation: str,
         flow_id: str | None,
         requirement: FlowTargetRequirement,
+        timeout: float | None = None,
     ) -> Any:
         try:
-            return method(request)
+            if timeout is None:
+                return method(request)
+            return method(request, timeout=timeout)
         except grpc.RpcError as error:
             raise translate_rpc_error(error, operation, flow_id, requirement) from error