dex-python-sdk 0.12.0__tar.gz → 0.13.0__tar.gz

{dex_python_sdk-0.12.0 → dex_python_sdk-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dex-python-sdk
-Version: 0.12.0
+Version: 0.13.0
 Requires-Dist: grpcio>=1.83.0
 Requires-Dist: grpcio-status>=1.83.0
 Requires-Dist: protobuf>=7.35.1
@@ -58,6 +58,30 @@ 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.
 
+### Invocation-time map instances
+
+The `@rpc` decorator remains the registration-time contract for timeout,
+transactionality, locks, and fixed state loads. Pass frozen `RPCInvokeOptions`
+through the keyword-only `options` argument when the caller chooses an exact map
+instance at runtime:
+
+```python
+options = dex.RPCInvokeOptions(
+    lock_attribute_map_instances=(profiles.lock(partition_name),),
+    load_attribute_map_instances=(profiles.load(partition_name),),
+)
+result = client.invoke_rpc(
+    directory.upsert_customer_profile,
+    flow_id,
+    profile,
+    options=options,
+)
+```
+
+`Client` and `AsyncClient` union, sort, and deduplicate these selections with the
+registered ones. Locking and loading are independent; read-modify-write handlers
+need both for the same instance.
+
 ## Step and timeout-handler state loading
 
 `StepOptions` provides the same five selections independently for `wait_for` and
@@ -363,11 +387,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.12.0 → dex_python_sdk-0.13.0}/README.md

@@ -42,6 +42,30 @@ 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.
 
+### Invocation-time map instances
+
+The `@rpc` decorator remains the registration-time contract for timeout,
+transactionality, locks, and fixed state loads. Pass frozen `RPCInvokeOptions`
+through the keyword-only `options` argument when the caller chooses an exact map
+instance at runtime:
+
+```python
+options = dex.RPCInvokeOptions(
+    lock_attribute_map_instances=(profiles.lock(partition_name),),
+    load_attribute_map_instances=(profiles.load(partition_name),),
+)
+result = client.invoke_rpc(
+    directory.upsert_customer_profile,
+    flow_id,
+    profile,
+    options=options,
+)
+```
+
+`Client` and `AsyncClient` union, sort, and deduplicate these selections with the
+registered ones. Locking and loading are independent; read-modify-write handlers
+need both for the same instance.
+
 ## Step and timeout-handler state loading
 
 `StepOptions` provides the same five selections independently for `wait_for` and
@@ -347,11 +371,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.12.0 → dex_python_sdk-0.13.0}/dex/__init__.py

@@ -74,11 +74,12 @@ from dex.runtime_errors import (
     FlowNotFoundError,
     InvalidStepResultError,
     LongPollTimeoutError,
+    RequestTimeoutError,
     RpcLockConflictError,
     ValueMappingError,
-    WaitHandlerTimeoutError,
     WorkerInvocationError,
 )
+from dex.rpc_invoke_options import RPCInvokeOptions
 from dex.step import (
     RetryPolicy,
     Step,
@@ -166,9 +167,10 @@ __all__ = [
     "IndexType",
     "JsonCodec",
     "LongPollTimeoutError",
-    "WaitHandlerTimeoutError",
+    "RequestTimeoutError",
     "PersistenceSchema",
     "RPCResult",
+    "RPCInvokeOptions",
     "RecoveryErrorInfo",
     "RetryAfterError",
     "RpcLockConflictError",

{dex_python_sdk-0.12.0 → dex_python_sdk-0.13.0}/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.12.0 → dex_python_sdk-0.13.0}/dex/async_client.py

@@ -45,14 +45,16 @@ 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.rpc_invoke_options import RPCInvokeOptions
 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")
@@ -213,6 +215,7 @@ class AsyncClient:
         input: InputT,
         *,
         run_id: str = "",
+        options: RPCInvokeOptions = RPCInvokeOptions(),
     ) -> OutputT: ...
 
     @overload
@@ -222,6 +225,7 @@ class AsyncClient:
         flow_id: str,
         *,
         run_id: str = "",
+        options: RPCInvokeOptions = RPCInvokeOptions(),
     ) -> OutputT: ...
 
     @overload
@@ -232,6 +236,7 @@ class AsyncClient:
         input: InputT,
         *,
         run_id: str = "",
+        options: RPCInvokeOptions = RPCInvokeOptions(),
     ) -> None: ...
 
     @overload
@@ -241,6 +246,7 @@ class AsyncClient:
         flow_id: str,
         *,
         run_id: str = "",
+        options: RPCInvokeOptions = RPCInvokeOptions(),
     ) -> None: ...
 
     async def invoke_rpc(
@@ -250,6 +256,7 @@ class AsyncClient:
         input: object = None,
         *,
         run_id: str = "",
+        options: RPCInvokeOptions = RPCInvokeOptions(),
     ) -> Any:
         """Invoke a registered RPC and await its typed result.
 
@@ -266,6 +273,7 @@ class AsyncClient:
             input: The annotated input, or ``None`` for an input-free RPC.
             run_id: Optional exact run. With ``""``, the server resolves the current
                 execution.
+            options: Additive runtime AttributeMap locks and exact map-instance loads.
 
         Returns:
             The decoded ``RPCResult.output``, or ``None`` for a no-output RPC.
@@ -278,7 +286,12 @@ class AsyncClient:
             DexServiceError: If the selected path requires an active execution or the
                 service call otherwise fails.
         """
-        _, rpc = self.registry._rpc_for_method(rpc_method)
+        registered_flow, rpc = self.registry._rpc_for_method(rpc_method)
+        (
+            invocation_locks,
+            invocation_attribute_map_loads,
+            invocation_channel_map_loads,
+        ) = self.registry._resolve_rpc_invoke_options(registered_flow, options)
         encoded_input = (
             self._values.encode(input, rpc.input_codec)
             if rpc.input_codec is not None
@@ -299,12 +312,28 @@ class AsyncClient:
                     rpc_name=rpc.name,
                     input=encoded_input,
                     timeout_seconds=timeout,
-                    lock_attribute_keys=rpc.locks,
+                    lock_attribute_keys=tuple(
+                        sorted(set(rpc.locks + invocation_locks))
+                    ),
                     request_id=str(uuid4()),
                     is_transactional=rpc.options.is_transactional,
-                    load_attribute_map_instances=rpc.load_attribute_map_instances,
+                    load_attribute_map_instances=tuple(
+                        sorted(
+                            set(
+                                rpc.load_attribute_map_instances
+                                + invocation_attribute_map_loads
+                            )
+                        )
+                    ),
                     load_channel_names=rpc.load_channel_names,
-                    load_channel_map_instances=rpc.load_channel_map_instances,
+                    load_channel_map_instances=tuple(
+                        sorted(
+                            set(
+                                rpc.load_channel_map_instances
+                                + invocation_channel_map_loads
+                            )
+                        )
+                    ),
                 ),
                 "invoke_rpc",
                 flow_id,
@@ -738,27 +767,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 +801,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 +837,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 +870,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 +878,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 +915,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 +940,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 +956,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 +978,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 +1309,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