GoodLark (飞书表格 Python 助手)

GoodLark (goodlark.py) 是一个基于 lark-oapi 封装的 Python 类库，旨在简化飞书（Lark）电子表格的本地调用与数据交互。

它封装了繁琐的 API 请求细节，提供了针对 Pandas DataFrame 的直接读写支持、大批量数据的自动分批处理、进度条显示以及自动 Token 刷新机制。

😀😀😀 Wish you GOOD LARK!

功能特性

• 自动鉴权：自动获取和刷新 tenant_access_token，无需担心 Token 过期（v1.1 新增）。
• Pandas 深度集成：
  • 支持直接将飞书表格读取为 DataFrame。
  • 支持将 DataFrame、Dict 或 List 直接写入飞书表格。
• 批量读写优化：
  • 读取/写入大数据量时自动分批（Batch）处理。
  • 集成 tqdm 进度条，实时显示处理进度。
  • 内置重试机制，应对网络波动。
• 数据清洗：
  • 写入时自动处理 np.nan、None 等空值。
  • 读取时自动去除全空行和无效列。
• 表格管理：支持创建电子表格、新增 Sheet、获取 Sheet ID 映射等。

依赖安装

在使用本库之前，请确保已安装以下 Python 依赖库：

pip install lark-oapi pandas requests requests-toolbelt tqdm fastapi

快速开始

1. 初始化

首先需要创建一个飞书自建应用，并获取 App ID 和 App Secret。

from goodlark import goodlark
# 填入你的飞书应用凭证
APP_ID = "cli_a1b2c3d4e5"
APP_SECRET = "your_app_secret_here"
# 初始化实例
gl = goodlark(APP_ID, APP_SECRET)

2. 读取数据 (Read)

将表格数据读取为 DataFrame：

spreadsheet_token = "shtcn......" # 电子表格的 Token (URL 中可找到)
sheet_name = "Sheet1"
# 读取从第1行到100行，A列到K列的数据
df = gl.load_sheet_data_to_df(
    spreadsheet_token = spreadsheet_token,
    sheet_name = sheet_name,
    row_id_start = 1,
    row_id_end = 100,
    col_id_start = "A",
    col_id_end = "K",
    batch_size = 200  # 可选：每批次读取行数
)
print(df.head())

交互式读取（命令行向导）：

如果你不想手动输入参数，可以使用交互模式：

df = gl.select_from_sheet_to_df()
# 跟随终端提示输入 Token、范围等信息即可

3. 写入数据 (Write)

批量写入 DataFrame (推荐)：

适用于大量数据写入，会自动处理分批和进度条。

import pandas as pd
import numpy as np
# 准备数据
data = {
    '姓名': ['张三', '李四', '王五'],
    '年龄': [25, np.nan, 30],  # 自动处理 NaN 为空单元格
    '部门': ['技术部', '产品部', '运营部']
}
df_to_write = pd.DataFrame(data)
# 写入数据
gl.batch_write_multi_data(
    spreadsheet_token = spreadsheet_token,
    sheet_name = "Sheet1",
    start_loc = "A1",       # 从 A1 单元格开始写入
    input_data = df_to_write,
    batch_size = 100        # 每批次写入行数
)

写入单个单元格：

gl.write_single_data(spreadsheet_token, "Sheet1", "E5", "通过")

4. 表格管理 (Manage)

新建电子表格：

请确保自建应用有文件夹权限，快捷方式：将自建应用拉入群聊，并为该群开通文件夹权限

# folder_token 为飞书云文档文件夹的 token
res = gl.create_spreadsheet(folder_token = "fld......", spreadsheet_name = "核心指标")
print(res['url'])

新建 Sheet 页：

gl.create_sheet(spreadsheet_token, "新数据")

获取 Sheet 名称与 ID 的映射：

mapping = gl.get_name_id_dict(spreadsheet_token)
print(mapping) 
# 输出示例: {'Sheet1': 'xxxxxx', '2月数据': 'yyyyyy'}

注意事项

1. 权限设置：
   • 读写权限：请确保你的飞书机器人（Bot）已被添加为该电子表格的协作者，或者表格所在的文件夹已对 Bot 授权。
   • 创建权限：使用 create_spreadsheet 时，Bot 必须拥有目标文件夹的编辑权限。
