excel-toolbox 1.0.1

一体化 Excel 数据处理工具集 - 数据整合、清洗、转换全流程解决方案

Excel Toolbox 📊

一体化 Excel 数据处理工具集 - 数据整合、清洗、转换全流程解决方案

🚀 快速开始: QUICKSTART.md
📦 安装说明: INSTALL.md
🎯 发布指南: PUBLISH_GUIDE.md
📋 发布快速参考: PUBLISH_QUICKREF.md
📊 项目总览: PROJECT_OVERVIEW.md

✨ 核心特性

• 🔗 数据聚合 - 批量合并文件 / 关联合并表
• 🧹 数据清洗 - 去重清理 / 自定义排序
• 🔄 格式转换 - CSV/JSON/Excel 跨格式互转
• 📋 元数据管理 - 自动附加来源信息
• 🎨 美化输出 - Rich 终端显示
• 🚀 双模式支持 - CLI 命令行 + Python 脚本调用

🎯 设计原则

✅ 高内聚低耦合 - 每个功能模块独立封装
✅ 强类型契约 - 完整类型提示与参数校验
✅ 防御式编程 - 精细化异常处理
✅ 零数据丢失 - 所有转换保留原始数据语义

📦 安装

方式一：使用 pip 安装（推荐）

pip install -e .

方式二：安装依赖后直接使用

pip install -r requirements.txt

🚀 快速开始

CLI 命令行模式

1. 合并文件夹内所有 Excel 文件

# 仅合并首表
excel-toolbox merge ./monthly_reports merged.xlsx

# 合并所有工作表
excel-toolbox merge ./monthly_reports merged_all.xlsx --all-sheets

2. 两表关联合并

# Inner Join（内连接）
excel-toolbox join customers.xlsx orders.xlsx result.xlsx \
  --left-on customer_id \
  --right-on cust_id \
  --how inner

# Left Join（左连接）
excel-toolbox join customers.xlsx orders.xlsx result.xlsx \
  -l customer_id \
  -r cust_id \
  --how left

# 多键关联（CLI 模式暂不支持多键，请使用 Python API）

3. 去除重复数据

# 全行去重
excel-toolbox dedup data.xlsx --output cleaned.xlsx

# 按指定列去重
excel-toolbox dedup data.xlsx \
  --output cleaned.xlsx \
  --subset ID,Name

# 保留最后一次出现
excel-toolbox dedup data.xlsx \
  -o cleaned.xlsx \
  -s ID \
  --keep last

# 覆盖原文件
excel-toolbox dedup data.xlsx --inplace

4. 按模板自定义排序

# 基本排序
excel-toolbox sort data.xlsx template.xlsx sorted.xlsx \
  --main-col product_id \
  --template-col id

# 未匹配项置于底部
excel-toolbox sort data.xlsx template.xlsx sorted.xlsx \
  -m category \
  -t category_order \
  --unmatched bottom

5. CSV 转 Excel

# 默认 UTF-8 编码
excel-toolbox csv2excel data.csv

# 指定输出路径和编码
excel-toolbox csv2excel data.csv \
  --output result.xlsx \
  --encoding gbk

# 自定义分隔符（分号分隔）
excel-toolbox csv2excel data.csv \
  -o result.xlsx \
  --delimiter ";"

6. JSON 转 Excel

# 顶层数组 JSON
excel-toolbox json2excel data.json

# 嵌套对象，指定路径
excel-toolbox json2excel api_response.json \
  --output users.xlsx \
  --pointer data.users

# 复杂路径示例
excel-toolbox json2excel api.json \
  -o items.xlsx \
  -p response.data.items

7. Excel 转 JSON

# 默认第一个工作表
excel-toolbox excel2json data.xlsx

# 指定工作表名称
excel-toolbox excel2json data.xlsx \
  --output result.json \
  --sheet Sheet2

# 紧凑格式（无缩进）
excel-toolbox excel2json data.xlsx \
  -o compact.json \
  --indent 0

# 美化格式（4 空格缩进）
excel-toolbox excel2json data.xlsx \
  -o pretty.json \
  --indent 4

8. 批量合并 JSON 文件为 Excel

# 合并文件夹内所有 JSON 文件
excel-toolbox mergejson ./json_data merged.xlsx

# 使用 json_pointer 提取嵌套数据
excel-toolbox mergejson ./api_responses merged.xlsx --pointer data.items

# 禁用递归搜索
excel-toolbox mergejson ./logs output.xlsx --no-recursive

9. 完整数据处理流水线

