dex-python-sdk 0.2.8__tar.gz → 0.2.9__tar.gz

{dex_python_sdk-0.2.8 → dex_python_sdk-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dex-python-sdk
-Version: 0.2.8
+Version: 0.2.9
 Requires-Dist: grpcio>=1.83.0
 Requires-Dist: grpcio-status>=1.83.0
 Requires-Dist: protobuf>=7.35.1
@@ -17,6 +17,19 @@ Project-URL: Repository, https://github.com/superdurable/dex
 
 # Dex SDK for Python
 
+## Pending Channel messages
+
+`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.
+
+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.
+Attribute locks already select transactional execution, but Channel deletion
+itself does not.
+
 Python SDK for [Dex workflow engine](https://github.com/superdurable/dex)
 
 ## New user contracts

{dex_python_sdk-0.2.8 → dex_python_sdk-0.2.9}/README.md

@@ -1,6 +1,19 @@
 
 # Dex SDK for Python
 
+## Pending Channel messages
+
+`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.
+
+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.
+Attribute locks already select transactional execution, but Channel deletion
+itself does not.
+
 Python SDK for [Dex workflow engine](https://github.com/superdurable/dex)
 
 ## New user contracts

{dex_python_sdk-0.2.8 → dex_python_sdk-0.2.9}/dex/__init__.py

@@ -19,7 +19,7 @@ from dex.attribute import (
     IndexType,
 )
 from dex.blob_cache import BlobCache, BlobCacheConfig, open_blob_cache
-from dex.channel import Channel, ChannelMap
+from dex.channel import Channel, ChannelMap, ChannelMessage
 from dex.client import Client
 from dex.client_options import ClientOptions
 from dex.codec import (
@@ -68,6 +68,7 @@ from dex.runtime_errors import (
     FlowNotFoundError,
     InvalidStepResultError,
     LongPollTimeoutError,
+    ChannelMessageNotFoundError,
     RpcLockConflictError,
     ValueMappingError,
     WorkerInvocationError,
@@ -124,6 +125,8 @@ __all__ = [
     "BufferedTextStream",
     "Channel",
     "ChannelMap",
+    "ChannelMessage",
+    "ChannelMessageNotFoundError",
     "Client",
     "ClientOptions",
     "Codec",

{dex_python_sdk-0.2.8 → dex_python_sdk-0.2.9}/dex/_async_worker_dispatcher.py

@@ -306,6 +306,7 @@ class AsyncWorkerDispatcher(WorkerDispatcher):
             response = pb.InvokeWorkerRPCResponse(
                 upsert_attributes=list(context.attribute_writes.values()),
                 record_events=context.events,
+                delete_from_channel=context.channel_deletions,
                 publish_to_channel=context.publications,
             )
             if isinstance(returned, RPCResult):

{dex_python_sdk-0.2.8 → dex_python_sdk-0.2.9}/dex/_grpc_errors.py

@@ -19,6 +19,7 @@ from grpc_status import rpc_status
 
 from dex.dexpb import dex_pb2 as pb
 from dex.runtime_errors import (
+    ChannelMessageNotFoundError,
     DexServiceError,
     ErrorSubStatus,
     FlowAlreadyStartedError,
@@ -136,6 +137,8 @@ def translate_rpc_error(
         )
     if sub_status is ErrorSubStatus.LONG_POLL_TIMEOUT:
         return LongPollTimeoutError(*parameters)
+    if sub_status is ErrorSubStatus.CHANNEL_MESSAGE_NOT_FOUND:
+        return ChannelMessageNotFoundError(*parameters)
     return DexServiceError(*parameters)
 
 
@@ -219,5 +222,8 @@ def _map_sub_status(value: int) -> ErrorSubStatus:
         int(pb.ERROR_SUB_STATUS_FLOW_NOT_EXISTS): ErrorSubStatus.FLOW_NOT_EXISTS,
         int(pb.ERROR_SUB_STATUS_WORKER_API_ERROR): ErrorSubStatus.WORKER_API_ERROR,
         int(pb.ERROR_SUB_STATUS_LONG_POLL_TIME_OUT): ErrorSubStatus.LONG_POLL_TIMEOUT,
+        int(
+            pb.ERROR_SUB_STATUS_CHANNEL_MESSAGE_NOT_FOUND
+        ): ErrorSubStatus.CHANNEL_MESSAGE_NOT_FOUND,
     }
     return statuses.get(value, ErrorSubStatus.UNCATEGORIZED)

{dex_python_sdk-0.2.8 → dex_python_sdk-0.2.9}/dex/_invocation_context.py

@@ -82,6 +82,7 @@ class InvocationContext:
         self.attribute_writes: dict[str, pb.AttributeWrite] = {}
         self.local_writes: dict[str, pb.KV] = {}
         self.events: list[pb.KV] = []
+        self.channel_deletions: list[pb.ChannelMessageDeletion] = []
         self.publications: list[pb.ChannelMessage] = []
         self._event_names: set[str] = set()
         self._step_output_finalizers: list[_StepOutputFinalizer] = []
@@ -349,6 +350,26 @@ class InvocationContext:
                 size=(current.size if current is not None else 0) + 1
             )
 
+    def _delete_channel_message(
+        self,
+        definition: Channel[object] | ChannelMap[object],
+        instance: str | None,
+        message_id: str,
+    ) -> None:
+        if self._method is not InvocationMethod.RPC:
+            raise ValueError("Channel message deletion requires an RPC Context")
+        self._require_registered(definition)
+        name = self._physical_name(definition, instance)
+        self.channel_deletions.append(
+            pb.ChannelMessageDeletion(
+                channel_name=name,
+                message_id=require_name(message_id),
+            )
+        )
+        current = self._channel_infos.get(name)
+        if current is not None and current.size > 0:
+            self._channel_infos[name] = pb.ChannelInfo(size=current.size - 1)
+
     def _attribute_map_keys(
         self,
         definition: AttributeMap[object],

{dex_python_sdk-0.2.8 → dex_python_sdk-0.2.9}/dex/_utils.py

@@ -13,6 +13,13 @@ def require_name(name: str) -> str:
     return name
 
 
+def require_persistence_definition_name(name: str) -> str:
+    require_name(name)
+    if "/" in name:
+        raise ValueError("persistence definition names must not contain '/'")
+    return name
+
+
 def validate_condition_id(condition_id: str | None) -> None:
     if condition_id is not None and not condition_id:
         raise ValueError("condition ID must not be empty")

{dex_python_sdk-0.2.8 → dex_python_sdk-0.2.9}/dex/_worker_dispatcher.py

@@ -233,6 +233,7 @@ class WorkerDispatcher:
             response = pb.InvokeWorkerRPCResponse(
                 upsert_attributes=list(context.attribute_writes.values()),
                 record_events=context.events,
+                delete_from_channel=context.channel_deletions,
                 publish_to_channel=context.publications,
             )
             if isinstance(returned, RPCResult):

{dex_python_sdk-0.2.8 → dex_python_sdk-0.2.9}/dex/async_client.py

@@ -24,7 +24,7 @@ from dex._value_mapper import ValueMapper
 from dex._worker_dispatcher import WorkerDispatcher
 from dex.attribute import Attribute, AttributeMap, _apply_attribute_store_sync
 from dex.blob_cache import BlobCache
-from dex.channel import Channel, ChannelMap
+from dex.channel import Channel, ChannelMap, ChannelMessage
 from dex.client_options import ClientOptions
 from dex.context import Context
 from dex.dexpb import dex_pb2 as pb
@@ -273,6 +273,7 @@ class AsyncClient:
                     timeout_seconds=timeout,
                     lock_attribute_keys=rpc.locks,
                     request_id=str(uuid4()),
+                    is_transactional=rpc.options.is_transactional,
                 ),
                 "invoke_rpc",
                 flow_id,
@@ -544,6 +545,148 @@ class AsyncClient:
             "none",
         )
 
+    @overload
+    async def get_channel_messages(
+        self,
+        flow_id: str,
+        channel: Channel[ValueT],
+        /,
+        *,
+        run_id: str = "",
+    ) -> tuple[ChannelMessage[ValueT], ...]: ...
+
+    @overload
+    async def get_channel_messages(
+        self,
+        flow_id: str,
+        channel: ChannelMap[ValueT],
+        instance: str,
+        /,
+        *,
+        run_id: str = "",
+    ) -> tuple[ChannelMessage[ValueT], ...]: ...
+
+    async def get_channel_messages(
+        self,
+        flow_id: str,
+        channel: Channel[Any] | ChannelMap[Any],
+        instance: str | None = None,
+        /,
+        *,
+        run_id: str = "",
+    ) -> tuple[ChannelMessage[Any], ...]:
+        """Return every pending message for a Channel in FIFO order.
+
+        Args:
+            flow_id: The non-empty target Flow ID.
+            channel: A typed singleton Channel or ChannelMap definition.
+            instance: Required ChannelMap instance; omit for a singleton Channel.
+            run_id: Optional exact run; ``""`` targets the current run.
+
+        Returns:
+            Immutable typed message envelopes with server-assigned IDs.
+
+        Raises:
+            ValueMappingError: If a pending value cannot be decoded.
+            FlowNotFoundError: If the selected Flow run does not exist.
+            DexServiceError: If FlowService cannot read the queue.
+        """
+        name = self._definition_name(channel, instance)
+        response = cast(
+            pb.GetChannelMessagesResponse,
+            await self._call(
+                self._service.GetChannelMessages,
+                pb.GetChannelMessagesRequest(
+                    flow_id=require_name(flow_id),
+                    run_id=run_id,
+                    channel_name=name,
+                ),
+                "get_channel_messages",
+                flow_id,
+                "existing",
+            ),
+        )
+        codec = self._values.codec(channel.value_type)
+        messages: list[ChannelMessage[Any]] = []
+        for message in response.messages:
+            messages.append(
+                ChannelMessage(
+                    message_id=message.message_id,
+                    value=self._values.decode(
+                        await self._hydrator.hydrate(message.value),
+                        codec,
+                    ),
+                )
+            )
+        return tuple(messages)
+
+    @overload
+    async def delete_channel_message(
+        self,
+        flow_id: str,
+        channel: Channel[Any],
+        message_id: str,
+        /,
+        *,
+        run_id: str = "",
+    ) -> None: ...
+
+    @overload
+    async def delete_channel_message(
+        self,
+        flow_id: str,
+        channel: ChannelMap[Any],
+        instance: str,
+        message_id: str,
+        /,
+        *,
+        run_id: str = "",
+    ) -> None: ...
+
+    async def delete_channel_message(
+        self,
+        flow_id: str,
+        channel: Channel[Any] | ChannelMap[Any],
+        instance_or_message_id: str,
+        message_id: str | None = None,
+        /,
+        *,
+        run_id: str = "",
+    ) -> None:
+        """Delete one pending Channel message by its server-assigned ID.
+
+        Args:
+            flow_id: The non-empty target Flow ID.
+            channel: A typed singleton Channel or ChannelMap definition.
+            instance_or_message_id: Singleton message ID or ChannelMap instance.
+            message_id: ChannelMap message ID; omit for a singleton Channel.
+            run_id: Optional exact run; ``""`` targets the active run.
+
+        Raises:
+            ChannelMessageNotFoundError: If the message is no longer pending.
+            FlowNotActiveError: If the selected Flow run is closed.
+            DexServiceError: If FlowService cannot delete the message.
+        """
+        instance = instance_or_message_id if isinstance(channel, ChannelMap) else None
+        resolved_message_id = (
+            message_id if instance is not None else instance_or_message_id
+        )
+        if resolved_message_id is None:
+            raise ValueError("ChannelMap message ID is required")
+        await self._call(
+            self._service.DeleteChannelMessage,
+            pb.DeleteChannelMessageRequest(
+                flow_id=require_name(flow_id),
+                run_id=run_id,
+                channel_name=self._definition_name(channel, instance),
+                message_id=require_name(resolved_message_id),
+                request_id=str(uuid4()),
+            ),
+            "delete_channel_message",
+            flow_id,
+            "active",
+        )
+
     async def read_stream(
         self,
         flow_id: str,

{dex_python_sdk-0.2.8 → dex_python_sdk-0.2.9}/dex/attribute.py

@@ -14,7 +14,7 @@ from dataclasses import dataclass
 from enum import Enum
 from typing import Any, Generic, TypeVar, cast
 
-from dex._utils import require_name
+from dex._utils import require_name, require_persistence_definition_name
 from dex.context import Context
 from dex.dexpb import dex_pb2 as pb
 
@@ -71,7 +71,7 @@ class Attribute(Generic[ValueT]):
     projects SQL NULL, and failures do not roll back the Flow Attribute.
 
     Attributes:
-        name: The non-empty logical Attribute name, unique within its Flow.
+        name: The non-empty logical Attribute name without ``/``, unique within its Flow.
         value_type: The Python type used to encode and decode values.
         index: Optional search-index configuration; ``None`` disables indexing.
         sync_to_attribute_store: Whether writes are projected to the selected
@@ -90,7 +90,7 @@ class Attribute(Generic[ValueT]):
     sync_to_attribute_store: bool = False
 
     def __post_init__(self) -> None:
-        require_name(self.name)
+        require_persistence_definition_name(self.name)
 
     def get(self, context: Context) -> ValueT:
         """Return the current value from a Step or RPC Context.
@@ -150,7 +150,7 @@ class AttributeMap(Generic[ValueT]):
     do not roll back Flow Attributes.
 
     Attributes:
-        name: The non-empty logical Attribute name, unique within its Flow.
+        name: The non-empty logical Attribute name without ``/``, unique within its Flow.
         value_type: The Python type used for every map instance.
         index: Optional shared search-index configuration.
         sync_to_attribute_store: Whether every instance is projected to the selected
@@ -169,7 +169,7 @@ class AttributeMap(Generic[ValueT]):
     sync_to_attribute_store: bool = False
 
     def __post_init__(self) -> None:
-        require_name(self.name)
+        require_persistence_definition_name(self.name)
 
     def get(self, context: Context, instance: str) -> ValueT:
         """Return one map instance from a Step or RPC Context.

{dex_python_sdk-0.2.8 → dex_python_sdk-0.2.9}/dex/channel.py

@@ -13,13 +13,26 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import Generic, Sequence, TypeVar, cast
 
-from dex._utils import require_name
+from dex._utils import require_persistence_definition_name
 from dex.condition import ChannelCondition, Condition
 from dex.context import Context
 
 ValueT = TypeVar("ValueT")
 
 
+@dataclass(frozen=True)
+class ChannelMessage(Generic[ValueT]):
+    """Represent one pending Channel message and its server-assigned identity.
+
+    Attributes:
+        message_id: UUIDv7 assigned by Dex when the message was published.
+        value: The decoded Channel value.
+    """
+
+    message_id: str
+    value: ValueT
+
+
 @dataclass(frozen=True)
 class Channel(Generic[ValueT]):
     """Define a typed, durable singleton message stream owned by a Flow.
@@ -29,7 +42,7 @@ class Channel(Generic[ValueT]):
     selected values through ``results``.
 
     Attributes:
-        name: The non-empty Channel name, unique within its Flow.
+        name: The non-empty Channel name without ``/``, unique within its Flow.
         value_type: The Python type of every published value.
 
     Examples:
@@ -42,7 +55,7 @@ class Channel(Generic[ValueT]):
     value_type: type[ValueT]
 
     def __post_init__(self) -> None:
-        require_name(self.name)
+        require_persistence_definition_name(self.name)
 
     def publish(self, context: Context, value: ValueT) -> None:
         """Stage one value to append with the current handler decision.
@@ -53,6 +66,19 @@ class Channel(Generic[ValueT]):
         """
         context._publish_channel(self, None, value)
 
+    def delete(self, context: Context, message_id: str) -> None:
+        """Stage deletion of one pending message from an RPC handler.
+
+        Use ``@rpc(is_transactional=True)`` when a missing message must fail the
+        entire RPC without committing its other writes. Step Contexts reject this
+        operation.
+
+        Args:
+            context: The current RPC Context.
+            message_id: Non-empty ID returned by a Client pending-message read.
+        """
+        context._delete_channel_message(self, None, message_id)
+
     def size(self, context: Context) -> int:
         """Return the current number of queued values.
 
@@ -173,7 +199,7 @@ class ChannelMap(Generic[ValueT]):
     Add the ChannelMap definition to the Flow's ``PersistenceSchema``.
 
     Attributes:
-        name: The non-empty Channel name, unique within its Flow.
+        name: The non-empty Channel name without ``/``, unique within its Flow.
         value_type: The Python type of every published value.
 
     Examples:
@@ -186,7 +212,7 @@ class ChannelMap(Generic[ValueT]):
     value_type: type[ValueT]
 
     def __post_init__(self) -> None:
-        require_name(self.name)
+        require_persistence_definition_name(self.name)
 
     def publish(self, context: Context, instance: str, value: ValueT) -> None:
         """Stage a value to append to one ChannelMap instance.
@@ -198,6 +224,16 @@ class ChannelMap(Generic[ValueT]):
         """
         context._publish_channel(self, instance, value)
 
+    def delete(self, context: Context, instance: str, message_id: str) -> None:
+        """Stage deletion of one pending message from a ChannelMap instance.
+
+        Args:
+            context: The current RPC Context.
+            instance: The non-empty logical map key.
+            message_id: Non-empty ID returned by a Client pending-message read.
+        """
+        context._delete_channel_message(self, instance, message_id)
+
     def size(self, context: Context, instance: str) -> int:
         """Return the queued value count for one instance.
 

{dex_python_sdk-0.2.8 → dex_python_sdk-0.2.9}/dex/client.py

@@ -24,7 +24,7 @@ from dex._value_mapper import ValueMapper
 from dex._worker_dispatcher import WorkerDispatcher
 from dex.attribute import Attribute, AttributeMap, _apply_attribute_store_sync
 from dex.blob_cache import BlobCache
-from dex.channel import Channel, ChannelMap
+from dex.channel import Channel, ChannelMap, ChannelMessage
 from dex.client_options import ClientOptions
 from dex.context import Context
 from dex.dexpb import dex_pb2 as pb
@@ -273,6 +273,7 @@ class Client:
                     timeout_seconds=timeout,
                     lock_attribute_keys=rpc.locks,
                     request_id=str(uuid4()),
+                    is_transactional=rpc.options.is_transactional,
                 ),
                 "invoke_rpc",
                 flow_id,
@@ -545,6 +546,146 @@ class Client:
             "none",
         )
 
+    @overload
+    def get_channel_messages(
+        self,
+        flow_id: str,
+        channel: Channel[ValueT],
+        /,
+        *,
+        run_id: str = "",
+    ) -> tuple[ChannelMessage[ValueT], ...]: ...
+
+    @overload
+    def get_channel_messages(
+        self,
+        flow_id: str,
+        channel: ChannelMap[ValueT],
+        instance: str,
+        /,
+        *,
+        run_id: str = "",
+    ) -> tuple[ChannelMessage[ValueT], ...]: ...
+
+    def get_channel_messages(
+        self,
+        flow_id: str,
+        channel: Channel[Any] | ChannelMap[Any],
+        instance: str | None = None,
+        /,
+        *,
+        run_id: str = "",
+    ) -> tuple[ChannelMessage[Any], ...]:
+        """Return every pending message for a Channel in FIFO order.
+
+        Args:
+            flow_id: The non-empty target Flow ID.
+            channel: A typed singleton Channel or ChannelMap definition.
+            instance: Required ChannelMap instance; omit for a singleton Channel.
+            run_id: Optional exact run; ``""`` targets the current run.
+
+        Returns:
+            Immutable typed message envelopes with server-assigned IDs.
+
+        Raises:
+            ValueMappingError: If a pending value cannot be decoded.
+            FlowNotFoundError: If the selected Flow run does not exist.
+            DexServiceError: If FlowService cannot read the queue.
+        """
+        name = self._definition_name(channel, instance)
+        response = cast(
+            pb.GetChannelMessagesResponse,
+            self._call(
+                self._service.GetChannelMessages,
+                pb.GetChannelMessagesRequest(
+                    flow_id=require_name(flow_id),
+                    run_id=run_id,
+                    channel_name=name,
+                ),
+                "get_channel_messages",
+                flow_id,
+                "existing",
+            ),
+        )
+        codec = self._values.codec(channel.value_type)
+        return tuple(
+            ChannelMessage(
+                message_id=message.message_id,
+                value=self._values.decode(
+                    self._hydrator.hydrate(message.value),
+                    codec,
+                ),
+            )
+            for message in response.messages
+        )
+
+    @overload
+    def delete_channel_message(
+        self,
+        flow_id: str,
+        channel: Channel[Any],
+        message_id: str,
+        /,
+        *,
+        run_id: str = "",
+    ) -> None: ...
+
+    @overload
+    def delete_channel_message(
+        self,
+        flow_id: str,
+        channel: ChannelMap[Any],
+        instance: str,
+        message_id: str,
+        /,
+        *,
+        run_id: str = "",
+    ) -> None: ...
+
+    def delete_channel_message(
+        self,
+        flow_id: str,
+        channel: Channel[Any] | ChannelMap[Any],
+        instance_or_message_id: str,
+        message_id: str | None = None,
+        /,
+        *,
+        run_id: str = "",
+    ) -> None:
+        """Delete one pending Channel message by its server-assigned ID.
+
+        Args:
+            flow_id: The non-empty target Flow ID.
+            channel: A typed singleton Channel or ChannelMap definition.
+            instance_or_message_id: Singleton message ID or ChannelMap instance.
+            message_id: ChannelMap message ID; omit for a singleton Channel.
+            run_id: Optional exact run; ``""`` targets the active run.
+
+        Raises:
+            ChannelMessageNotFoundError: If the message is no longer pending.
+            FlowNotActiveError: If the selected Flow run is closed.
+            DexServiceError: If FlowService cannot delete the message.
+        """
+        instance = instance_or_message_id if isinstance(channel, ChannelMap) else None
+        resolved_message_id = (
+            message_id if instance is not None else instance_or_message_id
+        )
+        if resolved_message_id is None:
+            raise ValueError("ChannelMap message ID is required")
+        self._call(
+            self._service.DeleteChannelMessage,
+            pb.DeleteChannelMessageRequest(
+                flow_id=require_name(flow_id),
+                run_id=run_id,
+                channel_name=self._definition_name(channel, instance),
+                message_id=require_name(resolved_message_id),
+                request_id=str(uuid4()),
+            ),
+            "delete_channel_message",
+            flow_id,
+            "active",
+        )
+
     def read_stream(
         self,
         flow_id: str,

{dex_python_sdk-0.2.8 → dex_python_sdk-0.2.9}/dex/context.py

@@ -10,7 +10,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Protocol, Sequence, TypeVar
+from typing import TYPE_CHECKING, Any, Protocol, Sequence, TypeVar
 
 if TYPE_CHECKING:
     from dex.attribute import Attribute, AttributeMap
@@ -210,6 +210,13 @@ class Context(Protocol):
         value: ValueT,
     ) -> None: ...
 
+    def _delete_channel_message(
+        self,
+        definition: Channel[Any] | ChannelMap[Any],
+        instance: str | None,
+        message_id: str,
+    ) -> None: ...
+
     def _channel_size(
         self,
         definition: Channel[object] | ChannelMap[object],