Excel_Split_and_fill_merged_cells
输入 Excel 文件路径,自动识别合并单元格、拆分并填入对应内容。
一个专注于"拆分合并单元格并填充"的轻量 Python 库。基于 openpyxl + 线程池,纯 Python 实现,无需编译,装上即用。
特性
- ✅ 自动识别:自动检测 Excel 中所有合并单元格区域
- ✅ 拆分并填充:取消合并,把原左上角的值回填到区域内每个单元格
- ✅ 多种输出:覆盖原文件 / 另存 xlsx / 另存 CSV / 输出 DataFrame
- ✅ pandas / polars 友好:一行代码拿到 DataFrame,直接进分析流程
- ✅ 多工作表支持:可按索引、名称选择,也可一次处理全部工作表
- ✅ 并发回填:线程池加速大批量合并单元格的填充
- ✅ 纯 Python:无需 C/C++ 编译器,跨平台
安装
pip install Excel_Split_and_fill_merged_cells
如需 pandas / polars 支持,安装对应的可选依赖:
pip install "Excel_Split_and_fill_merged_cells[pandas]" # 仅 pandas
pip install "Excel_Split_and_fill_merged_cells[polars]" # 仅 polars
pip install "Excel_Split_and_fill_merged_cells[all]" # 两者都要
快速开始
from Excel_Split_and_fill_merged_cells import (
split_and_fill, to_csv, to_pandas, to_polars, to_data, get_sheet_names
)
1. 拆分并覆盖原文件
split_and_fill("data.xlsx")
2. 另存为新 Excel 文件
split_and_fill("data.xlsx", output="clean.xlsx")
3. 另存为 CSV
to_csv("data.xlsx", output="out.csv")
# 不指定 output,自动生成同名 .csv
to_csv("data.xlsx")
4. 输出 pandas DataFrame
df = to_pandas("data.xlsx")
print(df.head())
5. 输出 polars DataFrame
df = to_polars("data.xlsx")
print(df)
6. 输出原生 dict(不依赖任何第三方库)
data = to_data("data.xlsx")
print(data["headers"]) # ['姓名', '部门', '工资']
print(data["rows"][0]) # ['张三', '技术部', 9500]
# 也可以自己喂给 pandas
import pandas as pd
df = pd.DataFrame(data["rows"], columns=data["headers"])
7. 查看工作表名称
print(get_sheet_names("data.xlsx")) # ['Sheet1', '汇总', '明细']
API 一览
| 函数 | 作用 | 返回 |
|---|---|---|
split_and_fill(filepath, output=None, sheet=None, max_workers=8) |
拆分填充并保存 | 输出文件路径 |
to_csv(filepath, output=None, sheet=0, max_workers=8, encoding='utf-8-sig') |
拆分填充后存为 CSV | CSV 文件路径 |
to_pandas(filepath, sheet=0, header=True, max_workers=8) |
拆分填充后返回 DataFrame | pandas.DataFrame |
to_polars(filepath, sheet=0, header=True, max_workers=8) |
拆分填充后返回 DataFrame | polars.DataFrame |
to_data(filepath, sheet=0, header=True, max_workers=8) |
拆分填充后返回原生数据 | dict(headers, rows, sheet_name) |
get_sheet_names(filepath) |
读取工作表名称 | list[str] |
参数说明
filepath:Excel 文件路径,支持.xlsx/.xlsm。output:None:覆盖原文件(split_and_fill);*.xlsx/*.xlsm:另存为新 Excel;*.csv:另存为 CSV(此时sheet只能指向单个工作表)。
sheet:工作表选择。None:处理所有工作表(split_and_fill默认);int:按索引选择,0 开始;str:按名称选择;list:多选。
header:True时把第一行作为列名(to_pandas/to_polars/to_data)。max_workers:线程池大小,控制并发回填的线程数;<=1表示单线程。encoding:CSV 编码,默认utf-8-sig(带 BOM,Excel 直接打开不乱码)。
工作原理
原始 Excel(有合并单元格) 处理后(已拆分并填充)
┌─────────┬─────────┐ ┌─────┬─────┐
│ 部门 │ 工资 │ │部门 │工资 │
├─────────┼─────────┤ ├─────┼─────┤
│ 技术部 │ │ ───▶ │技术部│9500 │
│ │ 9500 │ │技术部│9500 │
│ │ │ │技术部│9500 │
└─────────┴─────────┘ └─────┴─────┘
- 用
openpyxl打开工作簿,定位目标工作表; - 快照所有合并区域及其左上角值(在取消合并前读取);
- 调用
unmerge_cells取消合并; - 用线程池把左上角值回填到区域内每个单元格(写操作加锁,保证线程安全);
- 按选择的输出方式保存或返回。
注意事项
- 仅支持
.xlsx/.xlsm格式;旧的.xls格式请先在 Excel 中另存为.xlsx。 openpyxl在保存时会丢失部分高级元素(如图表、数据透视表、部分 VBA 项目)。如果文件包含这些内容,建议用output另存为新文件,保留原始文件。- 公式单元格默认读取其缓存值(
data_only=True);如果文件从未被 Excel 打开保存过,公式结果可能为None。 max_workers在纯 Python 环境下受 GIL 限制,主要价值在于批量场景下的 I/O 调度;数据量小时设为 1 即可。
开发
# 克隆仓库后
pip install -e ".[dev]"
# 运行测试
pytest tests/ -v
# 构建
python -m build
# 上传 PyPI
twine upload dist/*
License
MIT © 辉哥 & 旺财
Metadata
Release files for Excel-Split-and-fill-merged-cells 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_split_and_fill_merged_cells-0.1.0.tar.gz | 11.9 kB | Without provenance | Details for excel_split_and_fill_merged_cells-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| excel_split_and_fill_merged_cells-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for excel_split_and_fill_merged_cells-0.1.0-py3-none-any.whl |
Total release size: 22.3 kB
Release files / excel_split_and_fill_merged_cells-0.1.0.tar.gz
| Download URL | excel_split_and_fill_merged_cells-0.1.0.tar.gz |
|---|---|
| Size | 11.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a319161e748a4bef1e352f98a77b2d73f08cbec3d4c6ac1cd4ccbadeb7bbbcfa
|
|
BLAKE2b-256 checksum How to use checksums |
a19ecbad20e8c3bb9cebf6aea651cb5ff178717a6759392427b0b16a974dc302
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.9
|
Release files / excel_split_and_fill_merged_cells-0.1.0-py3-none-any.whl
| Download URL | excel_split_and_fill_merged_cells-0.1.0-py3-none-any.whl |
|---|---|
| Size | 10.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b88e9700dff78aa3f7e20f0dde7c3cc3bda3bbde6f743abe244a22a2457b9130
|
|
BLAKE2b-256 checksum How to use checksums |
5d64632c17f74f32718fde23f076cf7db5e2f3a8b6c1fe3e2e1924c7d511cb82
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.9
|
Security for Excel-Split-and-fill-merged-cells 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.