batch_rename_by_excel Skill
按 Excel 映射批量重命名文件
功能描述
用户手里有一批需要改名的文件,改名前后的对应关系已经整理在 Excel 里。本 Skill 读取 Excel 中的「原文件名 → 新文件名」映射,批量重命名指定目录下的文件。
和 replace4filename 的区别:replace4filename 是「按规则批量替换文件名中的字符」,
本 Skill 是「按 Excel 中逐行指定的映射改名」,适合改名规则不统一、只能逐个列出的场景。
所属分类
skills/file/batch_rename_by_excel/
调用方式
from skills.file.batch_rename_by_excel import batch_rename_by_excel
实现代码位于贡献者目录,也可以直接引用:
from contributors.my12yyds.batch_rename_by_excel import batch_rename_by_excel
注意:
contributors/不随pip install python-office一起发布,安装包环境中请直接 复制contributors/my12yyds/batch_rename_by_excel.py到自己的项目里使用。
参数说明
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
excel_path |
str | 是 | - | 记录新旧文件名映射的 Excel 文件路径,支持 .xlsx |
folder_path |
str | 是 | - | 需要重命名文件所在的目录路径,只处理该目录第一层的文件 |
old_name_column |
str | 否 | '原文件名' |
Excel 中存放原文件名的列名 |
new_name_column |
str | 否 | '新文件名' |
Excel 中存放新文件名的列名 |
sheet_name |
str | 否 | None |
工作表名称,默认使用第一个工作表 |
dry_run |
bool | 否 | False |
为 True 时只返回重命名计划,不真正修改文件 |
返回值
dict,包含 4 个键:
| 键 | 类型 | 说明 |
|---|---|---|
renamed |
list | 已重命名的记录,元素为 (原文件名, 新文件名) 元组;dry_run=True 时为计划重命名的记录 |
skipped |
list | 未执行重命名的记录,元素为 (文件名, 原因) 元组,例如新旧文件名相同、原文件名或新文件名为空 |
missing |
list | Excel 中有记录、但目录下找不到的原文件名 |
conflicts |
list | 目标文件名已存在,为避免覆盖而跳过的原文件名 |
使用示例
Excel 内容(表头必须是这两列):
| 原文件名 | 新文件名 |
|---|---|
| a.txt | 2026年1月报表.txt |
| b.txt | 2026年2月报表.txt |
from skills.file.batch_rename_by_excel import batch_rename_by_excel
# 先预览,确认映射没问题
result = batch_rename_by_excel(
excel_path='./rename_list.xlsx',
folder_path='./files',
dry_run=True,
)
print(result['renamed'])
# 确认无误后再真正执行
result = batch_rename_by_excel(
excel_path='./rename_list.xlsx',
folder_path='./files',
)
print('成功', len(result['renamed']), '个')
print('找不到', result['missing'])
print('目标已存在', result['conflicts'])
原始函数
contributors/my12yyds/batch_rename_by_excel.py::batch_rename_by_excel
