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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dex-python-sdk
-Version: 0.12.1
+Version: 0.13.10
 Requires-Dist: grpcio>=1.83.0
 Requires-Dist: grpcio-status>=1.83.0
 Requires-Dist: protobuf>=7.35.1
@@ -58,6 +58,34 @@ 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.
+
+See the runnable [sequential chunking](../examples/python/dex_examples/patterns/sequentially-chunked-attribute-map)
+and [hash partitioning](../examples/python/dex_examples/patterns/hash-partitioned-attribute-map)
+patterns for complete async call sites.
+
 ## Step and timeout-handler state loading
 
 `StepOptions` provides the same five selections independently for `wait_for` and

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

@@ -42,6 +42,34 @@ 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.
+
+See the runnable [sequential chunking](../examples/python/dex_examples/patterns/sequentially-chunked-attribute-map)
+and [hash partitioning](../examples/python/dex_examples/patterns/hash-partitioned-attribute-map)
+patterns for complete async call sites.
+
 ## Step and timeout-handler state loading
 
 `StepOptions` provides the same five selections independently for `wait_for` and

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

@@ -79,6 +79,7 @@ from dex.runtime_errors import (
     ValueMappingError,
     WorkerInvocationError,
 )
+from dex.rpc_invoke_options import RPCInvokeOptions
 from dex.step import (
     RetryPolicy,
     Step,
@@ -169,6 +170,7 @@ __all__ = [
     "RequestTimeoutError",
     "PersistenceSchema",
     "RPCResult",
+    "RPCInvokeOptions",
     "RecoveryErrorInfo",
     "RetryAfterError",
     "RpcLockConflictError",

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

@@ -46,6 +46,7 @@ from dex.flow_options import (
 )
 from dex.flow_result import FlowResult, flow_result_from_proto
 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
@@ -214,6 +215,7 @@ class AsyncClient:
         input: InputT,
         *,
         run_id: str = "",
+        options: RPCInvokeOptions = RPCInvokeOptions(),
     ) -> OutputT: ...
 
     @overload
@@ -223,6 +225,7 @@ class AsyncClient:
         flow_id: str,
         *,
         run_id: str = "",
+        options: RPCInvokeOptions = RPCInvokeOptions(),
     ) -> OutputT: ...
 
     @overload
@@ -233,6 +236,7 @@ class AsyncClient:
         input: InputT,
         *,
         run_id: str = "",
+        options: RPCInvokeOptions = RPCInvokeOptions(),
     ) -> None: ...
 
     @overload
@@ -242,6 +246,7 @@ class AsyncClient:
         flow_id: str,
         *,
         run_id: str = "",
+        options: RPCInvokeOptions = RPCInvokeOptions(),
     ) -> None: ...
 
     async def invoke_rpc(
@@ -251,6 +256,7 @@ class AsyncClient:
         input: object = None,
         *,
         run_id: str = "",
+        options: RPCInvokeOptions = RPCInvokeOptions(),
     ) -> Any:
         """Invoke a registered RPC and await its typed result.
 
@@ -267,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.
@@ -279,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
@@ -300,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,

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

@@ -46,6 +46,7 @@ from dex.flow_options import (
 )
 from dex.flow_result import FlowResult, flow_result_from_proto
 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
@@ -213,6 +214,7 @@ class Client:
         input: InputT,
         *,
         run_id: str = "",
+        options: RPCInvokeOptions = RPCInvokeOptions(),
     ) -> OutputT: ...
 
     @overload
@@ -222,6 +224,7 @@ class Client:
         flow_id: str,
         *,
         run_id: str = "",
+        options: RPCInvokeOptions = RPCInvokeOptions(),
     ) -> OutputT: ...
 
     @overload
@@ -232,6 +235,7 @@ class Client:
         input: InputT,
         *,
         run_id: str = "",
+        options: RPCInvokeOptions = RPCInvokeOptions(),
     ) -> None: ...
 
     @overload
@@ -241,6 +245,7 @@ class Client:
         flow_id: str,
         *,
         run_id: str = "",
+        options: RPCInvokeOptions = RPCInvokeOptions(),
     ) -> None: ...
 
     def invoke_rpc(
@@ -250,6 +255,7 @@ class Client:
         input: object = None,
         *,
         run_id: str = "",
+        options: RPCInvokeOptions = RPCInvokeOptions(),
     ) -> Any:
         """Synchronously invoke a registered RPC on a Flow execution.
 
@@ -266,6 +272,7 @@ class Client:
             input: The annotated RPC 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 +285,12 @@ class Client:
             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 +311,28 @@ class Client:
                     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,

{dex_python_sdk-0.12.1 → dex_python_sdk-0.13.10}/dex/flow.py

