Skip to main content

Durable functions in Python

Durable functions can be written in Python as well as TypeScript. A Python function issues exactly the commands its TypeScript twin would and records the same event history, so everything on the other pages (activities, timers, signals, child runs, versioning, run control) works the same way. Python durable functions run on the managed queue, in an isolated sandbox with no network, or on your own self-hosted workers.

A first Python durable function​

Create a Python project (Python 3.11 or later) and install the SDK:

fluidgrids init --lang py
pip install fluidgrids-workflows
workflows/process_order.py
from fluidgrids_workflows import triggers
from fluidgrids_workflows.durable import define_signal, workflow
from fluidgrids_workflows.project import nodes as n

approve = define_signal("approve")


@workflow("process-order", trigger={"operation": triggers.webhook, "args": {"path": "orders"}})
async def processOrder(ctx, order):
charge = await ctx.run(n.stripe.create_charge, args={"amount": order["amount"]})
await ctx.signal_received(approve)
await ctx.sleep("1h")
return {"charge": charge["id"]}

Push it with fluidgrids push. The CLI builds the project into a deterministic bundle (.pyz) with python -m fluidgrids_workflows build, the same build FluidGrids runs for the in-browser editor, so both produce the same build id for the same sources.

The Python API​

The workflow context has the same calls as in TypeScript, in Python spelling:

PythonDoes
await ctx.run(operation, args=..., retry=..., start_to_close_timeout=...)Run a FluidGrids node operation as an activity
await ctx.activity(declaration, args=...)Run a user activity on a self-hosted worker
await ctx.sleep("1h"), await ctx.condition(predicate, timeout)Durable timers and waits
await ctx.signal_received(signal), ctx.on_signal(signal, handler)Receive signals
ctx.handle_query(query, handler), ctx.handle_update(update, handler, validate=...)Answer queries and handle updates (see Run control)
await ctx.child(workflow, ...)Start a child run
ctx.gather(...), ctx.race(...)Wait for several awaitables
ctx.patched(id)Change running code safely
ctx.now(), ctx.random(), ctx.uuid()Deterministic values
ctx.upsert_search_attributes({...})Set search attributes
ctx.continue_as_new(input)Start a fresh history

Declare signals, queries and updates with define_signal, define_query and define_update, and user activities with declare_activity (implemented with define_activity or implement_activity in the worker).

The rules of workflow code​

The same rules as in TypeScript apply, and Python enforces them with an import guard: workflow modules cannot read the clock or randomness, touch the file system or the network, or start processes. Use ctx.now(), ctx.random(), ctx.uuid() and activities instead. Workflow code awaits only what the context returns; plain asyncio tasks and sleeps are not allowed.

Generated node clients are imported with from fluidgrids_workflows.project import nodes as n. A bundle carries only the clients your workflow modules name, so the bundle stays small even when the workspace has thousands of nodes. A client reached only through a name built at run time is not carried, and the build says which one.

Editing in the browser​

Python durable functions can be edited in the builder like TypeScript ones: open the Code workflow node's Source tab, edit, select Check to build the project and list any problems, then Save as new version. See The in-browser editor.

Testing​

TestWorkflowEnvironment (in fluidgrids_workflows.testing.environment) runs workflows in process with time skipping, activity mocks, user activities, signals, queries, updates, cancellation and resets. replay_history checks a recorded history against your current code. fluidgrids test runs python -m fluidgrids_workflows test for a project with a tests/ folder and then replays recorded histories; fluidgrids replay <history> replays one. See Testing and replay.

Python workers​

fluidgrids_workflows.worker.Worker (with the worker extra) runs Python bundles and Python user activities on your machines, and fluidgrids worker run uses it for Python projects. See Self-hosted workers.

Next steps​