Python quopri 怎样解码带软换行的邮件正文

平时用Python处理邮件解析相关需求的时候，很容易碰到采用Quoted-Printable编码、带大量以=作为结尾标记的软换行的邮件正文，直接用Python内置的quopri标准库就能完成解码操作，不用自己手动写逻辑处理转义规则。

直接调用quopri模块的解码接口，传入对应编码的字节数据，就能自动识别并清除所有软换行标记，输出还原后的正常正文内容。

邮件正文如果使用 quoted-printable 传输编码，长行可能在等号后换行，中文或特殊字节也可能写成 =XX。这种内容不能直接当作普通字符串拼接，应该先用 Python 标准库 quopri 还原传输层字节，再根据邮件声明的字符集解码成文本。

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

最常用的写法是 quopri.decodestring(body_bytes)。它会处理 quoted-printable 的软换行并返回 bytes；如果正文很大，则改用接收二进制文件对象的 quopri.decode()。字符集转换要放在这一步之后，正文场景通常不要传入 header=True。

先确认正文确实是 quoted-printable

不要看到等号就直接解码。MIME 部分的 Content-Transfer-Encoding 应该明确写成 quoted-printable；如果是 base64 或 8bit，应使用对应的处理方式。quoted-printable 的软换行通常表现为行尾等号，真正的换行不会保留这个等号。

排障时把原始正文保留为 bytes，先观察编码标记和少量原始片段。这样可以区分“传输编码没有还原”和“还原后按错误字符集显示”这两种常被混在一起的问题。

用 decodestring 解码内存中的正文

正文已经在内存中时，decodestring() 是最直接的入口。它接收源 bytes 并返回解码后的 bytes，所以不会替你猜测 UTF-8、GBK 等字符集。

from quopri import decodestring

# 末尾的等号表示 quoted-printable 软换行，不应出现在最终正文中。
body = (
    b"Hello=20Python=21=\r\n"
    b"Mail=3A=20caf=C3=A9\r\n"
)

# 先还原传输编码，结果仍然是 bytes。
decoded_bytes = decodestring(body)

# 字符集转换属于下一层；这里的示例正文使用 UTF-8。
decoded_text = decoded_bytes.decode("utf-8")
print(decoded_text)

这里的关键顺序是“quopri 解传输编码，再 bytes.decode() 解字符集”。如果直接对原始正文调用 decode("utf-8")，=20、=3A 这类传输层标记不会自动还原。

用 decode 处理较大的二进制流

如果正文来自临时文件或附件解析流程，不必先把所有内容读成一个大字符串。quopri.decode(input, output) 的两个参数都应是二进制文件对象，可以把转换结果直接写入另一个二进制目标。

from pathlib import Path
from quopri import decode

source_path = Path("mail-body.qp")
target_path = Path("mail-body.decoded")

# 使用二进制模式，避免文本层提前改写换行或字符。
with source_path.open("rb") as source, target_path.open("wb") as target:
    # decode 负责 quoted-printable，输出仍保持为原始 bytes。
    decode(source, target)

# 读取后的 bytes 再按邮件头声明的 charset 转成文本。
decoded_text = target_path.read_bytes().decode("utf-8")
print(decoded_text[:80])

这条路径适合大正文：文件对象承担输入输出，调用方只在最后一步读取需要展示的部分。输入和输出必须使用 rb/wb，否则文本包装层可能先改变换行，排查起来会更困难。

区分正文解码、字符集转换和 header 参数

quopri 解决的是 MIME quoted-printable 传输编码，不是万能的乱码修复器。解码后仍然乱码，优先检查邮件部分的 charset，例如先得到 decoded_bytes，再使用对应的 decoded_bytes.decode(charset, errors="replace")。只有在确实需要容错展示时才使用 replace，否则应保留异常以便发现错误的字符集声明。

header=True 的含义也要单独看待：官方文档说明它会把下划线按空格处理，用于 RFC 1522 的 Q 编码头部。邮件正文出现下划线时，不要为了“看起来像 Q 编码”就打开这个参数，否则正文中的真实下划线可能被改写。

异常输入怎么留出排障线索

生产邮件处理可以把问题分成三层记录：第一层是 MIME 传输编码与调用入口是否匹配；第二层是解码后字节是否符合声明的字符集；第三层才是业务文本清洗。不要在第一层失败时直接用多个字符集轮询并吞掉全部异常，否则后续很难判断是错误的邮件头还是损坏的正文。

from quopri import decodestring

def decode_mail_body(raw_body: bytes, charset: str) -> str:
    # 先还原 quoted-printable，保留传输层错误的定位边界。
    decoded = decodestring(raw_body)
    try:
        # 字符集由 MIME 头提供，不能让 quopri 替你猜测。
        return decoded.decode(charset)
    except (LookupError, UnicodeDecodeError) as exc:
        # 记录编码名和异常后再决定是否降级展示，避免静默吞错。
        raise ValueError(f"邮件正文字符集无法解码: {charset}") from exc

这样处理后，带软换行的正文会在传输层先恢复，真正的字符集问题也会在明确的位置暴露。对普通内存正文使用 decodestring，对大文件使用 decode，并把 header=True 留给 Q 编码头部，是最不容易混淆的分工。

相关问题

为什么解码后仍然是 bytes？ 因为 quopri 只负责 quoted-printable，字符集属于后续的文本解码层。

软换行会不会变成普通换行？ 行尾等号表示传输层续行，解码时会被移除；正文真正的换行仍按输入内容保留。

正文能不能直接使用 header=True？ 一般不应这样做。它针对 Q 编码头部的下划线规则，正文的下划线应按正文原值保留。