excelflow 0.2.0

Excel-declared data extraction powered by Pandas

ExcelFlow

ExcelFlow 是一个由 Excel 计划驱动的数据抽取工具。业务用户在模板中声明需要读取的 Sheet、关联方式、过滤条件、输出字段和衍生列，ExcelFlow 使用 Pandas 执行这些规则并输出 CSV、JSONL 或 Excel。

适合解决的问题

• 从一个 Excel Sheet 中选择、重命名和转换字段。
• 使用结构化条件筛选数据，而不需要编写代码。
• 在同一个工作簿中关联多个 Sheet。
• 通过安全表达式计算金额、差值和超窗天数等衍生列。
• 按一个或多个字段分组，进行计数、求和、平均值等汇总。
• 将同一份抽取计划保存、审核、复用和纳入版本管理。

安装

推荐使用 uv 安装为独立命令行工具：

uv tool install excelflow

也可以使用 pipx：

pipx install excelflow

详细说明参见安装指南。

五分钟快速开始

生成计划模板：

excelflow template --output extraction_plan.xlsx

填写模板后，依次校验、预览和执行。假设任务ID为 order_report，源数据为 source.xlsx：

excelflow validate --plan extraction_plan.xlsx
excelflow preview --plan extraction_plan.xlsx --task order_report
excelflow run --plan extraction_plan.xlsx --task order_report \
  --source source.xlsx --format csv --output output/order_report.csv

完整操作过程参见快速开始和模板填写完整教程。

核心能力

• 单 Sheet 与多 Sheet 数据抽取。
• INNER JOIN、LEFT JOIN、多级关联和复合关联键。
• AND/OR 条件组及 13 种过滤运算符。
• integer、decimal、string、datetime 输出类型。
• 字符串、数值、日期、类型转换和 if_else 等安全逐行函数。
• count、count_distinct、sum、avg、concat_agg 等分组聚合。
• CSV、JSONL、XLSX 输出。
• 计划校验和 Pandas 执行计划预览。

文档

• 在线文档
• 文档首页
• 安装指南
• 核心概念
• 模板填写完整教程
• 模板字段参考
• 过滤运算符参考
• 表达式参考
• 命令行参考
• 故障排查

示例

examples/ 提供五个递进案例：单 Sheet、过滤、关联、衍生列和分组聚合。示例计划和源数据可以直接运行。

安全边界

字段转换由受限 AST 解释器执行，不使用 Python eval()。表达式只能访问已声明的源字段、常量和受支持函数，不能执行文件操作、系统命令或任意 Python 代码。

参与项目

• 贡献指南
• 开发环境
• 架构说明
• 测试指南
• 安全策略
• 变更记录

源码托管于 GitHub，问题和功能建议请提交到 GitHub Issues。

ExcelFlow 使用 MIT License 发布。