dex-python-sdk 0.4.0__tar.gz → 0.6.0__tar.gz

{dex_python_sdk-0.4.0 → dex_python_sdk-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dex-python-sdk
-Version: 0.4.0
+Version: 0.6.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
@@ -392,14 +400,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.4.0 → dex_python_sdk-0.6.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
@@ -376,14 +384,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.4.0 → dex_python_sdk-0.6.0}/dex/__init__.py

@@ -103,6 +103,7 @@ from dex.stream import (
     BufferedTextStream,
     Stream,
     StreamMessage,
+    StreamMessagesPage,
 )
 from dex.subflow import SubFlow
 from dex.timer import Timer
@@ -190,6 +191,7 @@ __all__ = [
     "StepOptions",
     "Stream",
     "StreamMessage",
+    "StreamMessagesPage",
     "StopFlowOptions",
     "StopType",
     "Timer",

{dex_python_sdk-0.4.0 → dex_python_sdk-0.6.0}/dex/async_client.py

@@ -25,7 +25,7 @@ from dex._worker_dispatcher import WorkerDispatcher
 from dex.attribute import Attribute, AttributeMap, _apply_attribute_store_sync
 from dex.attribute_match import AttributeMatch, _encode_attribute_match
 from dex.blob_cache import BlobCache
-from dex.channel import Channel, ChannelMap, ChannelMessage
+from dex.channel import Channel, ChannelMap
 from dex.client_options import ClientOptions
 from dex.context import Context
 from dex.dexpb import dex_pb2 as pb
@@ -48,7 +48,7 @@ from dex.flow_result import FlowResult, flow_result_from_proto
 from dex.runtime_errors import FlowErrorType
 from dex.step import RetryPolicy, StepDurability
 from dex.step_execution import StepExecutionId, TimerId
-from dex.stream import Stream, StreamMessage
+from dex.stream import Stream, StreamMessage, StreamMessagesPage
 
 InputT = TypeVar("InputT")
 OutputT = TypeVar("OutputT")
@@ -307,223 +307,6 @@ class AsyncClient:
             rpc.output_codec,
         )
 
