durable-workflow 0.1.0

Python SDK for the Durable Workflow server (language-neutral HTTP protocol)

durable-workflow (Python SDK)

A Python SDK for the Durable Workflow server. Speaks the server's language-neutral HTTP/JSON worker protocol — no PHP runtime required.

Status: Alpha. Supports starting workflows, registering workers, polling workflow + activity tasks, schedules, signals, and completing workflows. Queries, updates, timers, and child workflows are planned.

Install

pip install durable-workflow

Or for development:

pip install -e '.[dev]'

Quickstart

from durable_workflow import Client, Worker, workflow, activity

@activity.defn(name="greet")
def greet(name: str) -> str:
    return f"hello, {name}"

@workflow.defn(name="greeter")
class GreeterWorkflow:
    def run(self, ctx, name):
        result = yield ctx.schedule_activity("greet", [name])
        return result

async def main():
    client = Client("http://server:8080", token="dev-token-123", namespace="default")
    worker = Worker(
        client,
        task_queue="python-workers",
        workflows=[GreeterWorkflow],
        activities=[greet],
    )
    handle = await client.start_workflow(
        workflow_type="greeter",
        workflow_id="greet-1",
        task_queue="python-workers",
        input=["world"],
    )
    await worker.run_until(workflow_id="greet-1")
    result = await client.get_result(handle)
    print(result)  # "hello, world"

Features

• Async-first: Built on httpx and asyncio
• Type-safe: Full type hints, passes mypy --strict
• Polyglot: Works alongside PHP workers on the same task queue
• HTTP/JSON protocol: No gRPC, no protobuf dependencies
• Codec envelopes: Proper {codec: "json", blob: "..."} serialization for cross-language workflows

Documentation

Full documentation is available at durable-workflow.github.io/docs/2.0/sdks/python/:

• Quickstart
• Client API
• Workflow Authoring
• Activity Authoring
• Worker Configuration
• Error Handling
• Schedules (Cron)

Requirements

• Python ≥ 3.10
• A running Durable Workflow server

Development

# Install dev dependencies
pip install -e '.[dev]'

# Run tests
pytest

# Run integration tests (requires Docker)
pytest -m integration

# Type check
mypy src/durable_workflow/

# Lint
ruff check src/ tests/

License

MIT