dex-python-sdk 1.28.1__tar.gz → 1.29.0__tar.gz

{dex_python_sdk-1.28.1 → dex_python_sdk-1.29.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dex-python-sdk
-Version: 1.28.1
+Version: 1.29.0
 Requires-Dist: grpcio>=1.83.0
 Requires-Dist: grpcio-status>=1.83.0
 Requires-Dist: protobuf>=7.35.1
@@ -244,10 +244,38 @@ to assess reserve pressure. It never resets and remains available after shutdown
 
 ## Flow state I/O
 
-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.
+Applications write Flow state through typed RPCs. Client and AsyncClient do not
+expose direct Attribute writes, Channel publication, or pending-message
+mutation. This keeps each external state transition behind a Flow-owned method.
+
+Read committed Attribute values without an RPC through `get_attributes`. Pass
+one or more singleton Attributes or AttributeMap instances selected with
+`AttributeMap.instance(key)`:
+
+```python
+values = client.get_attributes(flow_id, ORDER_STATUS, NOTES.instance("n1"))
+status = values.get(ORDER_STATUS, "new")
+if NOTES.instance("n1") in values:
+    note = values[NOTES.instance("n1")]
+```
+
+`AsyncClient.get_attributes` is the awaitable form. There is no single-Attribute
+method; pass one read to read one value. The Client sends every key in one
+request and no Worker runs, so all values come from the same committed state.
+The call reads the current run, or the latest run when no run is open, and a
+closed run stays readable until Dex purges it. Unlike a read inside an RPC
+handler, it never sees writes that a running Step or RPC has not committed.
+
+The result `AttributeValues` is keyed by the reads passed to the call, and type
+checkers infer each value type from its key. An unset Attribute or map instance
+is absent: `values[key]` raises `KeyError`, `values.get(key)` returns `None`,
+`values.get(key, default)` returns `default`, and `key in values` is `False`. A
+stored value that decodes to `None` is still present. Each read must equal a
+definition declared by some Flow in the Client's Registry, with the same name,
+value type, index, `sync_to_attribute_store`, and `hard_delete_on_null`;
+otherwise the call raises `FlowDefinitionError` before contacting Dex. Two
+reads of the same key, or no read at all, raise `ValueError`. Large values are
+resolved through LoadBlobs and the BlobCache before decoding.
 
 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.
@@ -439,7 +467,8 @@ the Attribute or setting it to `None` permanently deletes the stored value, and
 deleted value reads as absent. Only string and object values, including
 `bytes`, are supported; `int`, `bool`, and `float` types are rejected. The
 option cannot be combined with an index or `sync_to_attribute_store`, and
-`wait_for_attribute_match` rejects it. Handlers receive the value inline, and
+`wait_for_attribute_match` rejects it. `get_attributes` reads it; Dex resolves
+the stored value. Handlers and `get_attributes` receive the value inline, and
 the SDK never stores it in the local blob cache.
 
 Hard-delete writes require a Server with an enabled blob store and Server
@@ -796,7 +825,7 @@ SubFlow.
 ### Errors
 
 Client calls raise concrete `DexServiceError` subclasses. Existing-Flow reads
-(`describe_flow`, `wait_for_flow`, and `time_travel`) raise
+(`describe_flow`, `get_attributes`, `wait_for_flow`, and `time_travel`) raise
 `FlowNotFoundError` when the Flow does not exist. Mutations, RPCs, timer/Step
 waits, config updates, and state-transfer triggers raise
 `FlowNotActiveOrNotFoundError` when no running Flow can accept the operation.

{dex_python_sdk-1.28.1 → dex_python_sdk-1.29.0}/README.md

@@ -228,10 +228,38 @@ to assess reserve pressure. It never resets and remains available after shutdown
 
 ## Flow state I/O
 
-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.
+Applications write Flow state through typed RPCs. Client and AsyncClient do not
+expose direct Attribute writes, Channel publication, or pending-message
+mutation. This keeps each external state transition behind a Flow-owned method.
+
+Read committed Attribute values without an RPC through `get_attributes`. Pass
+one or more singleton Attributes or AttributeMap instances selected with
+`AttributeMap.instance(key)`:
+
+```python
+values = client.get_attributes(flow_id, ORDER_STATUS, NOTES.instance("n1"))
+status = values.get(ORDER_STATUS, "new")
+if NOTES.instance("n1") in values:
+    note = values[NOTES.instance("n1")]
+```
+
+`AsyncClient.get_attributes` is the awaitable form. There is no single-Attribute
+method; pass one read to read one value. The Client sends every key in one
+request and no Worker runs, so all values come from the same committed state.
+The call reads the current run, or the latest run when no run is open, and a
+closed run stays readable until Dex purges it. Unlike a read inside an RPC
+handler, it never sees writes that a running Step or RPC has not committed.
+
+The result `AttributeValues` is keyed by the reads passed to the call, and type
+checkers infer each value type from its key. An unset Attribute or map instance
+is absent: `values[key]` raises `KeyError`, `values.get(key)` returns `None`,
+`values.get(key, default)` returns `default`, and `key in values` is `False`. A
+stored value that decodes to `None` is still present. Each read must equal a
+definition declared by some Flow in the Client's Registry, with the same name,
+value type, index, `sync_to_attribute_store`, and `hard_delete_on_null`;
+otherwise the call raises `FlowDefinitionError` before contacting Dex. Two
+reads of the same key, or no read at all, raise `ValueError`. Large values are
+resolved through LoadBlobs and the BlobCache before decoding.
 
 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.
@@ -423,7 +451,8 @@ the Attribute or setting it to `None` permanently deletes the stored value, and
 deleted value reads as absent. Only string and object values, including
 `bytes`, are supported; `int`, `bool`, and `float` types are rejected. The
 option cannot be combined with an index or `sync_to_attribute_store`, and
-`wait_for_attribute_match` rejects it. Handlers receive the value inline, and
+`wait_for_attribute_match` rejects it. `get_attributes` reads it; Dex resolves
+the stored value. Handlers and `get_attributes` receive the value inline, and
 the SDK never stores it in the local blob cache.
 
 Hard-delete writes require a Server with an enabled blob store and Server
@@ -780,7 +809,7 @@ SubFlow.
 ### Errors
 
 Client calls raise concrete `DexServiceError` subclasses. Existing-Flow reads
-(`describe_flow`, `wait_for_flow`, and `time_travel`) raise
+(`describe_flow`, `get_attributes`, `wait_for_flow`, and `time_travel`) raise
 `FlowNotFoundError` when the Flow does not exist. Mutations, RPCs, timer/Step
 waits, config updates, and state-transfer triggers raise
 `FlowNotActiveOrNotFoundError` when no running Flow can accept the operation.

{dex_python_sdk-1.28.1 → dex_python_sdk-1.29.0}/dex/__init__.py

@@ -16,10 +16,12 @@ from dex.attribute import (
     AttributeIndex,
     AttributeLock,
     AttributeMap,
+    AttributeMapInstance,
     AttributeMapLoad,
     IndexType,
 )
 from dex.attribute_match import AttributeMatch
+from dex.attribute_values import AttributeValues
 from dex.blob_cache import BlobCache, BlobCacheConfig, open_blob_cache
 from dex.channel import Channel, ChannelMap, ChannelMapLoad, ChannelMessage
 from dex.client import Client
@@ -139,9 +141,11 @@ __all__ = [
     "AttributeIndex",
     "AttributeLock",
     "AttributeMap",
+    "AttributeMapInstance",
     "AttributeMapLoad",
     "AttributeMapNotLoadedError",
     "AttributeMatch",
+    "AttributeValues",
     "AsyncContext",
     "AsyncClient",
     "AsyncBufferedTextStream",

dex_python_sdk-1.29.0/dex/_attribute_reads.py

@@ -0,0 +1,200 @@
+# 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 collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any
+
+import grpc
+
+from dex._grpc_errors import translate_rpc_error
+from dex._value_mapper import ValueMapper
+from dex.attribute import Attribute, AttributeMap, AttributeMapInstance
+from dex.attribute_values import AttributeValues
+from dex.codec import Codec
+from dex.dexpb import dex_pb2 as pb
+from dex.flow import Registry
+from dex.runtime_errors import DexServiceError, FlowDefinitionError, ValueMappingError
+
+_OPERATION = "get_attributes"
+
+AttributeRead = Attribute[Any] | AttributeMapInstance[Any]
+
+
+@dataclass(frozen=True)
+class _PlannedAttributeRead:
+    read: AttributeRead
+    key: str
+    codec: Codec[Any]
+
+
+@dataclass(frozen=True)
+class AttributeReadPlan:
+    """Validated reads of one get_attributes call, shared by both Clients."""
+
+    flow_id: str
+    reads: tuple[_PlannedAttributeRead, ...]
+
+    @property
+    def keys(self) -> tuple[str, ...]:
+        return tuple(planned.key for planned in self.reads)
+
+    def request(self) -> pb.GetAttributesRequest:
+        return pb.GetAttributesRequest(flow_id=self.flow_id, keys=self.keys)
+
+    def service_error(
+        self, error: grpc.RpcError, service_method: str
+    ) -> DexServiceError:
+        translated = translate_rpc_error(error, _OPERATION, self.flow_id, "existing")
+        translated.args = (
+            f"{self._context()} Attributes {self._joined_keys()} {service_method} "
+            f"failed: {translated.detail}",
+        )
+        return translated
+
+    def hydration_error(self, error: Exception) -> ValueMappingError:
+        return ValueMappingError(
+            "decode",
+            f"{self._context()} Attributes {self._joined_keys()} returned a value "
+            f"that cannot be resolved: {error}",
+        )
+
+    def set_entries(self, response: pb.GetAttributesResponse) -> list[pb.KV]:
+        """Return the set entries after rejecting malformed responses.
+
+        Returns:
+            One entry per set read, in response order. An omitted key is unset.
+
+        Raises:
+            ValueError: If an entry has an unexpected or duplicate key, or no value.
+        """
+        requested = set(self.keys)
+        seen: set[str] = set()
+        entries: list[pb.KV] = []
+        for entry in response.attributes:
+            if entry.key not in requested:
+                raise ValueError(
+                    f"{self._context()} returned unexpected Attribute {entry.key!r}"
+                )
+            if entry.key in seen:
+                raise ValueError(
+                    f"{self._context()} returned duplicate Attribute {entry.key!r}"
+                )
+            if not entry.HasField("value"):
+                raise ValueError(
+                    f"{self._context()} returned Attribute {entry.key!r} without a value"
+                )
+            seen.add(entry.key)
+            entries.append(entry)
+        return entries
+
+    def decode(
+        self,
+        values: ValueMapper,
+        entries: Sequence[pb.KV],
+        hydrated: Sequence[pb.Value],
+    ) -> AttributeValues:
+        """Decode every set value, or raise before returning any of them.
+
+        Returns:
+            The set values keyed by the read passed to the call.
+
+        Raises:
+            ValueMappingError: If a value cannot be decoded as its value type.
+        """
+        hydrated_by_key = {
+            entry.key: value for entry, value in zip(entries, hydrated, strict=True)
+        }
+        decoded: dict[AttributeRead, object] = {}
+        for planned in self.reads:
+            value = hydrated_by_key.get(planned.key)
+            if value is None:
+                continue
+            try:
+                decoded[planned.read] = values.decode(value, planned.codec)
+            except ValueMappingError as error:
+                raise ValueMappingError(
+                    "decode",
+                    f"{self._context()} Attribute {planned.key!r}: {error.detail}",
+                ) from error
+        return AttributeValues._of_set_values(decoded)
+
+    def _context(self) -> str:
+        return f"{_OPERATION} Flow {self.flow_id!r}"
+
+    def _joined_keys(self) -> str:
+        return ", ".join(repr(key) for key in self.keys)
+
+
+def plan_attribute_reads(
+    registry: Registry,
+    values: ValueMapper,
+    flow_id: str,
+    reads: Sequence[object],
+) -> AttributeReadPlan:
+    """Validate the reads of one get_attributes call before any transport.
+
+    Returns:
+        The plan whose keys follow the order of ``reads``.
+
+    Raises:
+        ValueError: If the Flow ID is empty, no read is given, or a key repeats.
+        TypeError: If a read is not an Attribute or AttributeMapInstance.
+        FlowDefinitionError: If no registered Flow declares an equal definition.
+    """
+    if not isinstance(flow_id, str) or not flow_id.strip():
+        raise ValueError(f"{_OPERATION} requires a non-empty Flow ID, got {flow_id!r}")
+    if not reads:
+        raise ValueError(
+            f"{_OPERATION} Flow {flow_id!r} requires at least one Attribute read"
+        )
+    planned_reads: list[_PlannedAttributeRead] = []
+    seen_keys: set[str] = set()
+    for read in reads:
+        typed_read, definition, key = _definition_and_key(flow_id, read)
+        try:
+            registry._require_registered_attribute(definition)
+        except FlowDefinitionError as error:
+            raise FlowDefinitionError(
+                f"{_OPERATION} Flow {flow_id!r} Attribute {key!r}: {error}"
+            ) from error
+        if key in seen_keys:
+            raise ValueError(
+                f"{_OPERATION} Flow {flow_id!r} has duplicate Attribute read {key!r}"
+            )
+        seen_keys.add(key)
+        planned_reads.append(
+            _PlannedAttributeRead(
+                read=typed_read,
+                key=key,
+                codec=values.codec(definition.value_type),
+            )
+        )
+    return AttributeReadPlan(flow_id, tuple(planned_reads))
+
+
+def _definition_and_key(
+    flow_id: str,
+    read: object,
+) -> tuple[AttributeRead, Attribute[Any] | AttributeMap[Any], str]:
+    if isinstance(read, Attribute):
+        return read, read, read.name
+    if isinstance(read, AttributeMapInstance):
+        key = Registry.physical_name(read.attribute_map.name, read.instance)
+        return read, read.attribute_map, key
+    if isinstance(read, AttributeMap):
+        raise TypeError(
+            f"{_OPERATION} Flow {flow_id!r} AttributeMap {read.name!r} needs an "
+            "instance; pass AttributeMap.instance(key)"
+        )
+    raise TypeError(
+        f"{_OPERATION} Flow {flow_id!r} read must be an Attribute or "
+        f"AttributeMapInstance, not {type(read).__name__}"
+    )

{dex_python_sdk-1.28.1 → dex_python_sdk-1.29.0}/dex/async_client.py

@@ -19,6 +19,7 @@ from uuid import uuid4
 import grpc
 from google.protobuf import empty_pb2
 
+from dex._attribute_reads import plan_attribute_reads
 from dex._credential_transport import AsyncCredentialRunner, async_channel
 from dex._async_value_hydrator import AsyncValueHydrator
 from dex._grpc_errors import FlowTargetRequirement, translate_rpc_error
@@ -34,12 +35,14 @@ from dex._worker_dispatcher import WorkerDispatcher
 from dex.attribute import (
     Attribute,
     AttributeMap,
+    AttributeMapInstance,
     _apply_attribute_store_sync,
     _apply_hard_delete_on_null,
     _require_attribute_wait_supported,
     _require_matching_hard_delete_on_null,
 )
 from dex.attribute_match import AttributeMatch, _encode_attribute_match
+from dex.attribute_values import AttributeValues
 from dex.blob_cache import BlobCache
 from dex.channel import Channel, ChannelMap
 from dex.client_options import ClientOptions
@@ -660,6 +663,99 @@ class AsyncClient:
             response.start_time.ToDatetime(tzinfo=timezone.utc),
         )
 
+    async def get_attributes(
+        self,
+        flow_id: str,
+        *reads: Attribute[Any] | AttributeMapInstance[Any],
+    ) -> AttributeValues:
+        """Read committed Attribute values from the current or latest Flow run.
+
+        Use ``get_attributes`` to read Flow state from outside the Flow without
+        defining an RPC. Pass one or more reads. A read is a singleton
+        ``Attribute`` or one AttributeMap instance selected with
+        ``AttributeMap.instance(key)``. To read one Attribute, pass a single read.
+        The Client sends every key in one FlowService request, so all values come
+        from the same committed state. No Worker runs.
+
+        The call targets the current run, or the latest run when no run is open. A
+        closed run stays readable until Dex purges it. The call sees only committed
+        state. Unlike reading inside an RPC handler, it never sees writes that a
+        running Step or RPC has staged but not yet committed.
+
+        Each read must use a definition that some Flow in this Client's Registry
+        declares in its ``PersistenceSchema``. The definition matches when it is
+        equal to the registered one: same class (``Attribute`` or
+        ``AttributeMap``), name, ``value_type``, ``index``,
+        ``sync_to_attribute_store``, and ``hard_delete_on_null``. The definition
+        may come from any registered Flow. The server does not check that the
+        target Flow's type declares it, so a same-named Attribute of another type
+        in the target Flow fails to decode.
+
+        Attributes defined with ``hard_delete_on_null=True`` are readable; the
+        server resolves their stored values. The Client resolves other large
+        values through LoadBlobs and the Client's BlobCache, and then decodes every
+        value. On any error the call returns nothing, so no partial result is
+        visible. Every error message names the Flow ID. An error about one read or
+        value also names its Attribute name or physical key.
+
+        Example::
+
+            ORDER_STATUS = Attribute("order-status", str)
+            NOTES = AttributeMap("notes", Note)
+
+            try:
+                values = await client.get_attributes(
+                    "order-42", ORDER_STATUS, NOTES.instance("n1")
+                )
+            except FlowNotFoundError:
+                return None
+            status = values.get(ORDER_STATUS, "new")
+            if NOTES.instance("n1") in values:
+                note = values[NOTES.instance("n1")]
+
+        Args:
+            flow_id: The non-empty Flow ID.
+            *reads: At least one ``Attribute`` or ``AttributeMapInstance``. Two
+                reads of the same Attribute or AttributeMap instance are rejected.
+
+        Returns:
+            The set values, keyed by the reads passed to this call. An Attribute or
+            AttributeMap instance without a stored value is absent from the result.
+
+        Raises:
+            ValueError: If ``flow_id`` is empty, no read is given, two reads select
+                the same Attribute or AttributeMap instance, or the response has an
+                unexpected key, a duplicate key, or an entry without a value.
+            TypeError: If a read is not an ``Attribute`` or
+                ``AttributeMapInstance``, such as an ``AttributeMap`` without an
+                instance.
+            FlowDefinitionError: If no Flow in the Registry declares a matching
+                definition, including a same-named definition with another value
+                type.
+            FlowNotFoundError: If the Flow does not exist or its latest run is
+                being purged.
+            ValueMappingError: If a returned value cannot be resolved or decoded
+                as its value type. This includes an empty or non-finite value, an
+                unsupported object encoding, and a large value that LoadBlobs omits.
+            DexServiceError: If FlowService or LoadBlobs otherwise fails. A LoadBlobs
+                failure for a missing Flow raises ``FlowNotFoundError``.
+        """
+        plan = plan_attribute_reads(self.registry, self._values, flow_id, reads)
+        try:
+            response = await self._service.GetAttributes(plan.request())
+        except grpc.RpcError as error:
+            raise plan.service_error(error, "GetAttributes") from error
+        entries = plan.set_entries(response)
+        try:
+            hydrated = await self._hydrator.hydrate_all(
+                flow_id, [entry.value for entry in entries]
+            )
+        except grpc.RpcError as error:
+            raise plan.service_error(error, "LoadBlobs") from error
+        except (ValueError, RuntimeError) as error:
+            raise plan.hydration_error(error) from error
+        return plan.decode(self._values, entries, hydrated)
+
     async def search_flows(
         self,
         query: str,

{dex_python_sdk-1.28.1 → dex_python_sdk-1.29.0}/dex/attribute.py

@@ -378,6 +378,37 @@ class AttributeMap(Generic[ValueT]):
         """
         return AttributeMapLoad(self, require_map_instance(instance))
 
+    def instance(self, instance: str) -> AttributeMapInstance[ValueT]:
+        """Select one typed instance for a Client Attribute read.
+
+        Pass the result to ``Client.get_attributes`` or
+        ``AsyncClient.get_attributes``, and use the same selector, or an equal
+        one, to look up the value in the returned ``AttributeValues``. The
+        selector keeps the AttributeMap value type, so type checkers infer the
+        value type of the lookup.
+
+        This differs from :meth:`load`. ``load`` selects an instance that an RPC
+        handler receives in its snapshot. ``instance`` selects an instance that
+        a Client reads from outside the Flow.
+
+        Example::
+
+            notes = AttributeMap("notes", Note)
+            values = client.get_attributes("order-42", notes.instance("n1"))
+            note = values.get(notes.instance("n1"))
+
+        Args:
+            instance: The non-empty, slash-free logical map key to read.
+
+        Returns:
+            A typed selector for this one instance.
+
+        Raises:
+            TypeError: If ``instance`` is not a string.
+            ValueError: If ``instance`` is empty or contains ``/``.
+        """
+        return AttributeMapInstance(self, instance)
+
     def get(self, context: Context, instance: str) -> ValueT:
         """Return one map instance from a Step or RPC Context.
 
@@ -451,6 +482,46 @@ class AttributeMap(Generic[ValueT]):
         return AttributeLock(self, instance)
 
 
+@dataclass(frozen=True)
+class AttributeMapInstance(Generic[ValueT]):
+    """Select one typed AttributeMap instance for a Client Attribute read.
+
+    Create a selector with :meth:`AttributeMap.instance`. Pass it to
+    ``Client.get_attributes`` or ``AsyncClient.get_attributes`` together with
+    singleton Attributes. Then use it as the key of the returned
+    ``AttributeValues``. Selectors are immutable and hashable. Two selectors are
+    equal when their AttributeMap definitions are equal and their instance keys
+    are the same string.
+
+    Example::
+
+        notes = AttributeMap("notes", Note)
+        first_note = notes.instance("n1")
+        values = client.get_attributes("order-42", first_note)
+        if first_note in values:
+            print(values[first_note].text)
+
+    Attributes:
+        attribute_map: The AttributeMap definition that owns the instance.
+        instance: The non-empty logical map key. It must not contain ``/``.
+
+    Raises:
+        TypeError: If ``attribute_map`` is not an AttributeMap, or ``instance`` is
+            not a string.
+        ValueError: If ``instance`` is empty or contains ``/``.
+    """
+
+    attribute_map: AttributeMap[ValueT]
+    instance: str
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.attribute_map, AttributeMap):
+            raise TypeError("AttributeMapInstance requires an AttributeMap definition")
+        if not isinstance(self.instance, str):
+            raise TypeError("attribute-map instance must be a string")
+        require_map_instance(self.instance)
+
+
 @dataclass(frozen=True)
 class AttributeLock:
     """Describe an Attribute lock acquired for a Step or RPC handler.