-    @overload
-    async def get_attribute(
-        self,
-        flow_id: str,
-        attribute: Attribute[ValueT],
-        *,
-        run_id: str = "",
-    ) -> ValueT: ...
-
-    @overload
-    async def get_attribute(
-        self,
-        flow_id: str,
-        attribute: AttributeMap[ValueT],
-        instance: str,
-        *,
-        run_id: str = "",
-    ) -> ValueT: ...
-
-    async def get_attribute(
-        self,
-        flow_id: str,
-        attribute: Attribute[Any] | AttributeMap[Any],
-        instance: str | None = None,
-        *,
-        run_id: str = "",
-    ) -> Any:
-        """Await one decoded Attribute or AttributeMap instance.
-
-        Args:
-            flow_id: The non-empty target Flow ID.
-            attribute: A typed singleton Attribute or AttributeMap definition.
-            instance: The map instance. Omit it for a singleton Attribute. Slash is prohibited because it is a reserved character.
-            run_id: Optional exact run; ``""`` targets the current run.
-
-        Returns:
-            The decoded value, or ``None`` when unset.
-
-        Raises:
-            TypeError: If singleton/map arguments do not match the definition.
-            ValueMappingError: If the stored value cannot be decoded.
-            FlowNotFoundError: If ``flow_id`` does not exist.
-            DexServiceError: If FlowService cannot perform the request.
-        """
-        key = self._definition_name(attribute, instance)
-        response = cast(
-            pb.GetAttributesResponse,
-            await self._call(
-                self._service.GetAttributes,
-                pb.GetAttributesRequest(
-                    flow_id=require_name(flow_id),
-                    run_id=run_id,
-                    keys=[key],
-                ),
-                "get_attribute",
-                flow_id,
-                "existing",
-            ),
-        )
-        if not response.attributes:
-            return None
-        value = await self._hydrator.hydrate(response.attributes[0].value)
-        return self._values.decode(value, self._values.codec(attribute.value_type))
-
-    @overload
-    async def set_attribute(
-        self,
-        flow_id: str,
-        attribute: Attribute[ValueT],
-        value: ValueT,
-        /,
-        *,
-        run_id: str = "",
-    ) -> None: ...
-
-    @overload
-    async def set_attribute(
-        self,
-        flow_id: str,
-        attribute: AttributeMap[ValueT],
-        instance: str,
-        value: ValueT,
-        /,
-        *,
-        run_id: str = "",
-    ) -> None: ...
-
-    async def set_attribute(
-        self,
-        flow_id: str,
-        attribute: Attribute[Any] | AttributeMap[Any],
-        /,
-        *args: object,
-        run_id: str = "",
-    ) -> None:
-        """Write one Attribute or AttributeMap instance on an active Flow.
-
-        Singleton form is ``set_attribute(flow_id, attribute, value)``; map form is
-        ``set_attribute(flow_id, attribute_map, instance, value)``.
-
-        Args:
-            flow_id: The non-empty target Flow ID.
-            attribute: A typed singleton Attribute or AttributeMap definition.
-            *args: The value, or a map instance followed by its value.
-            run_id: Optional exact run; ``""`` targets the active run.
-
-        Raises:
-            TypeError: If arguments or value type are invalid.
-            ValueMappingError: If the value cannot be encoded.
-            FlowNotActiveError: If the selected Flow run is closed.
-            DexServiceError: If FlowService cannot apply the write.
-        """
-        instance, value = self._definition_value(attribute, args)
-        write = pb.AttributeWrite(
-            key=self._definition_name(attribute, instance),
-            value=self._values.encode(
-                value,
-                self._values.codec(attribute.value_type),
-            ),
-        )
-        index = self._values.index_config(
-            attribute.index,
-            isinstance(attribute, AttributeMap),
-        )
-        if index is not None:
-            write.index_config.CopyFrom(index)
-        _apply_attribute_store_sync(write, attribute)
-        await self._call(
-            self._service.SetAttributes,
-            pb.SetAttributesRequest(
-                flow_id=require_name(flow_id),
-                run_id=run_id,
-                attributes=[write],
-                request_id=str(uuid4()),
-            ),
-            "set_attribute",
-            flow_id,
-            "active",
-        )
-
-    @overload
-    async def publish(
-        self,
-        flow_id: str,
-        channel: Channel[ValueT],
-        /,
-        *values: ValueT,
-        run_id: str = "",
-    ) -> None: ...
-
-    @overload
-    async def publish(
-        self,
-        flow_id: str,
-        channel: ChannelMap[ValueT],
-        instance: str,
-        /,
-        *values: ValueT,
-        run_id: str = "",
-    ) -> None: ...
-
-    async def publish(
-        self,
-        flow_id: str,
-        channel: Channel[Any] | ChannelMap[Any],
-        /,
-        *args: object,
-        run_id: str = "",
-    ) -> None:
-        """Append one or more typed values to a Channel.
-
-        Singleton form supplies values directly; ChannelMap form supplies an instance
-        followed by values. Dex preserves argument order within the request.
-
-        Args:
-            flow_id: The non-empty target Flow ID.
-            channel: A typed singleton Channel or ChannelMap definition.
-            *args: Values, or a map instance followed by one or more values.
-            run_id: Optional exact run; ``""`` targets the active run.
-
-        Raises:
-            ValueError: If no value is passed or a name is empty.
-            TypeError: If map arguments or value types are invalid.
-            ValueMappingError: If a value cannot be encoded.
-            FlowNotActiveError: If the selected Flow run is closed.
-            DexServiceError: If FlowService cannot publish the batch.
-        """
-        if isinstance(channel, ChannelMap):
-            if len(args) < 2 or not isinstance(args[0], str):
-                raise TypeError("ChannelMap publish requires instance and values")
-            instance = args[0]
-            values = args[1:]
-        else:
-            instance = None
-            values = args
-        if not values:
-            raise ValueError("publish requires at least one value")
-        name = self._definition_name(channel, instance)
-        codec = self._values.codec(channel.value_type)
-        await self._call(
-            self._service.PublishToChannel,
-            pb.PublishToChannelRequest(
-                flow_id=require_name(flow_id),
-                run_id=run_id,
-                messages=[
-                    pb.ChannelMessage(
-                        channel_name=name,
-                        value=self._values.encode(value, codec),
-                    )
-                    for value in values
-                ],
-            ),
-            "publish",
-            flow_id,
-            "active",
-        )
-
     async def write_stream(
         self,
         flow_id: str,
@@ -565,148 +348,6 @@ 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,
@@ -767,6 +408,73 @@ class AsyncClient:
             response.message.source,
         )
 
