openpyxl中IllegalCharacterError与ValueError的统一处理咨询

问题背景 #

我用pandas结合openpyxl导出数据库数据到Excel，文本字段常包含特殊字符。之前遇到IllegalCharacterError时已经实现了问题单元格的定位方案，但近期触发了新错误：

ValueError: All strings must be XML compatible: Unicode or ASCII, no NULL bytes or control characters

希望把这个ValueError转为IllegalCharacterError统一处理，也想知道能否通过替换字节解决；同时疑惑在openpyxl仓库提issue建议统一抛出IllegalCharacterError是否合理。

复现代码 #

from openpyxl import Workbook

text = "" # 包含十六进制FFBFBF的三个字节，触发ValueError
# text = '\x16'                                        # 触发IllegalCharacterError

wb = Workbook()
ws = wb.active
ws.append([text])
wb.save("test.xlsx")

环境配置 #

openpyxl                 3.1.2
OS Linux-6.11.5-200.fc40.x86_64-x86_64-with-glibc2.39 (Fedora)
Python 3.12.7 (main, Oct  1 2024, 00:00:00) [GCC 14.2.1 20240912 (Red Hat 14.2.1-3)]

核心痛点 #

• pandas中两种异常抛出时机不同：IllegalCharacterError在to_excel阶段触发，ValueError在writer.close()阶段触发
• ValueError场景下无法定位具体的问题文本

问题解答 #

1. 通过替换字节解决异常 #

可以通过预处理文本，过滤或替换不符合XML规范的字符来避免两种异常：

• 对于控制字符（触发IllegalCharacterError的情况），保留XML允许的制表符(\t)、换行(\n)、回车(\r)，替换其他控制字符
• 对于非XML兼容的字节（如FFBFBF这类无效UTF-8字节、NULL字节），先转为合法UTF-8再过滤控制字符

示例预处理函数：

import re

def clean_text(text):
    if not isinstance(text, str):
        return text
    # 移除NULL字节
    text = text.replace('\x00', '')
    # 过滤XML禁止的控制字符
    forbidden_control = re.compile(r'[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]')
    text = forbidden_control.sub('', text)
    # 修复无效Unicode字符
    text = text.encode('utf-8', 'replace').decode('utf-8')
    return text

在pandas导出前对所有文本列应用该函数：

df = df.applymap(clean_text)
df.to_excel(writer, index=False)
writer.close()

2. 统一异常类型的合理性 #

直接将ValueError转为IllegalCharacterError需要修改openpyxl源码，但向openpyxl仓库提交issue建议统一异常类型是合理的：

• 两种错误本质都是输入文本不符合Excel XML格式要求，统一抛出IllegalCharacterError能降低开发者的处理成本
• 提交issue时可同时建议优化异常信息，增加问题文本的位置或片段，方便快速定位问题

内容的提问来源于stack exchange，提问作者Arpad Horvath -- Слава Україні