wecom-smartsheet 0.2.0

WeCom SmartSheet Python SDK with full CRUD operations support

WeCom SmartSheet Python SDK

企业微信智能表格 Python SDK，提供完整的 CRUD 操作支持。

功能特性

• ✅ 完整的 CRUD 操作

  • 读取记录（支持分页、过滤、转换）
  • 新增记录（单条/批量）
  • 更新记录（单条/批量）
  • 删除记录（单条/批量）

• ✅ 自动 Token 管理

  • 自动获取和缓存 access_token
  • Token 过期自动刷新

• ✅ 灵活的数据导出

  • 导出为 JSON 格式
  • 导出为 CSV 格式（支持 Excel）

• ✅ 命令行工具

  • 提供 wecom-smartsheet-fetch CLI 工具

安装

pip install wecom-smartsheet

快速开始

初始化客户端

from wecom_smartsheet import WeComSmartSheetClient

client = WeComSmartSheetClient(
    corpid="your_corpid",
    corpsecret="your_corpsecret"
)

读取记录

# 读取所有记录
records = client.fetch_records(
    docid="your_docid",
    sheet_id="your_sheet_id"
)

# 读取并转换为扁平格式
records = client.fetch_records(
    docid="your_docid",
    sheet_id="your_sheet_id",
    transform="flat"
)

新增记录

# 新增单条记录
result = client.add_records(
    docid="your_docid",
    sheet_id="your_sheet_id",
    records={
        "values": {
            "字段1": [{"text": "值1", "type": "text"}],
            "字段2": [{"text": "值2", "type": "text"}]
        }
    }
)

# 批量新增记录
result = client.add_records(
    docid="your_docid",
    sheet_id="your_sheet_id",
    records=[
        {"values": {"字段1": [{"text": "值1", "type": "text"}]}},
        {"values": {"字段1": [{"text": "值2", "type": "text"}]}}
    ]
)

更新记录

# 更新单条记录
result = client.update_records(
    docid="your_docid",
    sheet_id="your_sheet_id",
    records={
        "record_id": "rec123",
        "values": {
            "字段1": [{"text": "新值", "type": "text"}]
        }
    }
)

# 批量更新记录
result = client.update_records(
    docid="your_docid",
    sheet_id="your_sheet_id",
    records=[
        {"record_id": "rec1", "values": {"字段1": [{"text": "新值1", "type": "text"}]}},
        {"record_id": "rec2", "values": {"字段1": [{"text": "新值2", "type": "text"}]}}
    ]
)

删除记录

# 删除单条记录
result = client.delete_records(
    docid="your_docid",
    sheet_id="your_sheet_id",
    record_ids="rec123"
)

# 批量删除记录
result = client.delete_records(
    docid="your_docid",
    sheet_id="your_sheet_id",
    record_ids=["rec1", "rec2", "rec3"]
)

导出数据

# 导出为 JSON
client.fetch_records_to_json(
    docid="your_docid",
    sheet_id="your_sheet_id",
    output_path="output.json"
)

# 导出为 CSV
client.fetch_records_to_csv(
    docid="your_docid",
    sheet_id="your_sheet_id",
    output_path="output.csv"
)

错误处理

from wecom_smartsheet import WeComSmartSheetClient, WeComAPIError

client = WeComSmartSheetClient(corpid="...", corpsecret="...")

try:
    result = client.add_records(
        docid="your_docid",
        sheet_id="your_sheet_id",
        records={"values": {"字段1": [{"text": "值", "type": "text"}]}}
    )
except ValueError as e:
    print(f"参数错误: {e}")
except WeComAPIError as e:
    print(f"API 错误: {e}")

命令行工具

安装后可以使用 wecom-smartsheet-fetch 命令：

wecom-smartsheet-fetch --help

配置参数

获取配置参数

• corpid: 企业微信管理后台 -> 我的企业 -> 企业 ID
• corpsecret: 企业微信管理后台 -> 应用管理 -> 自建应用 -> Secret
• docid: 智能表格文档 URL 中的文档 ID
• sheet_id: 智能表格中的工作表 ID

高级用法

分页控制

records = client.fetch_records(
    docid="your_docid",
    sheet_id="your_sheet_id",
    page_size=100,        # 每页记录数
    max_pages=10,         # 最大页数
    pause_seconds=0.1     # 页面间暂停时间
)

视图过滤

records = client.fetch_records(
    docid="your_docid",
    sheet_id="your_sheet_id",
    view_id="your_view_id"  # 使用特定视图
)

系统要求

• Python >= 3.10
• 无外部依赖（仅使用 Python 标准库）

许可证

MIT License

更新日志

v0.2.0 (2026-03-03)

• ✨ 新增 add_records 方法（新增记录）
• ✨ 新增 update_records 方法（更新记录）
• ✨ 新增 delete_records 方法（删除记录）
• 📝 添加完整的使用示例和文档

v0.1.0 (2026-02-13)

• 🎉 初始版本
• ✨ 实现 fetch_records 方法（读取记录）
• ✨ 支持 JSON 和 CSV 导出
• ✨ 提供命令行工具

贡献

欢迎提交 Issue 和 Pull Request！

支持

如有问题，请在 GitHub 上提交 Issue。