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
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:
| Python | Does |
|---|---|
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.