# 步骤 1: 导入 CSV
excel-toolbox csv2excel raw_data.csv -o step1.xlsx

# 步骤 2: 去重
excel-toolbox dedup step1.xlsx -o step2.xlsx -s ID

# 步骤 3: 排序
excel-toolbox sort step2.xlsx template.xlsx step3.xlsx -m id -t id

# 步骤 4: 导出 JSON
excel-toolbox excel2json step3.xlsx -o final.json

查看帮助

# 查看所有命令
excel-toolbox --help

# 查看特定命令帮助
excel-toolbox merge --help
excel-toolbox join --help
excel-toolbox dedup --help
excel-toolbox sort --help
excel-toolbox csv2excel --help
excel-toolbox json2excel --help
excel-toolbox excel2json --help
excel-toolbox mergejson --help

# 查看版本
excel-toolbox --version

---

Python 脚本模式

from excel_toolbox import (
    merge_excel_files,
    join_tables,
    remove_duplicates,
    sort_by_template,
    csv_to_excel,
    json_to_excel,
    excel_to_json,
    merge_json_to_excel
)

示例 1: 合并文件夹内所有 Excel 文件

# 仅合并首表
df = merge_excel_files(
    folder_path="./sample_data/monthly_reports",
    output_path="./output/merged_first_sheet.xlsx",
    include_all_sheets=False
)

# 合并所有工作表
df_all = merge_excel_files(
    folder_path="./sample_data/monthly_reports",
    output_path="./output/merged_all_sheets.xlsx",
    include_all_sheets=True
)

示例 2: 两表关联合并（SQL JOIN）

# Inner Join
df_inner = join_tables(
    left_file="./sample_data/customers.xlsx",
    right_file="./sample_data/orders.xlsx",
    left_on="customer_id",
    right_on="cust_id",
    how="inner",
    output_path="./output/inner_join.xlsx"
)

# Left Join
df_left = join_tables(
    left_file="./sample_data/customers.xlsx",
    right_file="./sample_data/orders.xlsx",
    left_on="customer_id",
    right_on="cust_id",
    how="left",
    output_path="./output/left_join.xlsx"
)

示例 3: 去除重复数据

# 全行去重
stats1 = remove_duplicates(
    input_file="./sample_data/duplicates.xlsx",
    output_path="./output/dedup_all.xlsx"
)
print(f"全行去重: 删除 {stats1['dropped_count']} 行")

# 按指定列去重
stats2 = remove_duplicates(
    input_file="./sample_data/duplicates.xlsx",
    subset=["ID", "Name"],
    keep="last",
    output_path="./output/dedup_subset.xlsx"
)
print(f"按列去重: 删除 {stats2['dropped_count']} 行")

示例 4: 按模板自定义排序

df = sort_by_template(
    main_file="./sample_data/products.xlsx",
    template_file="./sample_data/priority_template.xlsx",
    main_col="product_id",
    template_col="id",
    unmatched_position="bottom",
    output_path="./output/sorted_products.xlsx"
)

示例 5: CSV 转 Excel

# UTF-8 编码
df1 = csv_to_excel(
    csv_path="./sample_data/sales.csv",
    output_path="./output/sales.xlsx",
    encoding="utf-8"
)

# GBK 编码
df2 = csv_to_excel(
    csv_path="./sample_data/sales_gbk.csv",
    output_path="./output/sales_gbk.xlsx",
    encoding="gbk"
)

示例 6: JSON 转 Excel

# 顶层数组
df1 = json_to_excel(
    json_path="./sample_data/simple_array.json",
    output_path="./output/from_simple_json.xlsx"
)

# 嵌套对象
df2 = json_to_excel(
    json_path="./sample_data/nested_object.json",
    output_path="./output/from_nested_json.xlsx",
    json_pointer="data.items"
)

示例 7: Excel 转 JSON

# 美化格式
json_str1 = excel_to_json(
    excel_path="./sample_data/products.xlsx",
    output_path="./output/products_pretty.json",
    sheet_name=0,
    indent=2
)

# 紧凑格式
json_str2 = excel_to_json(
    excel_path="./sample_data/products.xlsx",
    output_path="./output/products_compact.json",
    sheet_name=0,
    indent=None
)

示例 8: 批量合并 JSON 文件为 Excel

# 简单合并：合并文件夹内所有顶层数组格式的 JSON
df1 = merge_json_to_excel(
    folder_path="./sample_data/json_files",
    output_path="./output/merged_json.xlsx"
)

