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

dex/workflow_info.py

@@ -0,0 +1,16 @@
+# 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.dex_api.models.workflow_status import WorkflowStatus
+
+@dataclass
+class WorkflowInfo:
+    workflow_status: WorkflowStatus

dex/workflow_options.py

@@ -0,0 +1,74 @@
+# 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, field
+from typing import Any, Optional
+
+from dex.dex_api.models import (
+    IDReusePolicy,
+    WorkflowRetryPolicy,
+    WorkflowAlreadyStartedOptions,
+    WorkflowConfig,
+)
+from dex.workflow_state import (
+    WorkflowState,
+    get_state_id_by_class,
+    get_state_execution_id,
+)
+
+@dataclass
+class WorkflowOptions:
+    workflow_id_reuse_policy: Optional[IDReusePolicy] = None
+    workflow_cron_schedule: Optional[str] = None
+    workflow_start_delay_seconds: Optional[int] = None
+    workflow_retry_policy: Optional[WorkflowRetryPolicy] = None
+    workflow_already_started_options: Optional[WorkflowAlreadyStartedOptions] = None
+    workflow_config_override: Optional[WorkflowConfig] = None
+    initial_data_attributes: Optional[dict[str, Any]] = None
+    _wait_for_completion_state_ids: list[str] = field(default_factory=list)
+    _wait_for_completion_state_execution_ids: list[str] = field(default_factory=list)
+    initial_search_attributes: Optional[dict[str, Any]] = None
+
+    @property
+    def wait_for_completion_state_ids(self) -> Optional[list[str]]:
+        return self._wait_for_completion_state_ids
+
+    @wait_for_completion_state_ids.setter
+    def wait_for_completion_state_ids(self, *states: type[WorkflowState]):
+        state_ids: list[str] = []
+        for state in states:
+            state_ids.append(get_state_id_by_class(state))
+        self._wait_for_completion_state_ids = state_ids
+
+    def add_wait_for_completion_state_ids(self, *states: type[WorkflowState]):
+        for state in states:
+            self._wait_for_completion_state_ids.append(get_state_id_by_class(state))
+
+    @property
+    def wait_for_completion_state_execution_ids(self) -> Optional[list[str]]:
+        return self._wait_for_completion_state_execution_ids
+
+    @wait_for_completion_state_execution_ids.setter
+    def wait_for_completion_state_execution_ids(self, val):
+        try:
+            state, number = val
+        except ValueError:
+            raise ValueError(
+                "Pass an iterable with two items: state: type[WorkflowState] and number: int"
+            )
+        else:
+            state_id = get_state_execution_id(state, number)
+            self._wait_for_completion_state_execution_ids = state_id
+
+    def add_wait_for_completion_state_execution_id(
+        self, state: type[WorkflowState], number: int
+    ):
+        state_id = get_state_execution_id(state, number)
+        self._wait_for_completion_state_execution_ids.append(state_id)

dex/workflow_state.py

