iii-python-sdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python SDK

The async Python SDK for connecting workers to the iii engine.

用于将worker连接至iii引擎的异步Python SDK。

Documentation

文档

Full API reference: https://iii.dev/docs/api-reference/sdk-python

完整API参考：https://iii.dev/docs/api-reference/sdk-python

Install

安装

pip install iii-sdk

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_connection_state_change(callback)`	Monitor connection state
`register_trigger(type, fn_id, config, metadata?)`	Bind a trigger with optional metadata

导出项	用途
`register_worker(address, options?)`	连接至引擎，返回客户端
`InitOptions(worker_name, otel?)`	连接配置
`register_function(id, handler)`	注册异步函数处理器
`register_trigger(type, function_id, config)`	将触发器绑定至函数
`trigger(request)`	同步调用函数
`trigger_async(request)`	异步调用函数
`get_context()`	在处理器内访问日志和追踪上下文
`ApiRequest` / `ApiResponse`	HTTP请求/响应类型（基于pydantic）
`IStream`	自定义流实现的接口
`on_connection_state_change(callback)`	监控连接状态
`register_trigger(type, fn_id, config, metadata?)`	绑定触发器并可附加元信息

Key Notes

关键注意事项

```
register_worker()
```
returns a synchronous client; handlers are async
```
ApiResponse
```
uses camelCase
```
statusCode
```
(pydantic alias), not
```
status_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 synchronous
```
trigger(request)
```
. Use
```
trigger_async
```
inside async handlers, and
```
trigger
```
in synchronous scripts or threads where blocking behavior is desired.

For discovery reads and topology subscriptions, call the built-in engine functions with

trigger()

trigger_async()

and bind

engine::functions-available

with

register_trigger()

. See

/docs/how-to/discover-workers-functions-triggers

```
register_worker()
```
返回同步客户端；处理器为异步类型
```
ApiResponse
```
使用小驼峰命名的
```
statusCode
```
（pydantic别名），而非
```
status_code
```
需通过
```
while True: await asyncio.sleep(60)
```
维持事件循环运行，避免worker退出
处理器内的CPU密集型同步任务可使用
```
asyncio.to_thread()
```
处理
SDK同时实现了
```
trigger_async(request)
```
和同步版
```
trigger(request)
```
。在异步处理器内使用
```
trigger_async
```
，在同步脚本或线程中若需阻塞行为则使用
```
trigger
```
。

如需进行发现读取和拓扑订阅，可通过

trigger()

trigger_async()

调用内置引擎函数，并使用

register_trigger()

绑定

engine::functions-available

。详见

/docs/how-to/discover-workers-functions-triggers

。

Examples

示例

python

undefined

python

undefined

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"} })

undefined

result = iii.trigger({ "function_id": "greet", "payload": {"name": "World"} })

undefined

Pattern Boundaries

模式边界

For usage patterns and working examples, see
```
iii-functions-and-triggers
```
For HTTP middleware patterns, see
```
iii-http-middleware
```
For Node.js SDK, see
```
iii-node-sdk
```
For Rust SDK, see
```
iii-rust-sdk
```
For browser-side usage, see
```
iii-browser-sdk
```

如需使用模式和工作示例，请查看
```
iii-functions-and-triggers
```
如需HTTP中间件模式，请查看
```
iii-http-middleware
```
如需Node.js SDK，请查看
```
iii-node-sdk
```
如需Rust SDK，请查看
```
iii-rust-sdk
```
如需浏览器端使用方式，请查看
```
iii-browser-sdk
```

When to Use

使用场景

Use this skill when the task is primarily about
```
iii-python-sdk
```
in the iii engine.
Triggers when the request directly asks for this pattern or an equivalent implementation.

当任务主要涉及iii引擎中的
```
iii-python-sdk
```
时，使用此技能。
当请求直接询问此模式或等效实现时触发。

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.

切勿将此技能作为无关任务的通用回退方案。
当有更特定的iii技能更合适时，不得使用此技能。
在应用此技能中的示例前，务必验证环境和安全约束。