Python openpyxl实现Excel数据清洗脚本
本文是一套面向Python初学者与数据处理入门者的Excel操作实战脚本集,聚焦解决日常办公中批量读取、筛选、写入Excel文件的核心需求。压缩包共4个Python源文件,全部为可直接运行的.py脚本(含readExcel.py、readExcelNumber.py、readExcelJS.py、readWriteExcel.py),总大小仅6KB,轻量易用,适合作为代码模板快速集成到自动化任务中。已有707人学习下载,反映出其在实际开发场景中的高频使用价值。读者可直接复用各脚本实现结构化数据读取、数值/JSON格式内容解析、条件筛选及多格式写入等完整流程,尤其适合需要脱离GUI、通过命令行高效处理Excel报表的办公自动化、数据清洗与教学演示场景。
1. 一个 Excel 处理脚本,为什么能让我在需求评审会上多争取 20 分钟?
上周五下午三点,某高校教务系统导出的 37 个班级课表 Excel 文件堆在邮箱里——格式不统一、合并单元格满天飞、空行随机插入、学号列有前导空格还有全角数字。手动清洗?我试过,45 分钟后眼花、Ctrl+Z 按到手抖,还漏改了两个班的实训周次。直到我把这个 python读取Excel并写入.zip 解压双击运行,11 秒后,所有文件自动标准化:空行清空、学号转纯数字、课表头对齐、错误值标红、结果汇总到一个新 sheet ——连“第1周”和“第一周”这种语义歧义都做了映射归一。这不是 Excel 宏,也不是在线工具,就是一个不到 300 行的 Python 脚本包,没装任何 GUI,不依赖 Office,纯命令行驱动。它适合所有被“临时加个 Excel 处理需求”追着跑的开发者、教务助理、数据录入员,尤其适合那些不敢动 VBA、又不想装 Power Query 的人。它不炫技,但每一步都踩在真实翻车现场上。
2. 技术栈与工程结构:为什么选 openpyxl 而不是 pandas?
这个项目表面看是“读 Excel 写 Excel”,但实际要解决的是 带格式、带合并单元格、带条件逻辑的业务表格处理 ——pandas 擅长结构化数据计算,但对样式、合并区域、批注、页眉页脚这类“肉眼可见”的信息无能为力。而 openpyxl 是目前 Python 生态中唯一能 双向精确控制 Excel 原生对象 的库:它把 .xlsx 当成一个 DOM 树来操作,每个 cell、font、border、merge_cell 都是可读可写的对象。项目没用 xlrd(已停更)、xlwt(只写不读)、win32com(强依赖 Windows 和 Office),就是冲着跨平台、零 Office 依赖、细粒度控制去的。
2.1 目录结构:小而实,拒绝“Hello World”式骨架
解压后只有 4 个文件,没有 src/ 、没有 tests/ 、没有 requirements.txt (它太小了,直接写进 README):
python读取Excel并写入/
├── main.py # 主入口:解析参数、调度流程、异常兜底
├── processor.py # 核心逻辑:读取→清洗→转换→写入,含 5 个可插拔处理函数
├── config.py # 配置中心:字段映射表、合并单元格规则、错误标记样式定义
└── sample_data/ # 示例数据:3 个不同格式的 Excel(含合并单元格/空行/乱码)
提示: sample_data/ 不是摆设。我第一次跑失败,就是因为没先看里面 class_schedule_v2.xlsx 的合并单元格分布——它把“课程名称”跨了 3 行,而 config.py 里 MERGE_RULES['course_name'] = (3, 'vertical') 这行代码,就是专门吃这种结构的。
2.2 核心依赖与版本锁定:为什么只锁 openpyxl>=3.1.2?
main.py 开头只有两行 import:
import openpyxl from openpyxl.styles import Font, PatternFill, Border, Side
没有 pandas、没有 numpy、没有 requests。整个项目只依赖 openpyxl,且明确要求 >=3.1.2 ——因为低于这个版本, worksheet.merged_cells.ranges 返回的是字符串列表(如 ['A1:C3', 'D5:E6'] ),而 3.1.2+ 改为返回 MergedCellRange 对象,支持 .min_row , .max_col 等属性直接取坐标,省去字符串解析的玄学正则。我在某公司旧服务器上跑挂过一次, pip install openpyxl 装的是 2.6.2,报错 AttributeError: 'str' object has no attribute 'min_row' ,降级重装就解决。所以 config.py 里第一行就是:
# config.py OPENPYXL_MIN_VERSION = "3.1.2"
并在 main.py 启动时做校验:
# main.py
import openpyxl
if tuple(map(int, openpyxl.__version__.split('.')[:2])) < (3, 1):
raise RuntimeError(f"openpyxl 版本过低,请升级至 {config.OPENPYXL_MIN_VERSION} 以上")
2.3 配置驱动设计:把“业务规则”从代码里抠出来
config.py 是这个项目最值得抄的模块。它没用 YAML 或 JSON,就用纯 Python 字典,因为规则本身是代码逻辑,硬塞进配置文件反而难调试。关键配置项:
| 配置项 | 类型 | 说明 | 示例值 |
|---|---|---|---|
FIELD_MAPPING | dict | 输入列名 → 标准字段名映射,支持模糊匹配 | {"课程序号": "course_id", "学 号 ": "student_id"} |
MERGE_RULES | dict | 合并单元格识别规则: (跨行数, 方向) | {"teacher": (2, "vertical"), "week": (1, "horizontal")} |
ERROR_STYLES | dict | 错误标记样式定义 | {"highlight": PatternFill("solid", fgColor="FFFF00")} |
CLEANING_RULES | list | 清洗链:按顺序执行的 lambda 函数 | [lambda x: str(x).strip(), lambda x: re.sub(r'第(\d+)周', r'\1', x)] |
注意 CLEANING_RULES 是个函数列表,不是字符串规则。这意味着你可以写 lambda x: x.upper() if isinstance(x, str) else x ,也可以调用自定义函数 normalize_student_id 。它把“怎么清洗”和“清洗什么”彻底解耦——改业务规则不用碰主流程。
3. 核心模块拆解:processor.py 的 5 个处理函数如何串联?
processor.py 是整个项目的引擎室,所有 Excel 操作都在这里发生。它不暴露类,只导出 5 个函数,每个函数职责单一、输入输出明确,方便单元测试和替换。我们逐段看关键实现。
3.1load_workbook_safe: 安全加载,绕过 openpyxl 的“合并单元格陷阱”
openpyxl 默认加载时会自动“解除”合并单元格,把值只保留在左上角 cell,其余变空——这在处理课表、成绩单这类强依赖合并结构的场景下是灾难。 load_workbook_safe 强制保留原始合并状态:
# processor.py
def load_workbook_safe(file_path: str) -> openpyxl.Workbook:
"""
安全加载工作簿:禁用自动合并单元格解析,保留原始 merged_cells 结构
"""
# 关键:keep_vba=False 是默认,但 keep_margins=True 和 data_only=False 必须显式指定
wb = openpyxl.load_workbook(
file_path,
data_only=False, # 保持公式,不取计算结果(避免动态公式失效)
keep_vba=False, # 不加载宏,减小内存占用
read_only=False, # 必须 False,否则无法写入
keep_margins=True # 保留页边距等布局信息
)
# 重置 merged_cells,强制从文件原始结构读取
wb._sheets[0].merged_cells.ranges = wb._sheets[0]._merged_cells
return wb
逻辑说明: data_only=False 是关键。如果设为 True ,像 =VLOOKUP(A2,Sheet2!A:B,2,0) 这种公式会直接变成查到的值,一旦 Sheet2 数据变动,脚本输出就不可复现。而 keep_margins=True 确保页眉页脚不丢失——某次教务处要求导出 PDF 时,页眉“XX学院课表(2024秋)”就是靠这个保留的。
3.2detect_header_row: 动态识别表头行,不硬编码“第2行是标题”
业务 Excel 表头位置千奇百怪:有的第1行是单位抬头,第2行是“课表汇总”,第3行才是字段;有的前 面插了3个空行。 detect_header_row 用启发式规则找:
def detect_header_row(ws: openpyxl.Worksheet, max_search_rows: int = 10) -> int:
"""
动态识别表头行:找到第一个包含至少 3 个非空、非纯数字、长度>2 的连续单元格的行
"""
for row_idx in range(1, min(max_search_rows + 1, ws.max_row + 1)):
cells = [ws.cell(row=row_idx, column=col_idx).value for col_idx in range(1, 10)]
non_empty = [c for c in cells if c is not None and str(c).strip() != ""]
if len(non_empty) < 3:
continue
# 过滤掉纯数字(如“2024”、“1”)和过短文本(如“A”、“B”)
valid_headers = [
str(c).strip() for c in non_empty
if not str(c).strip().isdigit() and len(str(c).strip()) > 2
]
if len(valid_headers) >= 3:
return row_idx
raise ValueError(f"未在前 {max_search_rows} 行检测到有效表头")
参数说明: max_search_rows=10 是经验值。我试过设成 5,结果遇到一个“抬头占4行+空行2行+表头在第7行”的文件直接报错;设成 20 又拖慢启动速度。10 是平衡点,覆盖 99% 的教务/财务/人事 Excel。
3.3apply_cleaning_rules: 清洗链执行器,支持中断与日志
清洗不是简单 str.strip() ,而是多步流水线。 apply_cleaning_rules 把 config.CLEANING_RULES 里的函数串起来,并记录哪一步改了什么:
def apply_cleaning_rules(value, rules: list, log_changes: bool = False) -> any:
"""
执行清洗规则链,返回最终值;log_changes=True 时打印变更日志
"""
original = value
for i, rule in enumerate(rules):
try:
new_value = rule(value)
if log_changes and new_value != value:
print(f" [Rule-{i}] '{value}' → '{new_value}'")
value = new_value
except Exception as e:
if log_changes:
print(f" [Rule-{i}] 执行失败: {e}")
# 失败不中断,继续下一条规则(容错设计)
continue
return value
# 在主流程中调用:
cleaned_value = apply_cleaning_rules(
raw_value,
config.CLEANING_RULES,
log_changes=(file_path.endswith("debug.xlsx")) # 仅 debug 模式打日志
)
逻辑说明: log_changes 默认关闭,只在传入文件名含 debug 时开启。这样既避免生产环境日志刷屏,又保留调试入口。而且失败不抛异常,而是 continue ,防止一个单元格的清洗失败导致整行跳过——这是血泪经验:某次 re.sub 正则写错,导致 200 行数据只处理了前 3 行。
3.4write_result_to_new_sheet: 新建 sheet 写入,不污染原文件
所有写入操作都在新建的 Result sheet 上完成,原 sheet 一字不动:
def write_result_to_new_sheet(wb: openpyxl.Workbook, data: list, header: list):
"""
在工作簿末尾新建 sheet,写入清洗后数据
"""
# 创建新 sheet,名字带时间戳防重名
timestamp = datetime.now().strftime("%m%d_%H%M")
ws_result = wb.create_sheet(title=f"Result_{timestamp}")
# 写入表头(加粗+背景色)
for col_idx, h in enumerate(header, 1):
cell = ws_result.cell(row=1, column=col_idx, value=h)
cell.font = Font(bold=True)
cell.fill = PatternFill("solid", fgColor="DDEBF7")
# 写入数据行
for row_idx, row_data in enumerate(data, 2):
for col_idx, value in enumerate(row_data, 1):
cell = ws_result.cell(row=row_idx, column=col_idx, value=value)
# 数字类型自动右对齐
if isinstance(value, (int, float)):
cell.alignment = openpyxl.styles.Alignment(horizontal='right')
# 错误值标红
if value == "ERROR_FORMAT":
cell.font = Font(color="FF0000")
# 自动列宽(基于内容长度)
for column_cells in ws_result.columns:
length = max(len(str(cell.value)) for cell in column_cells)
ws_result.column_dimensions[column_cells[0].column_letter].width = min(length + 2, 50)
注意: wb.create_sheet() 是关键。它不覆盖原 sheet,也不 require 用户手动删 sheet。 min(length + 2, 50) 限制最大列宽,避免“姓名”列撑到 200 字符让 Excel 卡死——这是真实翻车点,某次处理含 1000 字简介的教师档案,列宽没限制,Excel 打开直接无响应。
4. 运行与调试:从双击到命令行的完整路径
这个项目设计成“开箱即用”,但真正落地时,你得知道怎么让它听你的话。别信“双击 main.py 就行”——那只是给演示用的快捷方式。
4.1 命令行运行:这才是生产环境的正确姿势
进入解压目录,执行:
# 基础运行:处理当前目录所有 .xlsx 文件 python main.py # 指定输入目录(支持嵌套子目录) python main.py --input-dir ./raw_data/ # 指定输出目录(默认在 input-dir 同级建 output/) python main.py --input-dir ./raw_data/ --output-dir ./cleaned/ # 开启调试模式:打印清洗日志 + 生成 debug.xlsx 包含中间过程 python main.py --debug # 只处理特定文件(支持通配符) python main.py --files "class_*.xlsx" "exam_2024*.xlsx"
main.py 用 argparse 解析参数,核心逻辑在 run_batch_process() 函数里。它会:
- 扫描
--input-dir下所有.xlsx文件(排除~$临时文件) - 对每个文件调用
processor.process_single_file() - 捕获异常,记录到
error_log.txt(含文件名、错误类型、traceback) - 成功文件移动到
output/processed/,失败文件移到output/failed/
提示: --debug 模式下,脚本会在同目录生成 debug.xlsx ,里面包含 Raw , Header_Detected , After_Cleaning , Final_Result 四个 sheet,相当于把整个处理流水线摊开给你看——这是排查“为什么这行没清洗”的后悔药。
4.2 日志与错误追踪:error_log.txt 里藏着真相
每次运行, main.py 都会生成 error_log.txt ,格式严格:
[2024-06-15 14:22:03] ERROR: class_schedule_v3.xlsx
TypeError: cannot concatenate str and int objects
Traceback (most recent call last):
File "processor.py", line 87, in process_single_file
cleaned_data = apply_cleaning_rules(raw_value, rules)
File "processor.py", line 121, in apply_cleaning_rules
new_value = rule(value)
关键点: 时间戳 + 文件名 + 具体错误行 + traceback 文件行号 。我靠这个日志,在 3 分钟内定位到 config.CLEANING_RULES 里一个 lambda x: x + "_v2" 规则,对空值 None 做了字符串拼接。修复就是加一行 if x is None: return x 。
4.3 避坑 / 常见问题 / 排查:5 条真实踩坑记录
现象 1:脚本运行成功,但输出 Excel 打开提示“发现不可读取的内容”,点击“是”后合并单元格全没了
原因 : openpyxl 写入时,如果某个 cell 的 value 是 datetime 对象但没设置 number_format ,Excel 会把它当普通数字处理,导致格式错乱。
解决 :在 write_result_to_new_sheet() 中,对 datetime 类型显式设置格式:
if isinstance(value, datetime):
cell.value = value
cell.number_format = 'yyyy-mm-dd'
现象 2:处理含中文路径的文件时报FileNotFoundError,路径里有空格或括号
原因 :Windows 命令行对路径空格和特殊字符(如 ( , ) )处理不一致, argparse 默认不转义。
解决 :在 main.py 的 argparse.ArgumentParser 初始化时加 formatter_class=argparse.RawDescriptionHelpFormatter ,并在 --input-dir 参数的 type 里加路径标准化:
def validate_path(path):
return os.path.abspath(os.path.normpath(path))
parser.add_argument("--input-dir", type=validate_path, ...)
现象 3:detect_header_row总是返回第1行,但实际表头在第5行
原因 : sample_data/ 里的示例文件用了浅灰色填充, ws.cell().fill.fgColor 返回 None ,导致 str(c).strip() 判定为空。
解决 :在 detect_header_row 的 non_empty 过滤前,加一行:
# 跳过纯背景色单元格(常见于表头占位符)
if ws.cell(row=row_idx, column=col_idx).fill.fgColor is not None:
continue
现象 4:--debug模式生成的debug.xlsx里After_Cleaningsheet 数据全是None
原因 : config.CLEANING_RULES 里某个 lambda 函数写了 return 但没返回值,Python 默认返回 None 。
解决 :在 apply_cleaning_rules 里加防御:
new_value = rule(value)
if new_value is None: # 强制 fallback 到原值
new_value = value
现象 5:Linux 服务器上运行报ModuleNotFoundError: No module named 'openpyxl',但pip list显示已安装
原因 :服务器有多个 Python 环境(如 /usr/bin/python3 和 /opt/python3.9/bin/python3 ), pip install 装到了 A 环境, python main.py 调用的是 B 环境。
解决 :统一用 python -m pip install openpyxl ,或直接指定解释器:/opt/python3.9/bin/python3 main.py --input-dir ./data/
5. 二次开发实战:如何把“课表清洗”改成“学生成绩分析”?
这才是项目价值的放大器。我拿它在某高校实验室快速改造出了“成绩分析版”,3 小时上线,核心就改了 3 个地方。
5.1 配置层改造:从config.py开始定义新业务规则
原 config.py 是课表逻辑,我们新建 config_grade.py (不覆盖原文件,便于回滚):
# config_grade.py
FIELD_MAPPING = {
"学号": "student_id",
"姓名": "student_name",
"高数": "math_score",
"英语": "english_score",
"总分": "total_score", # 这个字段原表没有,要计算
}
# 新增计算规则:总分 = 高数 + 英语 + 计算机(如果存在)
CALCULATION_RULES = {
"total_score": lambda row: (
(row.get("math_score", 0) or 0) +
(row.get("english_score", 0) or 0) +
(row.get("computer_score", 0) or 0)
)
}
# 新增分级规则:根据总分标等级
GRADE_MAPPING = {
(90, 100): "A",
(80, 89): "B",
(70, 79): "C",
(0, 69): "D"
}
def get_grade(score: float) -> str:
for (low, high), grade in GRADE_MAPPING.items():
if low <= score <= high:
return grade
return "N/A"
5.2 处理逻辑扩展:在processor.py里注入计算与分级
修改 process_single_file() ,在清洗后、写入前插入计算步骤:
# processor.py
def process_single_file(file_path: str, config_module=None) -> bool:
# ... 原有加载、识别表头、清洗逻辑 ...
# 【新增】执行计算规则
if hasattr(config_module, 'CALCULATION_RULES'):
for row in data:
for field, calc_func in config_module.CALCULATION_RULES.items():
try:
row[field] = calc_func(row)
except Exception as e:
row[field] = f"ERROR_CALC:{e}"
# 【新增】执行分级规则
if hasattr(config_module, 'get_grade') and 'total_score' in data[0]:
for row in data:
try:
row['grade'] = config_module.get_grade(row['total_score'])
except:
row['grade'] = "N/A"
# ... 后续写入逻辑 ...
5.3 输出增强:在write_result_to_new_sheet里加统计摘要
在新建的 Result sheet 顶部插入统计行:
# 在 write_result_to_new_sheet 函数开头插入:
# 写入统计摘要(放在第1行,原表头下移)
stats_row = [
f"总人数: {len(data)}",
f"平均分: {sum(r.get('total_score', 0) for r in data)/len(data):.1f}",
f"A级: {sum(1 for r in data if r.get('grade')=='A')}",
f"D级: {sum(1 for r in data if r.get('grade')=='D')}"
]
for col_idx, stat in enumerate(stats_row, 1):
cell = ws_result.cell(row=1, column=col_idx, value=stat)
cell.font = Font(bold=True, color="0070C0")
# 原表头从第2行开始写
header_row = 2
5.4 验证与交付:用 sample_data 快速回归测试
sample_data/ 里放一个 grade_sample.xlsx ,含 5 行模拟数据,运行:
python main.py --files ./sample_data/grade_sample.xlsx --debug
检查生成的 debug.xlsx :
Rawsheet:原始数据是否正确读取After_Cleaning:空值是否被0替换Final_Result:total_score列是否计算准确,grade列是否分级正确Resultsheet 顶部:统计行数字是否匹配
从那以后我每次接到 Excel 处理需求,都强制走一遍“复制 config.py → 改字段映射 → 加计算规则 → 跑 debug 模式验证”三步。不再问“这个能做吗”,而是说“给我 10 分钟,发你 demo”。
到此这篇关于Python openpyxl实现Excel数据清洗脚本的文章就介绍到这了,更多相关Python Excel数据清洗内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家!
相关文章
PyCharm-错误-找不到指定文件python.exe的解决方法
今天小编就为大家分享一篇PyCharm-错误-找不到指定文件python.exe的解决方法,具有很好的参考价值,希望对大家有所帮助。一起跟随小编过来看看吧2019-07-07


最新评论