Python SDK
The async Python SDK for connecting workers to the iii engine.
Documentation
Full API reference: https://iii.dev/docs/api-reference/sdk-python
Install
pip install iii-sdk
Key Exports
| Export | Purpose |
|---|---|
register_worker(address, options?) | Connect to the engine, returns the client |
InitOptions(worker_name, otel?) | Connection configuration |
register_function(id, handler) | Register an async function handler |
register_trigger(type, function_id, config) | Bind a trigger to a function |
trigger(request) | Invoke a function synchronously |
trigger_async(request) | Invoke a function asynchronously |
get_context() | Access logger and trace context inside handlers |
ApiRequest / ApiResponse | HTTP request/response types (pydantic) |
IStream | Interface for custom stream implementations |
on_functions_available(callback) | Listen for function discovery |
on_connection_state_change(callback) | Monitor connection state |
Key Notes
register_worker()returns a synchronous client; handlers are asyncApiResponseuses camelCasestatusCode(pydantic alias), notstatus_code- End workers with
while True: await asyncio.sleep(60)to keep the event loop alive - Use
asyncio.to_thread()for CPU-heavy sync work inside handlers - The SDK implements both
trigger_async(request)and a synchronoustrigger(request). Usetrigger_asyncinside async handlers, andtriggerin synchronous scripts or threads where blocking behavior is desired.
Examples
# Async invocation (non-blocking, typical inside handlers)
result = await iii.trigger_async({
"function_id": "greet",
"payload": {"name": "World"}
})
# Sync invocation (blocks the current thread, useful in sync contexts)
result = iii.trigger({
"function_id": "greet",
"payload": {"name": "World"}
})Pattern Boundaries
- For usage patterns and working examples, see
iii-functions-and-triggers - For Node.js SDK, see
iii-node-sdk - For Rust SDK, see
iii-rust-sdk
When to Use
- Use this skill when the task is primarily about
iii-python-sdkin the iii engine. - Triggers when the request directly asks for this pattern or an equivalent implementation.
Boundaries
- Never use this skill as a generic fallback for unrelated tasks.
- You must not apply this skill when a more specific iii skill is a better fit.
- Always verify environment and safety constraints before applying examples from this skill.