# 使用 json_pointer 提取嵌套数据
df2 = merge_json_to_excel(
    folder_path="./sample_data/api_responses",
    output_path="./output/merged_api_data.xlsx",
    json_pointer="data.items"
)

# 禁用递归，仅处理当前目录
df3 = merge_json_to_excel(
    folder_path="./sample_data/json_files",
    output_path="./output/merged_no_recursive.xlsx",
    recursive=False
)

示例 9: 完整数据处理流水线

# 步骤 1: CSV 转 Excel
df1 = csv_to_excel("./sample_data/raw_data.csv", "./output/step1_imported.xlsx")

# 步骤 2: 去重
stats = remove_duplicates(
    "./output/step1_imported.xlsx",
    subset="ID",
    output_path="./output/step2_deduped.xlsx"
)

# 步骤 3: 按模板排序
df3 = sort_by_template(
    "./output/step2_deduped.xlsx",
    "./sample_data/sort_template.xlsx",
    "category",
    "category_order",
    output_path="./output/step3_sorted.xlsx"
)

# 步骤 4: 导出 JSON
json_str = excel_to_json("./output/step3_sorted.xlsx", "./output/final_result.json")

📚 功能详解

1️⃣ 数据合并模块

merge_excel_files - 合并文件夹内所有 Excel

功能：遍历文件夹，智能合并所有 Excel 工作簿，自动注入元数据

参数：

• folder_path (str): 文件夹路径
• output_path (Optional[str]): 输出文件路径
• include_all_sheets (bool): 是否合并所有工作表（默认 False）

返回：pd.DataFrame

元数据列：

• source_file: 来源文件名
• source_sheet: 来源工作表名

示例：

# 仅合并首表
df = merge_excel_files("./reports")

# 合并所有工作表
df = merge_excel_files("./reports", "all_data.xlsx", include_all_sheets=True)

---

join_tables - 两表关联合并

功能：实现类 SQL 的 inner/left/right/outer 四种连接模式

参数：

• left_file (str): 左表文件路径
• right_file (str): 右表文件路径
• left_on (str | List[str]): 左表关联键
• right_on (str | List[str]): 右表关联键
• how (Literal["inner", "left", "right", "outer"]): 连接类型
• suffixes (Tuple[str, str]): 重名列后缀（默认 _left, _right）
• output_path (Optional[str]): 输出路径

返回：pd.DataFrame

示例：

# 内连接
df = join_tables("users.xlsx", "orders.xlsx", "id", "user_id")

# 左连接，多键关联
df = join_tables(
    "table_a.xlsx", "table_b.xlsx",
    left_on=["key1", "key2"],
    right_on=["k1", "k2"],
    how="left"
)

---

2️⃣ 数据清洗模块

remove_duplicates - 去除重复数据

功能：支持全行去重或指定列组合去重

参数：

• input_file (str): 输入文件路径
• subset (Optional[str | List[str]]): 去重依据列（None=全行）
• keep (Literal["first", "last", False]): 保留策略
• inplace (bool): 是否覆盖原文件
• output_path (Optional[str]): 输出路径

返回：字典 {original_count, dedup_count, dropped_count}

示例：

# 全行去重
stats = remove_duplicates("data.xlsx", output_path="cleaned.xlsx")

# 按 ID 列去重，保留最后一次出现
stats = remove_duplicates(
    "data.xlsx",
    subset="ID",
    keep="last",
    output_path="result.xlsx"
)

# 删除所有重复项（包括首次出现）
stats = remove_duplicates("data.xlsx", keep=False, output_path="unique.xlsx")

---

sort_by_template - 按模板自定义排序

功能：依据模板文件列值顺序重排主数据

参数：

• main_file (str): 主数据文件
• template_file (str): 模板文件
• main_col (str): 主数据匹配列
• template_col (str): 模板匹配列
• unmatched_position (Literal["top", "bottom"]): 未匹配项位置
• output_path (Optional[str]): 输出路径

返回：pd.DataFrame

示例：

# 按模板顺序排序，未匹配项置于顶部
df = sort_by_template(
    main_file="products.xlsx",
    template_file="priority_list.xlsx",
    main_col="product_id",
    template_col="id"
)

# 未匹配项置于底部
df = sort_by_template(
    "data.xlsx", "template.xlsx",
    "name", "name",
    unmatched_position="bottom",
    output_path="sorted.xlsx"
)

---

3️⃣ 格式转换模块

csv_to_excel - CSV 转 Excel

功能：智能编码识别，保留原始数据类型

参数：