@@ -0,0 +1,123 @@
+# 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 abc import ABC
+from typing import Generic, TypeVar, get_args
+
+from dex.command_request import CommandRequest
+from dex.command_results import CommandResults
+from dex.communication import Communication
+from dex.persistence import Persistence
+from dex.state_decision import StateDecision
+from dex.workflow_context import WorkflowContext
+from dex.workflow_state_options import WorkflowStateOptions
+
+T = TypeVar("T")
+
+not_implemented_error_msg = "This implementation shouldn't be invoked"
+
+class WorkflowState(ABC, Generic[T]):
+    """WorkflowState is the interface to define a workflow state."""
+
+    def wait_until(
+        self,
+        ctx: WorkflowContext,
+        input: T,
+        persistence: Persistence,
+        communication: Communication,
+    ) -> CommandRequest:
+        """
+        WaitUntil is the method to set up commands set up to wait for, before `execute` API is invoked.
+        It's optional -- execute will be invoked instead if this is not implemented.
+
+        Args:
+            ctx: the context info of this API invocation, like workflow start time, workflowId, etc
+            input: input: the state input
+            persistence:  the API for
+                    1) data attributes: defined by ObjectWorkflow interface
+                    2) search attributes: defined by ObjectWorkflow interface
+                    3) stateExecutionLocals: for passing data within the state execution
+                    4) recordEvent: for storing some tracking info(e.g. RPC call input/output) when executing the API.
+                    Note that any write API will be recorded to server after the whole waitUntil API response is accepted
+            communication: the API right now only for publishing value to internalChannel
+                        Note that any write API will be recorded to server after the whole waitUntil API response is accepted.
+
+        Returns: the requested command
+        """
+        raise NotImplementedError(not_implemented_error_msg)
+
+    def execute(
+        self,
+        ctx: WorkflowContext,
+        input: T,
+        command_results: CommandResults,
+        persistence: Persistence,
+        communication: Communication,
+    ) -> StateDecision:
+        """
+        Execute is the method to execute and decide what to do next. Invoke after commands from WaitUntil are completed, or there is WaitUntil is not implemented for the state.
+
+        Args:
+          ctx: the context info of this API invocation, like workflow start time, workflowId, etc
+          input:  the state input
+          command_results: the results of the command that executed by WaitUntil
+          persistence:  the API for
+                1) data attributes: defined by ObjectWorkflow interface
+                2) search attributes: defined by ObjectWorkflow interface
+                3) stateExecutionLocals: for passing data within the state execution
+                4) recordEvent: for storing some tracking info(e.g. RPC call input/output) when executing the API.
+                Note that any write API will be recorded to server after the whole waitUntil API response is accepted
+          communication: the API right now only for publishing value to internalChannel.
+                        Note that any write API will be recorded to server after the whole execute API response is accepted.
+
+        Returns: the decision of what to do next(e.g. transition to next states or closing workflow)
+        """
+        raise NotImplementedError(not_implemented_error_msg)
+
+    def get_state_options(self) -> WorkflowStateOptions:
+        """GetStateOptions can just return nil to use the default Options
+        StateOptions is optional configuration to adjust the state behaviors. Default values:
+             StateId:  name of the implementation class
+             waitUntilApiFailurePolicy: FAIL_WORKFLOW_ON_FAILURE
+             PersistenceLoadingPolicy for dataAttributes/searchAttributes: LOAD_ALL_WITHOUT_LOCKING
+             waitUntil/execute API:
+                timeout: 30s
+                retryPolicy:
+                    InitialIntervalSeconds: 1
+                    MaxInternalSeconds:100
+                    MaximumAttempts: 0
+                    BackoffCoefficient: 2
+        Returns: WorkflowStateOptions
+        """
+        return WorkflowStateOptions()
+
+def get_state_id(state: WorkflowState) -> str:
+    options = state.get_state_options()
+    if options is None or options.state_id is None:
+        return state.__class__.__name__
+    return options.state_id
+
+def get_state_id_by_class(state: type[WorkflowState]) -> str:
+    return state.__name__
+
+def should_skip_wait_until(state: WorkflowState) -> bool:
+    func_name = state.wait_until.__name__
+    parent_method = getattr(super(type(state), state), func_name)
+    return parent_method == state.wait_until
+
+def get_input_type(state):
+    bases = state.__orig_bases__
+    for b in bases:
+        if b.__origin__ == WorkflowState:
+            return get_args(b)[0]
+    return None
+
+def get_state_execution_id(state: type[WorkflowState], number: int):
+    return f"{get_state_id_by_class(state)}-{number}"

dex/workflow_state_options.py

