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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dex-python-sdk
-Version: 0.5.0
+Version: 0.7.0
 Requires-Dist: grpcio>=1.83.0
 Requires-Dist: grpcio-status>=1.83.0
 Requires-Dist: protobuf>=7.35.1
@@ -17,13 +17,12 @@ Project-URL: Repository, https://github.com/superdurable/dex
 
 # Dex SDK for Python
 
-## Pending Channel messages
+## Flow state I/O
 
-`Client.get_channel_messages(flow_id, channel)` returns typed `ChannelMessage`
-envelopes in FIFO order. Each envelope contains the decoded value and the UUIDv7
-assigned by Dex. `Client.delete_channel_message` deletes only a still-pending
-message and raises `ChannelMessageNotFoundError` after consumption or another
-deletion.
+Applications read and write Flow state through typed RPCs. Client and AsyncClient
+do not expose direct Attribute reads or writes, Channel publication, or
+pending-message mutation. This keeps each external state transition behind a
+Flow-owned method.
 
 RPC handlers can stage `channel.delete(context, message_id)`. Declare the RPC as
 `@rpc(is_transactional=True)` when a missing message must abort its other writes.
@@ -279,6 +278,15 @@ message = client.read_stream(flow_id, progress)
 print(message.source)
 ```
 
+`Client.read_stream` and `AsyncClient.read_stream` move forward one message at
+a time and can long-poll. Their `list_stream_messages` methods return one
+non-blocking newest-first retained page. Pass the registered `Stream`, a
+positive page size, and an empty token for the first page. Pass
+`StreamMessagesPage.next_page_token` unchanged to read older messages until it
+is empty. The server caps page size at 1000 by default. A trimmed anchor returns
+an empty page, and newer concurrent writes do not enter an existing older-page
+chain.
+
 ### Canceling Step executions
 
 A successful Step can cancel queued or active executions while continuing with
@@ -353,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:
@@ -392,14 +411,14 @@ SubFlow.
 ### Errors
 
 Client calls raise concrete `DexServiceError` subclasses. Existing-Flow reads
-(`get_attribute`, `describe_flow`, `wait_for_flow`, and `time_travel`) raise
+(`describe_flow`, `wait_for_flow`, and `time_travel`) raise
 `FlowNotFoundError` when the Flow does not exist. Mutations, RPCs, timer/Step
 waits, config updates, and continue-as-new triggers raise
 `FlowNotActiveError` when no running Flow can accept the operation.
 
 ```python
 try:
-    client.publish(flow_id, orders.approved, order_id)
+    client.invoke_rpc(orders.update_order, order_id, update)
 except dex.FlowNotActiveError:
     # The Flow is missing or already closed.
     pass

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

@@ -1,13 +1,12 @@
 
 # Dex SDK for Python
 
-## Pending Channel messages
+## Flow state I/O
 
-`Client.get_channel_messages(flow_id, channel)` returns typed `ChannelMessage`
-envelopes in FIFO order. Each envelope contains the decoded value and the UUIDv7
-assigned by Dex. `Client.delete_channel_message` deletes only a still-pending
-message and raises `ChannelMessageNotFoundError` after consumption or another
-deletion.
+Applications read and write Flow state through typed RPCs. Client and AsyncClient
+do not expose direct Attribute reads or writes, Channel publication, or
+pending-message mutation. This keeps each external state transition behind a
+Flow-owned method.
 
 RPC handlers can stage `channel.delete(context, message_id)`. Declare the RPC as
 `@rpc(is_transactional=True)` when a missing message must abort its other writes.
@@ -263,6 +262,15 @@ message = client.read_stream(flow_id, progress)
 print(message.source)
 ```
 
+`Client.read_stream` and `AsyncClient.read_stream` move forward one message at
+a time and can long-poll. Their `list_stream_messages` methods return one
+non-blocking newest-first retained page. Pass the registered `Stream`, a
+positive page size, and an empty token for the first page. Pass
+`StreamMessagesPage.next_page_token` unchanged to read older messages until it
+is empty. The server caps page size at 1000 by default. A trimmed anchor returns
+an empty page, and newer concurrent writes do not enter an existing older-page
+chain.
+
 ### Canceling Step executions
 
 A successful Step can cancel queued or active executions while continuing with
@@ -337,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:
@@ -376,14 +395,14 @@ SubFlow.
 ### Errors
 
 Client calls raise concrete `DexServiceError` subclasses. Existing-Flow reads
-(`get_attribute`, `describe_flow`, `wait_for_flow`, and `time_travel`) raise
+(`describe_flow`, `wait_for_flow`, and `time_travel`) raise
 `FlowNotFoundError` when the Flow does not exist. Mutations, RPCs, timer/Step
 waits, config updates, and continue-as-new triggers raise
 `FlowNotActiveError` when no running Flow can accept the operation.
 
 ```python
 try:
-    client.publish(flow_id, orders.approved, order_id)
+    client.invoke_rpc(orders.update_order, order_id, update)
 except dex.FlowNotActiveError:
     # The Flow is missing or already closed.
     pass

{dex_python_sdk-0.5.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.5.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)