• csv_path (str): CSV 文件路径
• output_path (Optional[str]): 输出路径（默认同目录 .xlsx）
• encoding (str): 文件编码（默认 utf-8）
• delimiter (str): 分隔符（默认逗号）
• include_index (bool): 是否包含索引

返回：pd.DataFrame

示例：

# 默认 UTF-8 编码
df = csv_to_excel("data.csv")

# GBK 编码，分号分隔
df = csv_to_excel("data.csv", encoding="gbk", delimiter=";")

---

json_to_excel - JSON 转 Excel

功能：支持平铺/嵌套 JSON，通过路径表达式提取数据

参数：

• json_path (str): JSON 文件路径
• output_path (Optional[str]): 输出路径
• json_pointer (Optional[str]): JSON 路径（点分隔，如 data.items）
• include_index (bool): 是否包含索引

返回：pd.DataFrame

支持结构：

JSON 顶层	处理方式
[{...}]	直接转换
{"key": [...]}	需指定 json_pointer
混合嵌套	自动扁平化

示例：

# 顶层数组
df = json_to_excel("data.json")

# 嵌套对象
df = json_to_excel("api.json", json_pointer="response.data.items")

---

excel_to_json - Excel 转 JSON

功能：输出标准 JSON 数组，NaN→null，支持美化

参数：

• excel_path (str): Excel 文件路径
• output_path (Optional[str]): 输出路径
• sheet_name (str | int): 工作表名称或索引
• indent (Optional[int]): 缩进（2=美化，None=紧凑）
• date_format (str): 日期格式（iso/epoch）

返回：str (JSON 字符串)

示例：

# 紧凑格式
json_str = excel_to_json("data.xlsx", indent=None)

# 指定工作表
json_str = excel_to_json("data.xlsx", sheet_name="Summary")

---

merge_json_to_excel - 批量合并 JSON 文件

功能：递归扫描文件夹，合并所有 JSON 文件为一个 Excel

参数：

• folder_path (str): 包含 JSON 文件的文件夹路径
• output_path (str): 输出 Excel 文件路径
• json_pointer (Optional[str]): JSON 路径（点分隔，如 data.items）
• include_index (bool): 是否包含索引
• recursive (bool): 是否递归搜索子文件夹（默认 True）

返回：pd.DataFrame

元数据列：

• source_file: 来源文件相对路径

示例：

# 合并文件夹内所有 JSON
df = merge_json_to_excel("./json_data", "merged.xlsx")

# 使用 json_pointer 提取嵌套数据
df = merge_json_to_excel("./api_data", "merged.xlsx", json_pointer="data.items")

# 禁用递归，仅处理当前目录
df = merge_json_to_excel("./logs", "merged.xlsx", recursive=False)

---

🛡️ 异常处理

异常类型	触发场景	处理策略
FileNotFoundError	文件不存在	中断执行
ValueError	参数冲突	中断执行
KeyError	列名/路径不存在	中断执行
UnicodeDecodeError	编码错误	提示尝试其他编码
RuntimeError	无有效数据	中断执行
Warning	单文件失败	跳过并记录警告

---

📋 CLI 命令速查

命令	功能	示例
merge	合并文件夹 Excel	excel-toolbox merge ./data out.xlsx
join	两表关联	excel-toolbox join a.xlsx b.xlsx out.xlsx -l id -r id
dedup	去重	excel-toolbox dedup data.xlsx -o clean.xlsx -s ID
sort	自定义排序	excel-toolbox sort data.xlsx tpl.xlsx out.xlsx -m id -t id
mergejson	合并JSON文件夹	excel-toolbox mergejson ./data out.xlsx -p data.items
csv2excel	CSV→Excel	excel-toolbox csv2excel data.csv
json2excel	JSON→Excel	excel-toolbox json2excel api.json -p data.items
excel2json	Excel→JSON	excel-toolbox excel2json data.xlsx -s Sheet1

---

🔧 依赖环境

• Python: 3.9+
• 核心依赖:

  pandas>=2.0.0
  openpyxl>=3.1.0
  xlrd>=2.0.0
  typer>=0.9.0
  rich>=13.0.0
  

---

📝 项目结构

excel-toolbox/
├── excel_toolbox/
│   ├── __init__.py       # 包初始化
│   ├── merger.py         # 数据合并模块
│   ├── cleaner.py        # 数据清洗模块
│   ├── converter.py      # 格式转换模块
│   └── cli.py            # CLI 命令行接口
├── test_installation.py  # 安装测试脚本
├── requirements.txt      # 依赖清单
├── pyproject.toml        # 项目配置
├── setup.py              # 安装脚本
└── README.md             # 说明文档

