Python quopri 解码邮件头时为什么要处理下划线

Python 的 quopri 在解码邮件头时处理下划线，是因为 MIME 的 Q 编码把邮件头里的普通空格写成了下划线；这条规则只属于“头部语境”。对邮件正文调用 quopri.decodestring() 时，默认的 header=False 会保留下划线，只有确认输入是 Q 编码邮件头片段时，才使用 header=True 把它还原为空格。

官方地址：https://docs.python.org/3/library/quopri.html

header 参数决定下划线的语境

quopri 解码的是 bytes。下面的例子故意让输入保持简单：同一段 Hello_World=20Python，只切换 header 参数。输出差异不是编码器随机行为，而是邮件头 Q 编码对空格的特殊约定。

from quopri import decodestring

# 普通 quoted-printable 数据：下划线没有特殊含义
body_value = decodestring(b"Hello_World=20Python")

# Q 编码邮件头片段：下划线按邮件头规则还原为空格
header_value = decodestring(b"Hello_World=20Python", header=True)

print(body_value)    # b'Hello_World Python'
print(header_value)  # b'Hello World Python'

因此，看到标题里的下划线时先问“这是不是 Q 编码邮件头”，不要为了让结果看起来像自然语言就无条件传入 header=True。普通正文中的文件名、标识符或 JSON 字段可能确实需要保留下划线。

完整 encoded-word 不应只靠 quopri 拆解

真实邮件头通常不是一段裸的 Q 编码，而是 =?字符集?编码?载荷?= 这样的 encoded-word。载荷里的下划线属于 Q 编码，前面的字符集、编码方式和后面的字节转文本也需要一起处理。此时让 email.header 负责分层更稳妥：

from email.header import decode_header, make_header

raw_header = "=?utf-8?q?Python_3=E5=AE=9E=E6=88=98?="

# decode_header 先拆出字符集和编码；make_header 再组合成可读文本
parts = decode_header(raw_header)
decoded = str(make_header(parts))
print(decoded)  # Python 3实战

如果你已经从邮件解析器拿到了 Q 编码载荷，才适合直接调用 quopri.decodestring(payload, header=True)。如果输入仍包含 =?utf-8?q? 和 ?=，直接把整串交给 quopri，只会得到不完整的处理结果。

按输入形态选择 API，排查三类常见误判

第一类误判是把普通正文当成邮件头，导致用户名、文件名里的下划线消失；第二类误判是把完整 encoded-word 当作裸载荷，结果残留 =? 或出现乱码；第三类误判是忘记 bytes 边界，直接把字符串传给只接受二进制文件对象的 quopri.decode()。小片段用 decodestring()，文件流用 decode(input, output, header=True)，选择会更清楚。

常见问题

为什么 header=True 不等于“把所有下划线转空格”？

它表达的是 Q 编码邮件头语境；普通 quoted-printable 正文不应套用这条规则。参数含义是输入协议上下文，而不是显示格式开关。

邮件主题解码还需要自己调用 quopri 吗？

通常不需要。完整主题交给 email.header.decode_header() 和 make_header()，只有已经分离出 Q 编码载荷时才直接使用 quopri。

为什么输出是 bytes 而不是中文字符串？

quopri 只负责传输编码层，字符集解码是下一层职责。先根据邮件头声明的 charset 解码 bytes，再交给文本处理逻辑。