@@ -41,6 +41,7 @@ from dex.codec import Codec, CodecRegistry
 from dex.context import AsyncContext, Context
 from dex.dexpb import dex_pb2 as pb
 from dex.runtime_errors import FlowDefinitionError
+from dex.rpc_invoke_options import RPCInvokeOptions
 from dex.step import Step, StepDecision, StepList, StepMovement, StepOutput, _StepDef
 from dex.stream import Stream
 from dex.wait import Wait
@@ -969,3 +970,65 @@ class Registry:
                 if registered_function is function:
                     return flow, registered_rpc
         raise FlowDefinitionError("RPC method is not registered")
+
+    def _resolve_rpc_invoke_options(
+        self,
+        flow: _RegisteredFlow,
+        options: RPCInvokeOptions,
+    ) -> tuple[tuple[str, ...], tuple[str, ...], tuple[str, ...]]:
+        lock_attribute_map_instances: list[str] = []
+        for lock in options.lock_attribute_map_instances:
+            if not isinstance(lock, AttributeLock) or not isinstance(
+                lock.attribute, AttributeMap
+            ):
+                raise FlowDefinitionError(
+                    "RPCInvokeOptions lock must target an AttributeMap instance"
+                )
+            if lock.instance is None:
+                raise FlowDefinitionError(
+                    "RPCInvokeOptions AttributeMap lock needs an instance"
+                )
+            self._require_rpc_invoke_definition(flow, lock.attribute, "AttributeMap")
+            lock_attribute_map_instances.append(
+                lock.attribute.load(lock.instance).physical_name
+            )
+
+        load_attribute_map_instances: list[str] = []
+        for attribute_map_load in options.load_attribute_map_instances:
+            if not isinstance(attribute_map_load, AttributeMapLoad):
+                raise FlowDefinitionError(
+                    "RPCInvokeOptions has an invalid AttributeMap load"
+                )
+            self._require_rpc_invoke_definition(
+                flow, attribute_map_load.attribute_map, "AttributeMap"
+            )
+            load_attribute_map_instances.append(attribute_map_load.physical_name)
+
+        load_channel_map_instances: list[str] = []
+        for channel_map_load in options.load_channel_map_instances:
+            if not isinstance(channel_map_load, ChannelMapLoad):
+                raise FlowDefinitionError(
+                    "RPCInvokeOptions has an invalid ChannelMap load"
+                )
+            self._require_rpc_invoke_definition(
+                flow, channel_map_load.channel_map, "ChannelMap"
+            )
+            load_channel_map_instances.append(channel_map_load.physical_name)
+
+        return (
+            tuple(sorted(set(lock_attribute_map_instances))),
+            tuple(sorted(set(load_attribute_map_instances))),
+            tuple(sorted(set(load_channel_map_instances))),
+        )
+
+    @staticmethod
+    def _require_rpc_invoke_definition(
+        flow: _RegisteredFlow,
+        definition: object,
+        kind: str,
+    ) -> None:
+        registered = flow.persistence.get(getattr(definition, "name", ""))
+        if registered is not definition:
+            raise FlowDefinitionError(
+                f"Flow {flow.name} does not register {kind} definition"
+            )

dex_python_sdk-0.13.10/dex/rpc_invoke_options.py

@@ -0,0 +1,42 @@
+# Copyright (c) 2026 Super Durable, Inc.
+#
+# Licensed under the Sustainable Use License 1.0.
+# You may not use this file except in compliance with the License.
+# See the LICENSE file in the repository root.
+#
+# SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from dex.attribute import AttributeLock, AttributeMapLoad
+from dex.channel import ChannelMapLoad
+
+
+@dataclass(frozen=True)
+class RPCInvokeOptions:
+    """Add runtime-selected map instances to one RPC invocation.
+
+    Dex unions these selections with the RPC decorator's fixed locks and state loads,
+    then sorts and deduplicates their physical names. Locking and loading are
+    independent. A read-modify-write handler must include the same AttributeMap
+    instance in both collections.
+
+    Attributes:
+        lock_attribute_map_instances: AttributeMap instance locks for this call.
+        load_attribute_map_instances: Exact AttributeMap instance snapshots.
+        load_channel_map_instances: Exact ChannelMap pending-message snapshots.
+
+    Examples:
+        >>> options = RPCInvokeOptions(
+        ...     lock_attribute_map_instances=(profiles.lock(partition),),
+        ...     load_attribute_map_instances=(profiles.load(partition),),
+        ... )
+        >>> client.invoke_rpc(directory.upsert_customer_profile, flow_id, profile,
+        ...                   options=options)
+    """
+
+    lock_attribute_map_instances: tuple[AttributeLock, ...] = ()
+    load_attribute_map_instances: tuple[AttributeMapLoad, ...] = ()
+    load_channel_map_instances: tuple[ChannelMapLoad, ...] = ()

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