---

🎓 学习路径

新手入门

1. 先阅读 QUICKSTART.md 快速了解
2. 运行几个简单的 CLI 命令熟悉基本操作
3. 参考上方「CLI 命令行模式」中的示例

进阶使用

1. 阅读「Python 脚本模式」了解 Python API 调用方式
2. 修改示例代码适配自己的数据
3. 编写自己的数据处理脚本

高级应用

1. 阅读源代码了解实现细节
2. 组合多个功能构建复杂流水线
3. 扩展自定义功能

---

💡 实用技巧

技巧 1: 链式处理

# CSV → Excel → 去重 → 排序 → JSON
excel-toolbox csv2excel data.csv -o step1.xlsx
excel-toolbox dedup step1.xlsx -o step2.xlsx -s ID
excel-toolbox sort step2.xlsx template.xlsx step3.xlsx -m id -t id
excel-toolbox excel2json step3.xlsx -o final.json

技巧 2: 批量合并 JSON

# 合并文件夹内所有 JSON 文件
excel-toolbox mergejson ./json_data merged.xlsx

# 使用 json_pointer 提取嵌套数据
excel-toolbox mergejson ./api_responses merged.xlsx --pointer data.items

# 禁用递归搜索
excel-toolbox mergejson ./logs output.xlsx --no-recursive

技巧 3: Python 流水线

from excel_toolbox import csv_to_excel, remove_duplicates, sort_by_template

# 链式调用
df1 = csv_to_excel("data.csv", "step1.xlsx")
stats = remove_duplicates("step1.xlsx", subset="ID", output_path="step2.xlsx")
df3 = sort_by_template("step2.xlsx", "template.xlsx", "id", "id", output_path="final.xlsx")

技巧 4: 批量合并 JSON (Python)

from excel_toolbox import merge_json_to_excel

# 合并文件夹内所有 JSON
df = merge_json_to_excel("./json_data", "merged.xlsx")

# 使用 json_pointer 提取嵌套数据
df = merge_json_to_excel("./api_data", "merged.xlsx", json_pointer="data.items")

技巧 5: 批处理

# 批量转换多个 CSV 文件
for file in *.csv; do
    excel-toolbox csv2excel "$file" --output "${file%.csv}.xlsx"
done

---

🔍 常见场景示例

场景 1: 月度报表汇总

# 合并所有月度报表
df = merge_excel_files("./monthly_reports", "yearly.xlsx", include_all_sheets=True)
# 自动添加 source_file 和 source_sheet 列标识来源

场景 2: 客户订单关联分析

# 左连接：保留所有客户，关联订单信息
df = join_tables(
    "customers.xlsx", "orders.xlsx",
    left_on="customer_id",
    right_on="cust_id",
    how="left",
    output_path="customer_orders.xlsx"
)

场景 3: 数据清洗

# 去重 + 排序
remove_duplicates("raw.xlsx", subset="ID", output_path="clean.xlsx")
sort_by_template("clean.xlsx", "priority.xlsx", "category", "order", output_path="final.xlsx")

场景 4: 批量合并 JSON 数据

from excel_toolbox import merge_json_to_excel

# 合并文件夹中所有 JSON 文件（包括子文件夹）
df = merge_json_to_excel("./api_logs", "all_logs.xlsx")

# 使用 json_pointer 提取嵌套数据后合并
df = merge_json_to_excel(
    "./api_responses",
    "merged_items.xlsx",
    json_pointer="data.items"
)

场景 5: 格式转换

# CSV 导入，处理后导出 JSON
excel-toolbox csv2excel data.csv -o temp.xlsx
excel-toolbox dedup temp.xlsx -o clean.xlsx -s ID
excel-toolbox excel2json clean.xlsx -o output.json

场景 6: 多格式数据汇总

# 1. CSV 转 Excel
csv_to_excel("sales.csv", "sales.xlsx")

# 2. JSON API 响应转 Excel
json_to_excel("api_response.json", "users.xlsx", json_pointer="data.users")

# 3. 合并所有 Excel
merge_excel_files(".", "all_data.xlsx")

---

🆘 遇到问题？

1. 查看帮助: excel-toolbox <command> --help
2. 阅读文档: 参考本文件中的功能详解与示例
3. 检查示例: 对比你的代码与上方示例的差异
4. 测试安装: python test_installation.py

---

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

---

📄 许可证

MIT License - 详见 LICENSE 文件

Excel Toolbox - 让数据处理更简单 🚀