Reference

Python SDK


Write workflows and tasks as plain async Python functions. The engine journals each step, and a run that is interrupted resumes on any worker from the last step it completed.


Installation

1
# pip
2
pip install orcher-sdk
3
4
# poetry
5
poetry add orcher-sdk
6
7
# uv
8
uv add orcher-sdk

The package is orcher-sdk and it imports as orcher. The package named orcher on PyPI is the command-line tool, not the SDK.

Requirements

  • Python 3.11 or later (CPython).
  • An Orcher engine to connect to. The quickstart starts one on your machine.
  • pip installs a prebuilt wheel on macOS (arm64 and x86_64) and Linux (x86_64 and aarch64, glibc or musl). Anywhere else it builds the SDK's native core from source, which needs a Rust toolchain.

The SDK is pre-1.0 (this guide covers orcher-sdk 0.4): its API may change between minor releases, and each breaking change is listed in the changelog.


Quick start

1. Define tasks

A task is an async function decorated with @task. Tasks are where side effects go: calls to other services, database writes, emails. The engine retries a failed task according to its retry policy.

1
from datetime import timedelta
2
3
from orcher import RetryPolicy, TaskContext, task
4
5
6
@task(
7
name="charge-payment",
8
retry_policy=RetryPolicy(
9
max_attempts=3,
10
initial_interval=timedelta(seconds=1),
11
backoff_coefficient=2.0,
12
),
13
)
14
async def charge_payment(ctx: TaskContext, amount: int, token: str) -> dict:
15
# Call your payment provider here, passing an idempotency key.
16
# A failure is retried: 3 attempts in all, 1s then 2s apart.
17
charge_id = f"ch_{token}_{amount}"
18
return {"charge_id": charge_id, "amount": amount, "status": "succeeded"}
19
20
21
@task(name="reserve-inventory")
22
async def reserve_inventory(ctx: TaskContext, order_id: str) -> dict:
23
# Call your inventory service here.
24
return {"reservation_id": f"res_{order_id}"}

2. Define a workflow

A workflow is an async function decorated with @workflow. It decides which tasks run and in what order. Its code is replayed from the journal every time it resumes, so it must be deterministic: do I/O in tasks, not in the workflow.

1
from orcher import WorkflowContext, workflow
2
3
from tasks import charge_payment, reserve_inventory
4
5
6
@workflow(name="process-order", version="1.0", description="Process customer order")
7
async def process_order(ctx: WorkflowContext, order_id: str, amount: int, token: str) -> dict:
8
payment = await ctx.execute_task(charge_payment, amount=amount, token=token)
9
inventory = await ctx.execute_task(reserve_inventory, order_id=order_id)
10
11
return {
12
"order_id": order_id,
13
"status": "completed",
14
"charge_id": payment["charge_id"],
15
"reservation_id": inventory["reservation_id"],
16
}

3. Run a worker

A worker connects to the engine, registers every workflow and task whose module has been imported, and runs them.

1
import asyncio
2
import signal
3
4
from orcher import Worker
5
6
# Importing the modules registers their @workflow and @task functions.
7
import workflows # noqa: F401
8
import tasks # noqa: F401
9
10
11
async def main() -> None:
12
worker = (
13
Worker.builder()
14
.server_url("http://localhost:50051")
15
.namespace("default")
16
.task_queue("orders")
17
.build()
18
)
19
20
# Drain in-flight work on Ctrl-C or SIGTERM.
21
loop = asyncio.get_running_loop()
22
for sig in (signal.SIGTERM, signal.SIGINT):
23
loop.add_signal_handler(sig, lambda: asyncio.create_task(worker.shutdown()))
24
25
await worker.run()
26
27
28
if __name__ == "__main__":
29
asyncio.run(main())

If the engine requires an API key, set ORCHER_API_KEY in the worker's environment; the builder reads it.

4. Start a workflow

1
import asyncio
2
import os
3
4
from orcher import Client, ClientConfig
5
6
7
async def main() -> None:
8
config = ClientConfig(
9
server_url="http://localhost:50051",
10
namespace="default",
11
api_key=os.environ.get("ORCHER_API_KEY"), # only if the engine requires one
12
)
13
14
async with Client(config) as client:
15
handle = await client.start_workflow(
16
"process-order",
17
workflow_id="order-123",
18
task_queue="orders",
19
# A dict reaches the workflow as keyword arguments.
20
args=({"order_id": "ord_123", "amount": 9999, "token": "tok_visa"},),
21
)
22
23
print(f"Started workflow: {handle.workflow_id}")
24
result = await handle.result(timeout=60.0)
25
print("Order completed:", result)
26
27
28
if __name__ == "__main__":
29
asyncio.run(main())

Next steps

  • Workflows: the WorkflowContext API, determinism and replay
  • Tasks: retries, heartbeats, cancellation and payload limits
  • Client: start, query and manage workflows
  • Worker: configuration, authentication and shutdown
  • Actors: keyed objects with durable state
  • Sessions: run several tasks on one worker
  • Testing: run workflows in memory with mocked tasks
  • Patterns: compensation, fan-out, approvals and batches