Skip to content

Getting started

Install Duron with uv pip install duron in Python 3.11 or later. Run the complete README example, or from this repository:

uv run python examples/hello_world.py hello.db

The first invocation prints its effect's greeting. Reusing the database and run ID returns the committed result without performing the effect again.

Define workflows and effects

A workflow coordinates durable operations through WorkflowContext. Effects perform external I/O through ordinary async Python. Annotate their first parameter as WorkflowContext or EffectContext, and annotate arguments and results. Call effects with await ctx.call(effect, ...).

import duron


@duron.effect
async def greet(_ctx: duron.EffectContext, name: str) -> str:
    return f"Hello, {name}!"


@duron.workflow(name="greetings.hello")
async def hello(ctx: duron.WorkflowContext, name: str) -> str:
    return await ctx.call(greet, name)


async def example() -> str:
    async with duron.SQLiteScheduler("app.db", workflows=[hello]) as scheduler:
        run = await scheduler.submit(hello, "hello-alice", "Alice")
        return await run.result()

Entering the scheduler context creates the database and starts execution. workflows=[hello] registers the code needed to execute and recover runs. Use ":memory:" for a temporary database in tests.

Submit and observe runs

A run ID identifies one business operation. submit(workflow_or_ref, run_id, ...) saves the workflow contract and arguments, including defaults, before returning a handle. Retrying the same submission returns the existing run. Reusing the ID with different arguments or a different reference raises SubmissionConflictError. Use a new ID to start a new operation.

To observe an existing run, call await scheduler.open(hello, "hello-alice"). This checks its contract without creating another run. An unknown ID raises RunNotFoundError.

Use the handle to observe or interact with the run:

Operation Purpose
await run.result() Wait for the result or raise the run's error.
await run.status() Read its current state and scheduling diagnostic.
await run.cancel() Request cancellation.
run.port(declaration) Send input or read output through a declared port.

Dropping a handle or cancelling a task waiting on result() leaves the workflow running. cancel() requests cancellation explicitly. Repeated requests are safe, but completion can still win the race. A cancelled run's result() raises RunCancelledError.

Close and reopen the scheduler

Closing the scheduler stops local execution and waits for effect cleanup. It does not request cancellation of persisted runs. To recover unfinished work, open the same database with the workflow implementations registered. You do not need to submit the runs again.

During recovery, completed effects return their recorded outcomes. An effect call without a recorded outcome blocks the run and is never invoked again. Reconcile any uncertain external changes before starting a new run. See recovery for details.

Only one active scheduler can own a database file, across all namespaces. Close it before opening another; a second active owner raises StorageError. Run IDs are unique within the configured namespace. Unsupported database schemas are rejected without migration or replacement.

Runs execute concurrently without a scheduler concurrency limit. A run waiting for input or a durable deadline can suspend after 60 idle seconds to free resources. Input delivery, cancellation, or the deadline resumes it. Set idle_timeout to change the grace period. Runs with active effects stay loaded.

Interactive workflows

Declare optional ports on a PortSet:

class Ports(duron.PortSet):
    items = duron.Input[str]()
    events = duron.Output[str]()


@duron.workflow(ports=Ports)
async def process(ctx: duron.WorkflowContext) -> str:
    item = await ctx.port(Ports.items).receive()
    await ctx.port(Ports.events).emit(item)
    return item

Applications send through run.port(Ports.items) and read run.port(Ports.events). Sends return after durable enqueueing, without waiting for workflow acceptance. Output cursors let readers resume after reconnection.

Effects have optional ports too. Use async with ctx.start(effect) as job, interact through job.port(...), and await job. ctx.select(...) chooses among named inputs and awaitables while preserving losing input messages.

Workflow references and contracts

Workflow[P, T, Ports] contains executable code; workflow.ref is an executable-free WorkflowRef[P, T, Ports]. Producers can declare shared references with @duron.workflow_ref(name=..., ports=...) on an annotated contract stub. The stub body is discarded. The scheduler must have an implementation registered to execute the run; references never trigger automatic Python imports.

Use workflow.ref when the executable definition is available.

Submitting or opening an executable workflow registers its code locally if no implementation is registered under that name. Passing a reference does not.

A reference describes the workflow's name, arguments, result, ports, and codec. The submitting code and implementation must agree on this contract. Runs without an implementation stay blocked until compatible code is registered.

Names default to the function's module and qualified name and can be overridden with name=.... Keep changes compatible with existing runs, or choose a new name for incompatible definitions. See definition identity for the full rules.

Write workflows that can replay

Keep workflow control flow deterministic. Use ctx.now(), ctx.random(), and ctx.sleep() for replay-safe time, randomness, and deadlines. Committed effect results replay; a committed call without a final outcome blocks the run. Use stable application operation IDs to reconcile uncertain external work.

See workflow ports, effect runs, recovery, and storage.