@@ -0,0 +1,154 @@
+# 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 Any, Optional
+
+from dex.errors import WorkflowDefinitionError
+from dex.dex_api.models import (
+    ExecuteApiFailurePolicy,
+    PersistenceLoadingPolicy,
+    RetryPolicy,
+    WaitUntilApiFailurePolicy,
+    WorkflowStateOptions as IdlWorkflowStateOptions,
+)
+from dex.dex_api.types import Unset
+
+@dataclass
+class WorkflowStateOptions:
+    state_id: Optional[str] = None
+    # apply for both waitUntil and execute API
+    data_attributes_loading_policy: Optional[PersistenceLoadingPolicy] = None
+    search_attributes_loading_policy: Optional[PersistenceLoadingPolicy] = None
+    # below are wait_until API specific options:
+    wait_until_api_timeout_seconds: Optional[int] = None
+    wait_until_api_retry_policy: Optional[RetryPolicy] = None
+    """
+       By default, workflow would fail after waitUntil API retry exhausted.
+       This policy to allow proceeding to the execute API after waitUntil API exhausted all retries.
+       This is useful for some advanced use cases like SAGA pattern.
+       RetryPolicy is required to be set with maximumAttempts or maximumAttemptsDurationSeconds for waitUntil API.
+    NOTE: execute API will use commandResults to check whether the waitUntil has succeeded or not.
+       See more in <a href="https://github.com/superdurable/dex/wiki/WorkflowStateOptions">wiki</a>
+    """
+    proceed_to_execute_when_wait_until_retry_exhausted: Optional[
+        WaitUntilApiFailurePolicy
+    ] = None
+    wait_until_api_data_attributes_loading_policy: Optional[
+        PersistenceLoadingPolicy
+    ] = None
+    wait_until_api_search_attributes_loading_policy: Optional[
+        PersistenceLoadingPolicy
+    ] = None
+    # below are execute API specific options:
+    execute_api_timeout_seconds: Optional[int] = None
+    execute_api_retry_policy: Optional[RetryPolicy] = None
+    """
+        By default, workflow would fail after execute API retry exhausted.
+        Set the state to proceed to the specified state after the execute API exhausted all retries
+        This is useful for some advanced use cases like SAGA pattern.
+        RetryPolicy is required to be set with maximumAttempts or maximumAttemptsDurationSeconds for execute API.
+        Note that the failure handling state will take the same input as the failed from state.
+        TODO the type should be the type is Optional[type[WorkflowState]] but -- there is an issue with circular import...
+    """
+    proceed_to_state_when_execute_retry_exhausted: Optional[type] = None
+    execute_api_data_attributes_loading_policy: Optional[PersistenceLoadingPolicy] = (
+        None
+    )
+    execute_api_search_attributes_loading_policy: Optional[PersistenceLoadingPolicy] = (
+        None
+    )
+
+def _to_idl_state_options(
+    skip_wait_until: bool,
+    options: Any,  # TODO this type was Optional[WorkflowStateOptions],
+    # however, type hint is not working with recursive call...
+    state_store: dict[str, Any],  # TODO this type should be dict[str, WorkflowState]
+) -> IdlWorkflowStateOptions:
+    res = IdlWorkflowStateOptions()
+    if skip_wait_until:
+        res.skip_wait_until = True
+
+    if options is None:
+        return res
+    assert isinstance(options, WorkflowStateOptions)
+
+    if options.wait_until_api_search_attributes_loading_policy is not None:
+        res.wait_until_api_search_attributes_loading_policy = (
+            options.wait_until_api_search_attributes_loading_policy
+        )
+    if options.execute_api_search_attributes_loading_policy is not None:
+        res.execute_api_search_attributes_loading_policy = (
+            options.execute_api_search_attributes_loading_policy
+        )
+    if options.search_attributes_loading_policy is not None:
+        res.search_attributes_loading_policy = options.search_attributes_loading_policy
+    if options.wait_until_api_data_attributes_loading_policy is not None:
+        res.wait_until_api_data_attributes_loading_policy = (
+            options.wait_until_api_data_attributes_loading_policy
+        )
+    if options.execute_api_data_attributes_loading_policy is not None:
+        res.execute_api_data_attributes_loading_policy = (
+            options.execute_api_data_attributes_loading_policy
+        )
+    if options.data_attributes_loading_policy is not None:
+        res.data_attributes_loading_policy = options.data_attributes_loading_policy
+    if options.proceed_to_execute_when_wait_until_retry_exhausted is not None:
+        res.wait_until_api_failure_policy = (
+            options.proceed_to_execute_when_wait_until_retry_exhausted
+        )
+        if options.wait_until_api_retry_policy is None:
+            raise WorkflowDefinitionError("wait_until API retry policy must be set")
+        if isinstance(
+            options.wait_until_api_retry_policy.maximum_attempts, Unset
+        ) and isinstance(
+            options.wait_until_api_retry_policy.maximum_attempts_duration_seconds, Unset
+        ):
+            raise WorkflowDefinitionError(
+                "wait_until API retry policy must be set with maximum_attempts or maximum_attempts_duration_seconds"
+            )
+    if options.wait_until_api_retry_policy is not None:
+        res.wait_until_api_retry_policy = options.wait_until_api_retry_policy
+    if options.wait_until_api_timeout_seconds is not None:
+        res.wait_until_api_timeout_seconds = options.wait_until_api_timeout_seconds
+    if options.execute_api_retry_policy is not None:
+        res.execute_api_retry_policy = options.execute_api_retry_policy
+    if options.execute_api_timeout_seconds is not None:
+        res.execute_api_timeout_seconds = options.execute_api_timeout_seconds
+    if options.proceed_to_state_when_execute_retry_exhausted is not None:
+        res.execute_api_failure_policy = (
+            ExecuteApiFailurePolicy.PROCEED_TO_CONFIGURED_STATE
+        )
+        if options.execute_api_retry_policy is None:
+            raise WorkflowDefinitionError("execute API retry policy must be set")
+        if isinstance(
+            options.execute_api_retry_policy.maximum_attempts, Unset
+        ) and isinstance(
+            options.execute_api_retry_policy.maximum_attempts_duration_seconds, Unset
+        ):
+            raise WorkflowDefinitionError(
+                "execute API retry policy must be set with maximum_attempts or maximum_attempts_duration_seconds"
+            )
+
+        from dex.workflow_state import get_state_id_by_class
+
+        res.execute_api_failure_proceed_state_id = get_state_id_by_class(
+            options.proceed_to_state_when_execute_retry_exhausted
+        )
+        state = state_store[res.execute_api_failure_proceed_state_id]
+        proceed_state_options = state.get_state_options()
+
+        from dex.workflow_state import should_skip_wait_until
+
+        proceed_state_idl_options = _to_idl_state_options(
+            should_skip_wait_until(state), proceed_state_options, state_store
+        )
+        res.execute_api_failure_proceed_state_options = proceed_state_idl_options
+    return res

