Wolai Python SDK

Wolai API 的 Python 客户端库，提供完整的 Wolai API 接口封装。

安装

pip install wolai

或者从源码安装：

git clone https://github.com/yourusername/wolai-python.git
cd wolai-python
pip install -e .

快速开始

from wolai import WolaiClient

# 初始化客户端
# Token 格式：直接使用从 Wolai 获取的 API Token
client = WolaiClient(token="your_api_token")
# 注意：Token 会直接添加到 authorization 请求头中（不需要 Bearer 前缀）

# 获取页面信息
page = client.get_page("page_id")

# 获取块信息
block = client.get_block("block_id")

# 创建块
new_block = client.create_block(
    parent_id="parent_block_id",
    blocks=[
        {
            "type": "text",
            "content": "Hello, Wolai!"
        }
    ]
)

# 获取数据库数据
database = client.get_database("database_id")

# 添加数据库记录
client.add_database_rows("database_id", rows=[...])

功能特性

• ✅ 完整的块操作（查询、创建）
• ✅ 数据库操作（查询、添加记录）
• ✅ 支持所有块类型
• ✅ 类型安全的 Python 对象模型

API 接口列表

块操作接口

1. 查询块详情

block = client.get_block(block_id="block_id")

2. 创建块

# 注意：parent_id 必须是有效的 UUID 格式
# 可以通过 client.get_page() 或 client.get_block() 获取有效的块ID
parent_page = client.get_page("有效的页面UUID")
blocks = client.create_block(
    parent_id=parent_page.id,  # 使用有效的 UUID
    blocks=[
        {
            "type": "text",
            "content": "文本内容",
            "text_alignment": "center"  # 可选: left, center, right
        },
        {
            "type": "heading",
            "level": 1,
            "content": {
                "title": "标题",
                "front_color": "red"
            },
            "text_alignment": "center"
        }
    ]
)

参考文档: 创建块 API

注意： parent_id 必须是有效的 UUID 格式，不能使用占位符如 "parent_block_id_here"

3. 创建文本块

text_block = client.create_text_block(
    parent_id="parent_block_id",
    content="文本内容",
    text_alignment="left"  # left, center, right
)

4. 创建标题块

heading_block = client.create_heading_block(
    parent_id="parent_block_id",
    content="标题内容",
    level=1,  # 1-6
    text_alignment="left"
)

# 或使用带样式的标题
styled_heading = client.create_heading_block(
    parent_id="parent_block_id",
    content={
        "title": "标题",
        "front_color": "red"
    },
    level=1
)

5. 创建待办块

todo_block = client.create_todo_block(
    parent_id="parent_block_id",
    content="待办事项",
    checked=False
)

6. 创建无序列表块

bull_list = client.create_bull_list_block(
    parent_id="parent_block_id",
    content="列表项"
)

7. 创建有序列表块

enum_list = client.create_enum_list_block(
    parent_id="parent_block_id",
    content="列表项"
)

8. 创建代码块

code_block = client.create_code_block(
    parent_id="parent_block_id",
    content="print('Hello')",
    language="python"
)

9. 创建页面块

# 创建简单页面
page_block = client.create_page_block(
    parent_id="parent_block_id",
    content="页面标题"
)

# 创建带图标和封面的页面
page_block = client.create_page_block(
    parent_id="parent_block_id",
    content="页面标题",
    icon={"type": "emoji", "emoji": "📄"},
    page_cover={"type": "external", "url": "https://example.com/image.jpg"}
)

数据库操作接口

1. 获取数据库数据

database = client.get_database(database_id="database_id")
column_order = database.get("column_order", [])
rows = database.get("rows", [])

2. 获取数据库行数据

rows = client.get_database_rows(database_id="database_id")
for row in rows:
    page_id = row.get("page_id")
    data = row.get("data", {})

3. 添加数据库记录

result = client.add_database_rows(
    database_id="database_id",
    rows=[
        {
            "标题": {
                "type": "primary",
                "value": "新任务"
            },
            "标签": {
                "type": "select",
                "value": "待完成"
            }
        }
    ]
)

块类型说明

本库支持以下块类型：

块类型	类型标识	说明
文本	text	普通文本块
标题	heading	标题块，支持1-6级，可设置颜色和对齐方式
无序列表	bull_list	无序列表项
有序列表	enum_list	有序列表项
待办	todo_list	待办事项，可设置完成状态
代码	code	代码块，可指定编程语言
图片	image	图片块
页面	page	页面块，支持图标、封面、页面设置等属性
数据库	database	数据库块

示例代码

更多示例代码请查看 examples/basic_usage.py 文件。

API 文档

详细的 API 文档请参考 Wolai 开发者文档

许可证

MIT License