Excel Merger 📊
一个强大的 Excel 文件合并工具,支持命令行(CLI)和 Python API 两种使用方式。
使用 Typer 提供现代化 CLI 体验,使用 rich 实现精美的命令行输出。
✨ 特性
- 🚀 易于使用 - 简单的命令行界面和 Python API
- 📁 批量合并 - 自动合并文件夹中的所有 Excel 文件
- 🔍 灵活匹配 - 支持通配符模式和递归搜索
- 🎨 精美输出 - 使用 Rich 库实现彩色、表格化的命令行输出
- 📊 智能处理 - 自动对齐列结构,可选添加来源文件列
- ⚡ 进度显示 - 实时显示处理进度
- 🛡️ 错误处理 - 单个文件失败不影响整体合并
📦 安装
方式一:从源码安装
# 克隆或下载项目
cd /path/to/202512
# 安装依赖
pip install -r requirements.txt
# 安装项目(开发模式)
pip install -e .
方式二:仅安装依赖(无需安装项目)
pip install pandas openpyxl typer rich
🚀 使用方法
命令行(CLI)使用
基本用法
# 合并当前目录下的所有 .xlsx 文件
excel-merge . --output merged.xlsx
# 或者使用 Python 模块方式运行
python -m excel_merger.cli merge . --output merged.xlsx
高级用法
# 递归搜索所有子目录中的 Excel 文件
excel-merge ./data --recursive --output all_merged.xlsx
# 合并指定 sheet
excel-merge ./reports --sheet "Data" --output data_merged.xlsx
# 使用自定义文件匹配模式
excel-merge ./data --pattern "report_*.xlsx" --output reports.xlsx
# 仅预览将要处理的文件(不实际合并)
excel-merge ./data --dry-run
# 不添加来源文件列
excel-merge ./data --no-add-source --output merged_no_source.xlsx
# 覆盖已存在的输出文件
excel-merge ./data --output merged.xlsx --overwrite
# 静默模式(减少输出)
excel-merge ./data --quiet --output merged.xlsx
查看帮助
# 查看完整帮助
excel-merge --help
# 查看版本
excel-merge version
Python API 使用
from excel_merger import merge_excels
# 基本使用
merge_excels(
input_dir="data/excels",
output_file="output/merged.xlsx"
)
# 高级使用
df = merge_excels(
input_dir="data/monthly",
output_file="output/monthly_merged.xlsx",
pattern="*.xlsx", # 文件匹配模式
recursive=True, # 递归搜索子目录
sheet_name="Sheet1", # 指定要合并的 sheet
header=0, # 表头行号
add_source_column=True, # 添加来源文件列
source_column_name="来源文件", # 来源列名称
overwrite=True, # 覆盖已存在文件
return_dataframe=True, # 返回 DataFrame
quiet=False, # 显示处理信息
)
print(f"合并后的行数: {len(df)}")
print(f"列名: {df.columns.tolist()}")
📋 参数说明
CLI 参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
input_dir |
Path | 必填 | 待合并的 Excel 文件所在文件夹 |
--output, -o |
Path | merged.xlsx |
输出文件路径 |
--pattern, -p |
str | *.xlsx |
文件匹配通配符 |
--recursive, -r |
bool | False |
是否递归遍历子文件夹 |
--sheet, -s |
str | None |
指定要合并的 sheet 名称 |
--header |
int | 0 |
表头所在行号 |
--add-source/--no-add-source |
bool | True |
是否添加来源文件列 |
--source-col |
str | source_file |
来源文件列名称 |
--dry-run |
bool | False |
仅显示将要处理的文件 |
--overwrite |
bool | False |
是否覆盖已存在的输出文件 |
--quiet, -q |
bool | False |
减少输出信息 |
Python API 参数
参数与 CLI 基本一致,额外包括:
return_dataframe(bool): 是否返回合并后的 DataFrame,默认False
📸 效果展示
CLI 运行效果包括:
- 🎨 彩色标题面板
- 📋 格式化的文件列表表格
- ⏳ 实时进度条
- 📊 合并结果统计面板
- ⚠️ 清晰的错误和警告提示
🔧 开发
# 安装开发依赖
pip install -e ".[dev]"
# 运行测试
pytest
# 代码格式化
black excel_merger/
# 代码检查
flake8 excel_merger/
📝 示例场景
场景 1:合并月度报表
excel-merge ./reports/2024 --pattern "report_*.xlsx" --output yearly_report.xlsx
场景 2:合并多个部门数据
from excel_merger import merge_excels
result = merge_excels(
input_dir="data/departments",
output_file="all_departments.xlsx",
recursive=True,
add_source_column=True,
source_column_name="部门",
return_dataframe=True
)
# 进一步处理合并后的数据
print(result.groupby("部门").size())
场景 3:批量处理多个文件夹
from pathlib import Path
from excel_merger import merge_excels
folders = ["2023Q1", "2023Q2", "2023Q3", "2023Q4"]
for folder in folders:
merge_excels(
input_dir=f"data/{folder}",
output_file=f"output/{folder}_merged.xlsx",
quiet=True
)
⚠️ 注意事项
- 文件格式:默认支持
.xlsx格式,如需支持.xls请安装xlrd - 列名对齐:合并时会自动对齐所有列,缺失值填充为 NaN
- 大文件:处理大量文件时建议使用进度条模式查看进度
- 错误处理:单个文件读取失败会跳过并继续处理其他文件
📄 许可证
MIT License
🤝 贡献
欢迎提交 Issue 和 Pull Request!
📧 联系
如有问题或建议,请提交 Issue。
Metadata
Release files for excel-merger 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| excel_merger-0.1.0.tar.gz | 12.5 kB | Without provenance | Details for excel_merger-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| excel_merger-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for excel_merger-0.1.0-py3-none-any.whl |
Total release size: 23.0 kB
Release files / excel_merger-0.1.0.tar.gz
| Download URL | excel_merger-0.1.0.tar.gz |
|---|---|
| Size | 12.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d095a19bb44d1ac932664e9d7f9bc0935122b7d22dd986b06f2867aa2274bdfc
|
|
BLAKE2b-256 checksum How to use checksums |
96d4bd86a7630be4e791a716967adb9f62e24f62200c38843dbfef9008165965
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Release files / excel_merger-0.1.0-py3-none-any.whl
| Download URL | excel_merger-0.1.0-py3-none-any.whl |
|---|---|
| Size | 10.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6c72e402ddc2d60edc04112b380af0a1aad0332b5411283d09602ee6311a5fde
|
|
BLAKE2b-256 checksum How to use checksums |
1ad4c081a9b3909f5819ef4c65e1e86c7ec5089638e13c6cbec3f3d89845fff3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Security for excel-merger 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.