dex_python_sdk-0.0.2.dist-info/METADATA

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: dex-python-sdk
+Version: 0.0.2
+Requires-Dist: grpcio>=1.83.0
+Requires-Dist: grpcio-status>=1.83.0
+Requires-Dist: httpx==0.28.1
+Requires-Dist: protobuf>=7.35.1
+License-File: LICENSE
+License-File: LEGACY_NOTICES.md
+Summary: Python SDK for the Dex workflow engine
+Author: Super Durable
+License-Expression: LicenseRef-Super-Durable-1.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/superdurable/dex/tree/main/sdk-python
+Project-URL: Repository, https://github.com/superdurable/dex
+
+
+# Dex SDK for Python
+
+Python SDK for [Dex workflow engine](https://github.com/superdurable/dex)
+
+## New user contracts
+
+The rewrite targets Python 3.11+ and exposes strongly typed workflow contracts
+from `dex`. This phase includes definitions, attributes, channels, waits,
+decisions, codecs, registry validation, synchronous client calls, and synchronous
+worker handlers. Python owns its gRPC Client and Worker transport;
+the shared Rust Core is used only for BlobCache.
+
+```python
+from datetime import timedelta
+
+import dex
+
+counter = dex.Attribute("counter", int)
+counters_by_region = dex.AttributeMap("counters-by-region", int)
+
+class Run(dex.Step[str]):
+    def wait_for(
+        self, context: dex.Context, input: str
+    ) -> dex.Wait:
+        return dex.Wait.all_of(
+            dex.Timer.by_duration(timedelta(seconds=1))
+        )
+
+    def execute(
+        self, context: dex.Context, input: str
+    ) -> dex.StepDecision:
+        return dex.graceful_complete(input)
+
+class CounterFlow(dex.Flow[str]):
+    run = Run()
+
+    def get_flow_type(self) -> str:
+        return "Counter"
+
+    def get_steps(self) -> dex.StepList[str]:
+        return dex.StepList.start_step(self.run)
+
+    def get_persistence_schema(self) -> dex.PersistenceSchema:
+        return dex.PersistenceSchema.of(counter, counters_by_region)
+
+    @dex.rpc(name="Increment")
+    def increment(
+        self, context: dex.Context, input: int
+    ) -> dex.RPCResult[int]:
+        return dex.RPCResult(input + 1)
+
+flow = CounterFlow()
+registry = dex.Registry((flow,))
+```
+
+Registry derives codecs from declared Python types and handler annotations.
+Built-in scalar types and dataclasses need no codec arguments. Register an
+explicit codec only for a custom encoding or a type Registry cannot derive.
+`PersistenceSchema.of(...)` accepts attributes and channels together and
+partitions them by definition type.
+
+Initial attributes retain their value types without a public wrapper class:
+
+```python
+options = (
+    dex.StartFlowOptions()
+    .with_attribute(counter, 1)
+    .with_attribute(counters_by_region, "us-west", 1)
+)
+```
+
+```
+pip install dex-python-sdk==0.0.2
+```
+
+See [samples](../examples/python) for use case examples.
+
+## Requirements
+
+- Python 3.11+
+- [Dex server](https://github.com/superdurable/dex#how-to-use)
+
+## Concepts
+
+Applications implement two generic interfaces from [`dex.contracts`](dex/contracts/):
+
+- `Flow[START_INPUT]` returns `StepList.start_step(...)`, followed by optional
+  `.other_steps(...)`, from one `get_steps()` method. The `StepList` generic
+  binds the Flow input to the starting Step input. Use `StepList.empty()` when
+  a Flow has no Steps.
+- `Step[INPUT]` implements synchronous `execute` and optionally synchronous
+  `wait_for`.
+
+`StepOptions.wait_for_method_timeout` and `execute_method_timeout` bound the
+two handler calls. Timer and channel conditions determine how long a Step waits.
+
+`Registry` validates every Flow, Step, RPC signature, durable name, lock, and
+codec before Client or Worker startup. `Client` methods use these typed objects
+instead of raw Flow, Step, or RPC strings.
+
+The legacy IWF integration inventory is ported under
+[`tests/integ`](tests/integ/README.md). Its 58 executable scenarios
+exercise the same workflows, client operations, and assertions as the Java
+suite against an isolated `dexcli dev` environment.
+
+## Implementation status
+
+The strongly typed contracts, registry, synchronous Client, Worker gRPC
+service, and Rust-backed BlobCache are implemented. Python owns its gRPC
+transport; the native bridge is limited to the shared BlobCache.
+
+## Running dex-server locally
+
+### Option 1: use docker compose
+See [dex README](https://github.com/superdurable/dex#using-docker-image--docker-compose)
+
+### Option 2: VSCode Dev Container
+
+Dev Container is an easy way to get dex-server running locally. Follow these steps to launch a dev container:
+- Install Docker, VSCode, and [VSCode Dev Container plugin](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
+- Open the project in VSCode.
+    ```bash
+    cd dex-python-sdk
+    code .
+    ```
+- Launch the Remote-Containers: Reopen in Container command from Command Palette (Ctrl + Shift + P). You can also click in the bottom left corner to access the remote container menu.
+- Once the dev container starts, dex-server will be listening on port 8801.
+
+## How To Contribute
+
+This project uses [uv](https://docs.astral.sh/uv/) for Python versions,
+dependencies, virtual environments, locking, building, and publishing.
+
+To install requirements:
+
+```bash
+uv sync --locked
+```
+
+Run the complete Python SDK integration suite with an isolated Dex development
+environment:
+
+```bash
+./run-integration-tests.sh
+```
+
+#### Update IDL
+
+Edit [`protos/dex.proto`](../protos/dex.proto). Rename catalog: [`docs/design/idl-renames.md`](../docs/design/idl-renames.md).
+
+#### Generate stubs from IDL
+
+```bash
+make -C ../protos proto-python
+```
+
+Checked-in Python stubs land in `dex/dexpb/`.
+#### Linting
+
+To run linting for this project:
+
+```bash
+uv run --frozen pre-commit run --show-diff-on-failure --color=always --all-files
+```
+
+## Code of Conduct
+This project is governed by the [Contributor Covenant v 1.4.1](CODE_OF_CONDUCT.md). (Review the Code of Conduct and remove this sentence before publishing your project.)
+
+## Publishing to PyPI
+
+1. Bump `version` in `pyproject.toml`, refresh `uv.lock`, and update the `pip install` line above.
+2. Run **Publish Python SDK to PyPI** manually without `publish` to validate all distributions.
+3. Create a GitHub Release with tag `sdk-python/vX.Y.Z` (for example `sdk-python/v0.0.2`).
+4. CI builds and smoke-tests Linux x86_64/ARM64, macOS x86_64/ARM64, and Windows x86_64 wheels, verifies the source distribution, and publishes them with `PYPI_TOKEN`.
+
+A manual run publishes only from `main`, when its version matches `pyproject.toml` and `publish` is explicitly selected.
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md#releases-monorepo-tags) for monorepo tag conventions.
+
+## License
+
+[Super Durable Source License 1.0](LICENSE), with legacy portions under their
+original terms as described in [LEGACY_NOTICES.md](LEGACY_NOTICES.md).
+