2. API 频率限制：
   • 代码内部已针对批量写入（batch_write_multi_data）和读取做了简单的重试机制（Retries），但若数据量极大，建议适当调整 batch_size（建议 50-200）以避免触发飞书服务端的限流。
3. 数据覆盖：
   • 写入操作会覆盖目标范围内的现有数据，请谨慎操作。

方法列表

1. 功能性方法

这些是底层的辅助方法，通常用于数据转换或获取必要的 ID 信息，也可以独立调用。

方法名	参数	描述
get_tenant_access_token	无	核心鉴权。向飞书服务器请求并返回有效的 tenant_access_token。类内部会自动调用此方法，通常无需手动使用。
get_name_id_dict	spreadsheet_token	ID 映射。传入电子表格 Token，返回该表格下所有 Sheet 的 {名称: ID} 字典。用于需要 sheet_id 的场景。
to_2d_list	input_data	格式转换。将 pandas.DataFrame 或 dict 转换为符合飞书 API 标准的二维列表（List of Lists）。
complete_data_range	start_loc, input_data	范围计算。基于起始单元格（如 "A1"）和数据形状，自动计算完整的写入范围（如 "A1:C10"）。
generate_col_order_info	无	列标生成。生成 Excel 风格的列标映射字典（A-ZZ），用于内部坐标计算。包含 列名→数字 和 数字→列名 的双向映射。

2. 创建电子表格与Sheet

用于在飞书云文档中新建文件或在表中创建子表。

方法名	参数	描述
create_spreadsheet	folder_token, spreadsheet_name	新建表格。在指定的飞书文件夹下创建一个新的电子表格。 注意：Bot 需要对该文件夹拥有编辑权限。
create_sheet	spreadsheet_token, sheet_name	新建 Sheet。在指定的电子表格中新增一个工作表。

3. 读取飞书表格

支持原始数据读取和 Pandas DataFrame 封装读取。

方法名	参数	描述
load_sheet_data_to_df	spreadsheet_token, sheet_name, row_id_start, row_id_end, col_id_start, col_id_end, batch_size, target_column_names	读取为 DataFrame。指定行列范围，将数据读取并清洗为 Pandas DataFrame。 支持分批读取（带有进度条）以应对大量数据。
load_data_from_sheet	spreadsheet_token, sheet_name, data_range	原始读取。指定范围（如 "A1:E10"），返回原始的二维列表数据。
select_from_sheet_to_df	可选参数	交互式读取。load_sheet_data_to_df 的交互式包装器。未传入的参数会通过终端询问用户（如输入Token、范围等），适合脚本调试使用。

4. 写入飞书表格

支持单单元格、多行以及批量多行写入，内置了空值处理。

方法名	参数	描述
batch_write_multi_data	spreadsheet_token, sheet_name, start_loc, input_data, batch_size	批量写入 (推荐)。支持 DataFrame/List/Dict。将大数据自动切分为小批次写入（避免报错 90227），并显示进度条。自动处理 NaN/None 为空值。
write_multi_data	spreadsheet_token, sheet_name, start_loc, input_data	单次写入。一次性写入多行数据。适用于少量数据，若数据量过大会自动抛出异常并建议改用 batch 方法。
write_single_data	spreadsheet_token, sheet_name, start_loc, input_data	单点写入。在指定单元格（如 "A1"）写入单个值。
select_batch_write_multi_data	input_data, 可选参数	交互式写入。batch_write_multi_data 的交互式包装器。未传入的表格信息会通过终端询问用户，只需提前准备好数据对象即可。

💡 使用建议

1. 日常数据分析：主要使用 load_sheet_data_to_df (读) 和 batch_write_multi_data (写)。
2. 脚本调试：可以使用 select_... 开头的方法，省去查阅和复制粘贴 Token 的麻烦。
3. 工具开发：如果需要开发更复杂的逻辑，可以利用 to_2d_list 和 get_name_id_dict 等底层工具构建自己的流程。

版本记录

• v 1.1
  • [优化] 移除 self.bearer_token 属性，改为按需动态获取，解决 Token 两小时过期问题。
  • [优化] 核心读写方法增加 Token 自动刷新机制。
• v 1.0
  • 解决 np.nan、None 无法写入飞书表格的问题。

作者

@ Wu, J. J. Based on Lark Open API

https://github.com/jwj1111/goodlark