Skip to content
Cloacina

Python SDK (`cloacina-client`)

This is the service client (pip install cloacina-client, import cloacina_client). The embedded workflow runtime is the separate cloaca package.

Generated from the server’s OpenAPI contract by a pinned openapi-python-client, wrapped in a hand-written shim.

Python version: cloacina-client requires Python >= 3.10 (clients/python/pyproject.toml). Note the asymmetry with the embedded runtime: the cloaca wheel is abi3 and supports Python >= 3.9 — a 3.9 interpreter can author and run workflows but cannot use this service SDK.

Tutorial: execute a workflow and follow its events

Section titled “Tutorial: execute a workflow and follow its events”
Terminal window
pip install cloacina-client
import asyncio
import os


from cloacina_client import AsyncClient, Client


client = Client("http://localhost:8080", api_key=os.environ["CLOACINA_API_KEY"], tenant="public")
accepted = client.execute_workflow("my_workflow", {"input": 42})
print("scheduled", accepted.execution_id)


async def follow() -> None:
    aclient = AsyncClient("http://localhost:8080", api_key=os.environ["CLOACINA_API_KEY"])
    async for event in aclient.follow_execution_events(accepted.execution_id):
        print(event)


asyncio.run(follow())

How-to

Section titled “How-to”

Paginate executions (sync generator; AsyncClient.iterate_executions is the async twin):

for execution in client.iterate_executions(status="Failed", page_size=100):
    print(execution.id, execution.workflow_name)

Handle errors — CloacinaApiError carries the canonical envelope:

from cloacina_client import CloacinaApiError


try:
    client.get_workflow("missing")
except CloacinaApiError as e:
    print(e.status, e.code, e.message)  # 404 workflow_not_found ...

Subscribe to raw delivery pushes:

async for push in aclient.subscribe_delivery("exec_events:<id>"):
    print(push.kind, push.payload_json())

Reconnection, dedup-on-row-id, and acks are handled inside the iterator; a 4426 close raises ProtocolVersionError (upgrade the SDK).

The Python WS surface is subscribe_delivery and follow_execution_events only — the ops-metrics stream helper (followOpsMetrics) exists in the TypeScript SDK only; from Python, subscribe to the ops_metrics:global recipient via subscribe_delivery with an admin-scoped key.

Reach past the shim — the generated openapi-python-client is exposed as client.generated for anything the helpers don’t cover.

Reference

Section titled “Reference”
  • Wire contract: OpenAPI document, WebSocket protocol
  • Generated models live under cloacina_client.models
  • Regeneration (pinned): see clients/python/README.md in the repository