+    async def list_stream_messages(
+        self,
+        flow_id: str,
+        stream: Stream[ValueT],
+        page_size: int,
+        before_page_token: str = "",
+    ) -> StreamMessagesPage[ValueT]:
+        """Await one newest-first page of retained Stream messages without waiting for writes.
+
+        An empty token starts at the retained tail. Pass the returned page token
+        unchanged to read older messages. Trimming may remove messages between pages.
+
+        Args:
+            flow_id: Logical Flow instance ID used as the Stream instance key.
+            stream: Exact Stream object registered in one Flow schema.
+            page_size: Positive maximum message count within the server-configured limit.
+            before_page_token: Opaque token from the preceding page, or ``""`` first.
+
+        Returns:
+            Decoded messages in newest-first order and the next-page token.
+
+        Raises:
+            ValueError: If ``page_size`` is not positive.
+            FlowDefinitionError: If the Stream is not registered.
+            ValueMappingError: If a retained message cannot be decoded.
+            DexServiceError: If FlowService cannot list the Stream.
+        """
+        if page_size < 1:
+            raise ValueError("Stream page size must be positive")
+        flow = self.registry._flow_for_stream(stream)
+        response = cast(
+            pb.ListStreamMessagesResponse,
+            await self._call(
+                self._service.ListStreamMessages,
+                pb.ListStreamMessagesRequest(
+                    flow_id=require_name(flow_id),
+                    flow_type=flow.name,
+                    stream_name=stream.name,
+                    page_size=page_size,
+                    before_page_token=before_page_token,
+                ),
+                "list_stream_messages",
+                flow_id,
+                "none",
+            ),
+        )
+        messages: list[StreamMessage[ValueT]] = []
+        for message in response.messages:
+            if (
+                not message.HasField("value")
+                or not message.HasField("created_time")
+                or not message.resume_token
+            ):
+                raise ValueError("Dex returned an incomplete Stream message")
+            messages.append(
+                StreamMessage(
+                    self._values.decode(
+                        message.value,
+                        self._values.codec(stream.value_type),
+                    ),
+                    message.resume_token,
+                    message.created_time.ToDatetime(tzinfo=timezone.utc),
+                    message.source,
+                )
+            )
+        return StreamMessagesPage(messages, response.next_page_token)
+
     async def wait_for_flow(
         self,
         flow_id: str,
@@ -1395,21 +1103,6 @@ class AsyncClient:
             raise ValueError("static definition cannot use an instance")
         return definition.name
 
-    @staticmethod
-    def _definition_value(
-        definition: Attribute[Any] | AttributeMap[Any],
-        args: tuple[object, ...],
-    ) -> tuple[str | None, object]:
-        if isinstance(definition, Attribute) and len(args) == 1:
-            return None, args[0]
-        if (
-            isinstance(definition, AttributeMap)
-            and len(args) == 2
-            and isinstance(args[0], str)
-        ):
-            return args[0], args[1]
-        raise TypeError("set_attribute received invalid arguments")
-
     @staticmethod
     def _attribute_wait_arguments(
         definition: Attribute[Any] | AttributeMap[Any],