dex-python-sdk 0.0.2__cp311-abi3-win_amd64.whl

dex/client_options.py

@@ -0,0 +1,19 @@
+# Legacy Materials in this file remain under their original licenses.
+# See LEGACY_NOTICES.md.
+
+# Modifications Copyright (c) 2026 Super Durable, Inc.
+#
+# Modifications after the Legacy Cutoff are licensed under the
+# Super Durable Source License 1.0.
+# Legacy Materials remain under their original licenses.
+# See LICENSE and LEGACY_NOTICES.md.
+
+from dataclasses import dataclass
+
+from dex.worker_options import WorkerTarget
+
+
+@dataclass(frozen=True)
+class ClientOptions:
+    server_address: str = "localhost:8801"
+    worker_target: WorkerTarget | None = None

dex/codec.py

@@ -0,0 +1,286 @@
+# Copyright (c) 2026 Super Durable, Inc.
+#
+# Licensed under the Super Durable Source 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-Super-Durable-1.0
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import asdict, dataclass, field, fields, is_dataclass
+from datetime import datetime
+from enum import Enum
+from typing import (
+    Any,
+    Callable,
+    Generic,
+    Mapping,
+    Protocol,
+    Sequence,
+    TypeVar,
+    cast,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+ValueT = TypeVar("ValueT")
+
+
+class WireKind(Enum):
+    STRING = "string"
+    BOOL = "bool"
+    INT64 = "int64"
+    DOUBLE = "double"
+    BYTES = "bytes"
+    JSON = "json"
+
+
+@dataclass(frozen=True)
+class Value:
+    kind: WireKind
+    data: str | bool | int | float | bytes
+
+
+class Codec(Protocol[ValueT]):
+    @property
+    def type_name(self) -> str: ...
+
+    @property
+    def wire_kind(self) -> WireKind: ...
+
+    def encode(self, value: ValueT) -> Value: ...
+
+    def decode(self, value: Value) -> ValueT: ...
+
+
+@dataclass(frozen=True)
+class _ScalarCodec(Generic[ValueT]):
+    type_name: str
+    wire_kind: WireKind
+    expected_type: type[Any]
+    validator: Callable[[ValueT], None] | None = None
+
+    def encode(self, value: ValueT) -> Value:
+        if type(value) is not self.expected_type:
+            raise TypeError(
+                f"{self.type_name} requires {self.expected_type.__name__}, "
+                f"got {type(value).__name__}"
+            )
+        if self.validator is not None:
+            self.validator(value)
+        return Value(self.wire_kind, cast(str | bool | int | float | bytes, value))
+
+    def decode(self, value: Value) -> ValueT:
+        if value.kind is not self.wire_kind:
+            raise TypeError(
+                f"{self.type_name} cannot decode wire kind {value.kind.value}"
+            )
+        decoded = value.data
+        if type(decoded) is not self.expected_type:
+            raise TypeError(f"invalid {self.type_name} payload")
+        typed = cast(ValueT, decoded)
+        if self.validator is not None:
+            self.validator(typed)
+        return typed
+
+
+def _validate_int64(value: int) -> None:
+    if value < -(2**63) or value > 2**63 - 1:
+        raise OverflowError(f"integer {value} exceeds int64")
+
+
+def _validate_double(value: float) -> None:
+    if not math.isfinite(value):
+        raise ValueError("non-finite floating-point values are unsupported")
+
+
+STRING: Codec[str] = _ScalarCodec("str", WireKind.STRING, str)
+BOOL: Codec[bool] = _ScalarCodec("bool", WireKind.BOOL, bool)
+INT64: Codec[int] = _ScalarCodec("int", WireKind.INT64, int, _validate_int64)
+DOUBLE: Codec[float] = _ScalarCodec("float", WireKind.DOUBLE, float, _validate_double)
+BYTES: Codec[bytes] = _ScalarCodec("bytes", WireKind.BYTES, bytes)
+
+
+@dataclass(frozen=True)
+class _NoneCodec:
+    type_name: str = "None"
+    wire_kind: WireKind = WireKind.JSON
+
+    def encode(self, value: None) -> Value:
+        if value is not None:
+            raise TypeError("None codec requires None")
+        return Value(WireKind.JSON, "null")
+
+    def decode(self, value: Value) -> None:
+        if value.kind is not WireKind.JSON or value.data != "null":
+            raise TypeError("None codec requires JSON null")
+        return None
+
+
+@dataclass(frozen=True)
+class _DateTimeCodec:
+    type_name: str = "datetime"
+    wire_kind: WireKind = WireKind.STRING
+
+    def encode(self, value: datetime) -> Value:
+        if not isinstance(value, datetime):
+            raise TypeError("datetime codec requires datetime")
+        return Value(WireKind.STRING, value.isoformat())
+
+    def decode(self, value: Value) -> datetime:
+        if value.kind is not WireKind.STRING or not isinstance(value.data, str):
+            raise TypeError("datetime codec requires a string value")
+        return datetime.fromisoformat(value.data)
+
+
+_NONE: Codec[None] = _NoneCodec()
+_DATETIME: Codec[datetime] = _DateTimeCodec()
+
+
+@dataclass(frozen=True)
+class JsonCodec(Generic[ValueT]):
+    type_name: str
+    decoder: Callable[[Any], ValueT]
+    encoder: Callable[[ValueT], Any] = field(default=lambda value: value)
+    expected_type: object | None = None
+    wire_kind: WireKind = field(default=WireKind.JSON, init=False)
+
+    def encode(self, value: ValueT) -> Value:
+        if self.expected_type is not None and not _matches_type(
+            value, self.expected_type
+        ):
+            raise TypeError(
+                f"{self.type_name} requires {_type_name(self.expected_type)}, "
+                f"got {type(value).__name__}"
+            )
+        payload = json.dumps(
+            self.encoder(value),
+            allow_nan=False,
+            separators=(",", ":"),
+            sort_keys=True,
+        )
+        return Value(WireKind.JSON, payload)
+
+    def decode(self, value: Value) -> ValueT:
+        if value.kind is not WireKind.JSON or not isinstance(value.data, str):
+            raise TypeError(f"{self.type_name} requires a JSON value")
+        return self.decoder(json.loads(value.data))
+
+
+class CodecRegistry:
+    def __init__(self, codecs: Mapping[object, Codec[Any]] | None = None) -> None:
+        self._codecs = dict(codecs or {})
+
+    def resolve(self, type_hint: object) -> Codec[Any]:
+        custom = self._codecs.get(type_hint)
+        if custom is not None:
+            return custom
+        builtins: dict[object, Codec[Any]] = {
+            str: STRING,
+            bool: BOOL,
+            int: INT64,
+            float: DOUBLE,
+            bytes: BYTES,
+            type(None): _NONE,
+            datetime: _DATETIME,
+        }
+        builtin = builtins.get(type_hint)
+        if builtin is not None:
+            return builtin
+        if _supports_automatic_json(type_hint):
+            return JsonCodec(
+                _type_name(type_hint),
+                lambda value: _decode_json_value(value, type_hint),
+                _encode_json_value,
+                type_hint,
+            )
+        raise TypeError(
+            f"no codec for {_type_name(type_hint)}; register one in CodecRegistry"
+        )
+
+
+def _supports_automatic_json(type_hint: object) -> bool:
+    origin = get_origin(type_hint)
+    return (
+        isinstance(type_hint, type)
+        and (is_dataclass(type_hint) or issubclass(type_hint, Enum))
+    ) or origin in (list, tuple, dict, Mapping, Sequence)
+
+
+def _type_name(type_hint: object) -> str:
+    return getattr(type_hint, "__qualname__", str(type_hint))
+
+
+def _matches_type(value: object, type_hint: object) -> bool:
+    origin = get_origin(type_hint)
+    arguments = get_args(type_hint)
+    if origin is list:
+        return isinstance(value, list) and all(
+            _matches_type(item, arguments[0]) for item in value
+        )
+    if origin is tuple:
+        return isinstance(value, tuple) and all(
+            _matches_type(item, arguments[0]) for item in value
+        )
+    if origin in (dict, Mapping):
+        return isinstance(value, Mapping) and all(
+            _matches_type(key, arguments[0]) and _matches_type(item, arguments[1])
+            for key, item in value.items()
+        )
+    return isinstance(type_hint, type) and type(value) is type_hint
+
+
+def _encode_json_value(value: Any) -> Any:
+    if is_dataclass(value) and not isinstance(value, type):
+        return asdict(value)
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, Mapping):
+        return {key: _encode_json_value(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_encode_json_value(item) for item in value]
+    return value
+
+
+def _decode_json_value(value: Any, type_hint: object) -> Any:
+    origin = get_origin(type_hint)
+    arguments = get_args(type_hint)
+    if isinstance(type_hint, type) and is_dataclass(type_hint):
+        if not isinstance(value, Mapping):
+            raise TypeError(f"{_type_name(type_hint)} requires a JSON object")
+        hints = get_type_hints(type_hint)
+        return type_hint(
+            **{
+                definition.name: _decode_json_value(
+                    value[definition.name], hints[definition.name]
+                )
+                for definition in fields(type_hint)
+            }
+        )
+    if type_hint is datetime:
+        if not isinstance(value, str):
+            raise TypeError("datetime requires a JSON string")
+        return datetime.fromisoformat(value)
+    if isinstance(type_hint, type) and issubclass(type_hint, Enum):
+        return type_hint(value)
+    if origin is list:
+        return [_decode_json_value(item, arguments[0]) for item in value]
+    if origin is tuple:
+        return tuple(_decode_json_value(item, arguments[0]) for item in value)
+    if origin in (dict, Mapping):
+        return {
+            _decode_json_value(key, arguments[0]): _decode_json_value(
+                item, arguments[1]
+            )
+            for key, item in value.items()
+        }
+    if type_hint in (str, bool, int, float):
+        if type(value) is not type_hint:
+            raise TypeError(f"expected {_type_name(type_hint)}")
+    return value

dex/command_request.py

@@ -0,0 +1,120 @@
+# Legacy Materials in this file remain under their original licenses.
+# See LEGACY_NOTICES.md.
+
+# Modifications Copyright (c) 2026 Super Durable, Inc.
+#
+# Modifications after the Legacy Cutoff are licensed under the
+# Super Durable Source License 1.0.
+# Legacy Materials remain under their original licenses.
+# See LICENSE and LEGACY_NOTICES.md.
+
+from dataclasses import dataclass
+from typing import Optional, Union
+
+from dex.errors import WorkflowDefinitionError
+from dex.dex_api.models import CommandWaitingType
+from dex.dex_api.models.command_combination import CommandCombination
+from dex.dex_api.models.command_request import (
+    CommandRequest as IdlCommandRequest,
+)
+from dex.dex_api.models.inter_state_channel_command import (
+    InterStateChannelCommand as IdlInternalChannelCommand,
+)
+from dex.dex_api.models.signal_command import SignalCommand as IdlSignalCommand
+from dex.dex_api.models.timer_command import TimerCommand as IdlTimerCommand
+
+@dataclass
+class TimerCommand:
+    command_id: str
+    duration_seconds: int
+
+    @classmethod
+    def by_seconds(cls, duration_seconds: int, command_id: Optional[str] = None):
+        return TimerCommand(
+            command_id if command_id is not None else "", duration_seconds
+        )
+
+@dataclass
+class InternalChannelCommand:
+    command_id: str
+    channel_name: str
+
+    @classmethod
+    def by_name(cls, channel_name: str, command_id: Optional[str] = None):
+        return InternalChannelCommand(
+            command_id if command_id is not None else "", channel_name
+        )
+
+@dataclass
+class SignalChannelCommand:
+    command_id: str
+    channel_name: str
+
+    @classmethod
+    def by_name(cls, channel_name: str, command_id: Optional[str] = None):
+        return SignalChannelCommand(
+            command_id if command_id is not None else "",
+            channel_name,
+        )
+
+BaseCommand = Union[TimerCommand, InternalChannelCommand, SignalChannelCommand]
+
+@dataclass
+class CommandRequest:
+    commands: list[BaseCommand]
+    command_waiting_type: CommandWaitingType
+    command_combinations: list[CommandCombination]
+
+    @classmethod
+    def for_any_command_completed(cls, *commands: BaseCommand):
+        bc = [c for c in commands]
+        return CommandRequest(bc, CommandWaitingType.ANY_COMPLETED, [])
+
+    @classmethod
+    def for_all_command_completed(cls, *commands: BaseCommand):
+        bc = [c for c in commands]
+        return CommandRequest(bc, CommandWaitingType.ALL_COMPLETED, [])
+
+    @classmethod
+    def for_any_command_combination_completed(
+        cls, command_combinations_list: list[list[str]], *commands: BaseCommand
+    ):
+        return CommandRequest(
+            list(commands),
+            CommandWaitingType.ANY_COMBINATION_COMPLETED,
+            [CommandCombination(c) for c in command_combinations_list],
+        )
+
+    @classmethod
+    def empty(cls):
+        return CommandRequest(list(), CommandWaitingType.ALL_COMPLETED, [])
+
+def _to_idl_command_request(request: CommandRequest) -> IdlCommandRequest:
+    req = IdlCommandRequest(
+        command_waiting_type=request.command_waiting_type,
+    )
+
+    timer_commands = []
+    internal_channel_commands = []
+    signal_commands = []
+    for t in request.commands:
+        if isinstance(t, TimerCommand):
+            timer_commands.append(IdlTimerCommand(t.duration_seconds, t.command_id))
+        elif isinstance(t, InternalChannelCommand):
+            internal_channel_commands.append(
+                IdlInternalChannelCommand(t.channel_name, t.command_id)
+            )
+        elif isinstance(t, SignalChannelCommand):
+            signal_commands.append(IdlSignalCommand(t.channel_name, t.command_id))
+        else:
+            raise WorkflowDefinitionError(f"unknown command {t.__class__.__qualname__}")
+
+    if len(timer_commands) > 0:
+        req.timer_commands = timer_commands
+    if len(internal_channel_commands) > 0:
+        req.inter_state_channel_commands = internal_channel_commands
+    if len(signal_commands) > 0:
+        req.signal_commands = signal_commands
+    if len(request.command_combinations) > 0:
+        req.command_combinations = request.command_combinations
+    return req

dex/command_results.py

@@ -0,0 +1,107 @@
+# Legacy Materials in this file remain under their original licenses.
+# See LEGACY_NOTICES.md.
+
+# Modifications Copyright (c) 2026 Super Durable, Inc.
+#
+# Modifications after the Legacy Cutoff are licensed under the
+# Super Durable Source License 1.0.
+# Legacy Materials remain under their original licenses.
+# See LICENSE and LEGACY_NOTICES.md.
+
+import typing
+from dataclasses import dataclass
+from typing import Any, Union, Optional
+
+from dex.errors import WorkflowDefinitionError, NotRegisteredError
+from dex.dex_api.models import (
+    ChannelRequestStatus,
+    CommandResults as IdlCommandResults,
+    TimerStatus,
+)
+from dex.dex_api.types import Unset
+from dex.object_encoder import ObjectEncoder
+from dex.type_store import TypeStore
+
+@dataclass
+class TimerCommandResult:
+    status: TimerStatus
+    command_id: str
+
+@dataclass
+class InternalChannelCommandResult:
+    channel_name: str
+    value: Any
+    status: ChannelRequestStatus
+    command_id: str
+
+@dataclass
+class SignalChannelCommandResult:
+    channel_name: str
+    value: Any
+    status: ChannelRequestStatus
+    command_id: str
+
+@dataclass
+class CommandResults:
+    timer_commands: list[TimerCommandResult]
+    internal_channel_commands: list[InternalChannelCommandResult]
+    signal_channel_commands: list[SignalChannelCommandResult]
+    wait_until_api_succeeded: Optional[bool] = None
+
+def from_idl_command_results(
+    idl_results: Union[Unset, IdlCommandResults],
+    internal_channel_types: TypeStore,
+    signal_channel_types: dict[str, typing.Optional[type]],
+    object_encoder: ObjectEncoder,
+) -> CommandResults:
+    results = CommandResults(list(), list(), list(), None)
+    if isinstance(idl_results, Unset):
+        return results
+
+    if not isinstance(idl_results.timer_results, Unset):
+        for timer in idl_results.timer_results:
+            results.timer_commands.append(
+                TimerCommandResult(timer.timer_status, timer.command_id)
+            )
+
+    if not isinstance(idl_results.inter_state_channel_results, Unset):
+        for inter in idl_results.inter_state_channel_results:
+
+            try:
+                val_type = internal_channel_types.get_type(inter.channel_name)
+            except NotRegisteredError as exception:
+                raise WorkflowDefinitionError(
+                    "internal channel is not registered: " + inter.channel_name
+                ) from exception
+
+            encoded = object_encoder.decode(inter.value, val_type)
+
+            results.internal_channel_commands.append(
+                InternalChannelCommandResult(
+                    inter.channel_name,
+                    encoded,
+                    inter.request_status,
+                    inter.command_id,
+                )
+            )
+
+    if not isinstance(idl_results.signal_results, Unset):
+        for sig in idl_results.signal_results:
+            results.signal_channel_commands.append(
+                SignalChannelCommandResult(
+                    sig.signal_channel_name,
+                    object_encoder.decode(
+                        sig.signal_value,
+                        signal_channel_types.get(sig.signal_channel_name),
+                    ),
+                    sig.signal_request_status,
+                    sig.command_id,
+                )
+            )
+
+    if not isinstance(idl_results.state_wait_until_failed, Unset):
+        # The server will set state_wait_until_failed to true if the waitUntil API failed.
+        # Hence, flag inversion is needed here to indicate that the waitUntil API succeeded.
+        results.wait_until_api_succeeded = not idl_results.state_wait_until_failed
+
+    return results

dex/communication.py

@@ -0,0 +1,136 @@
+# Legacy Materials in this file remain under their original licenses.
+# See LEGACY_NOTICES.md.
+
+# Modifications Copyright (c) 2026 Super Durable, Inc.
+#
+# Modifications after the Legacy Cutoff are licensed under the
+# Super Durable Source License 1.0.
+# Legacy Materials remain under their original licenses.
+# See LICENSE and LEGACY_NOTICES.md.
+
+from typing import Any, Optional, Union
+
+from dex.errors import WorkflowDefinitionError, NotRegisteredError
+from dex.dex_api.models import (
+    EncodedObject,
+    InterStateChannelPublishing,
+    WorkflowWorkerRpcRequestInternalChannelInfos,
+    WorkflowWorkerRpcRequestSignalChannelInfos,
+)
+from dex.dex_api.types import Unset
+from dex.object_encoder import ObjectEncoder
+from dex.state_movement import StateMovement
+from dex.type_store import TypeStore
+
+class Communication:
+    _internal_channel_type_store: TypeStore
+    _signal_channel_type_store: dict[str, Optional[type]]
+    _object_encoder: ObjectEncoder
+    _to_publish_internal_channel: dict[str, list[Union[EncodedObject, Unset]]]
+    _state_movements: list[StateMovement]
+    _internal_channel_infos: Optional[WorkflowWorkerRpcRequestInternalChannelInfos]
+    _signal_channel_infos: Optional[WorkflowWorkerRpcRequestSignalChannelInfos]
+
+    def __init__(
+        self,
+        internal_channel_type_store: TypeStore,
+        signal_channel_type_store: dict[str, Optional[type]],
+        object_encoder: ObjectEncoder,
+        internal_channel_infos: Optional[WorkflowWorkerRpcRequestInternalChannelInfos],
+        signal_channel_infos: Optional[WorkflowWorkerRpcRequestSignalChannelInfos],
+    ):
+        self._object_encoder = object_encoder
+        self._internal_channel_type_store = internal_channel_type_store
+        self._signal_channel_type_store = signal_channel_type_store
+        self._to_publish_internal_channel = {}
+        self._state_movements = []
+        self._internal_channel_infos = internal_channel_infos
+        self._signal_channel_infos = signal_channel_infos
+
+    def trigger_state_execution(self, state: Union[str, type], state_input: Any = None):
+        """
+
+        Args:
+            state: the workflowState TODO the type hint should be type[WorkflowState]
+            state_input: the input of the state
+        """
+        movement = StateMovement.create(state, state_input)
+        self._state_movements.append(movement)
+
+    def publish_to_internal_channel(self, channel_name: str, value: Any = None):
+        try:
+            registered_type = self._internal_channel_type_store.get_type(channel_name)
+        except NotRegisteredError as exception:
+            raise WorkflowDefinitionError(
+                f"InternalChannel channel_name is not defined {channel_name}"
+            ) from exception
+
+        if (
+            value is not None
+            and registered_type is not None
+            and not isinstance(value, registered_type)
+        ):
+            raise WorkflowDefinitionError(
+                f"InternalChannel value is not of type {registered_type}"
+            )
+        vals = self._to_publish_internal_channel.get(channel_name)
+        if vals is None:
+            vals = []
+        vals.append(self._object_encoder.encode(value))
+        self._to_publish_internal_channel[channel_name] = vals
+
+    def get_to_publishing_internal_channel(self) -> list[InterStateChannelPublishing]:
+        pubs = []
+        for name, vals in self._to_publish_internal_channel.items():
+            for val in vals:
+                pubs.append(InterStateChannelPublishing(name, val))
+        return pubs
+
+    def get_to_trigger_state_movements(self) -> list[StateMovement]:
+        return self._state_movements
+
+    def get_internal_channel_size(self, channel_name):
+        is_type_registered = self._internal_channel_type_store.is_valid_name_or_prefix(
+            channel_name
+        )
+
+        if is_type_registered is False:
+            raise WorkflowDefinitionError(
+                f"InternalChannel channel_name is not defined {channel_name}"
+            )
+
+        if (
+            self._internal_channel_infos is not None
+            and channel_name in self._internal_channel_infos
+        ):
+            server_channel_size = self._internal_channel_infos[channel_name].size
+        else:
+            server_channel_size = 0
+
+        if channel_name in self._to_publish_internal_channel:
+            buffer_channel_size = len(self._to_publish_internal_channel[channel_name])
+        else:
+            buffer_channel_size = 0
+
+        return server_channel_size + buffer_channel_size
+
+    def get_signal_channel_size(self, channel_name):
+        registered_type = self._signal_channel_type_store.get(channel_name)
+
+        if registered_type is None:
+            for name, t in self._signal_channel_type_store.items():
+                if channel_name.startswith(name):
+                    registered_type = t
+
+        if registered_type is None:
+            raise WorkflowDefinitionError(
+                f"SignalChannel channel_name is not defined {channel_name}"
+            )
+
+        if (
+            self._signal_channel_infos is not None
+            and channel_name in self._signal_channel_infos
+        ):
+            return self._signal_channel_infos[channel_name].size
+        else:
+            return 0