19.1.11. email.header：国际化的头文件 — Python 文档

19.1.11。 邮件头 : 国际化的标题

源代码： :source:`Lib/email/header.py`

---

此模块是旧式 (Compat32) 电子邮件 API 的一部分。 在当前的 API 中，头部的编码和解码由 EmailMessage 类的类似字典的 API 透明处理。 除了在遗留代码中使用之外，该模块在需要完全控制编码标头时使用的字符集的应用程序中也很有用。

本节的其余文本是该模块的原始文档。

RFC 2822 是描述电子邮件消息格式的基本标准。 它源自较旧的 RFC 822 标准，该标准在大多数电子邮件仅由 ASCII 字符组成时广泛使用。 RFC 2822 是假设电子邮件仅包含 7 位 ASCII 字符的规范。

当然，随着电子邮件已在全球范围内部署，它已变得国际化，因此现在可以在电子邮件消息中使用特定于语言的字符集。 基本标准仍然要求仅使用 7 位 ASCII 字符传输电子邮件消息，因此已经编写了大量 RFC 来描述如何将包含非 ASCII 字符的电子邮件编码为 RFC 2822[X226X ] 兼容格式。 这些 RFC 包括 RFC 2045、RFC 2046、RFC 2047、 X107X]RFC 2231。 email 包在其 email.header 和 email.charset 模块中支持这些标准。

如果您想在电子邮件标题中包含非 ASCII 字符，例如在 Subject 或 To 字段中，您应该使用 Header 类并分配该字段在 Message 对象中添加到 Header 的实例，而不是使用字符串作为标头值。 从 email.header 模块导入 Header 类。 例如：

>>> from email.message import Message
>>> from email.header import Header
>>> msg = Message()
>>> h = Header('p\xf6stal', 'iso-8859-1')
>>> msg['Subject'] = h
>>> msg.as_string()
'Subject: =?iso-8859-1?q?p=F6stal?=\n\n'

请注意这里我们如何希望 Subject 字段包含非 ASCII 字符？ 我们通过创建一个 Header 实例并传入字节字符串编码的字符集来做到这一点。 当后续的 Message 实例被展平时，Subject 字段被正确地 RFC 2047 编码。 MIME 感知邮件阅读器将使用嵌入的 ISO-8859-1 字符显示此标题。

这里是 Header 类描述：

class email.header.Header(s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict')

创建一个符合 MIME 标准的标头，该标头可以包含不同字符集中的字符串。

可选的 s 是初始标头值。 如果 None（默认），则不设置初始标头值。 您可以稍后使用 append() 方法调用附加到标头。 s 可能是 bytes 或 str 的实例，但请参阅 append() 文档以了解语义。

可选的 charset 有两个用途：它与 append() 方法的 charset 参数具有相同的含义。 它还为省略 charset 参数的所有后续 append() 调用设置默认字符集。 如果 charset 未在构造函数中提供（默认），则 us-ascii 字符集既用作 s 的初始字符集，也用作后续 [ X177X]append() 调用。

最大行长度可以通过 maxlinelen 明确指定。 用于将第一行拆分为较短的值（以说明 s 中未包含的字段标题，例如 Subject) 传入 header_name 中的字段名称。 默认的 maxlinelen 是 76，而 header_name 的默认值是 None，这意味着它不会被考虑到一个长分割头的第一行。

可选的 continuation_ws 必须是 RFC 2822 兼容的折叠空白，通常是空格或硬制表符。 该字符将被添加到连续行之前。 continuation_ws 默认为单个空格字符。

可选的 errors 直接传递到 append() 方法。

append(s, charset=None, errors='strict')

将字符串 s 附加到 MIME 标头。

可选的 charset，如果给定，应该是一个 Charset 实例（参见 email.charset）或字符集的名称，它将被转换为 [ X165X]字符集实例。 None（默认值）的值意味着使用构造函数中给出的 charset。

s 可以是 bytes 或 str 的实例。 如果它是 bytes 的实例，则 charset 是该字节字符串的编码，如果无法使用该字符串解码，则会引发 UnicodeError字符集。

如果 s 是 str 的实例，则 charset 是指定字符串中字符的字符集的提示。

在任一情况下，当使用 RFC 2047 规则生成符合 RFC 2822 的标头时，字符串将使用输出编解码器进行编码的字符集。 如果无法使用输出编解码器对字符串进行编码，则会引发 UnicodeError。

如果 s 是字节字符串，则可选的 errors 作为错误参数传递给解码调用。

encode(splitchars=';, \\t', maxlinelen=None, linesep='\\n')

将消息头编码为符合 RFC 的格式，可能会包装长行并将非 ASCII 部分封装在 base64 或带引号的可打印编码中。

可选的 splitchars 是一个包含字符的字符串，在正常的标头包装期间应该由拆分算法赋予这些字符额外的权重。 这是对 RFC 2822' 的“更高级别的语法中断”的非常粗略的支持：在行拆分期间首选以 splitchar 开头的拆分点，在它们出现在字符串中的顺序。 字符串中可以包含空格和制表符，以指示当其他拆分字符没有出现在被拆分的行中时，是否应该优先考虑一个而不是另一个作为拆分点。 Splitchars 不影响 RFC 2047 编码的行。

maxlinelen，如果给定，则覆盖最大行长度的实例值。

linesep 指定用于分隔折叠标题行的字符。 它默认为 Python 应用程序代码最有用的值 (\n)，但可以指定 \r\n 以生成带有 RFC 兼容行分隔符的标头。

3.2 版更改： 添加 linesep 参数。

Header 类还提供了许多方法来支持标准运算符和内置函数。

__str__()

以字符串形式返回 Header 的近似值，使用无限行长度。 所有片段都使用指定的编码转换为 unicode 并适当地连接在一起。 任何具有 'unknown-8bit' 字符集的片段都使用 'replace' 错误处理程序解码为 ASCII。

3.2 版更改： 添加了对 'unknown-8bit' 字符集的处理。

__eq__(other)

此方法允许您比较两个 Header 实例是否相等。

__ne__(other)

此方法允许您比较两个 Header 实例的不等式。

email.header 模块还提供了以下方便的功能。

email.header.decode_header(header)

解码消息头值而不转换字符集。 标头值在 header 中。

此函数返回一个 (decoded_string, charset) 对的列表，其中包含标头的每个解码部分。 charset 是 None 用于标头的非编码部分，否则是包含在编码字符串中指定的字符集名称的小写字符串。

下面是一个例子：

>>> from email.header import decode_header
>>> decode_header('=?iso-8859-1?q?p=F6stal?=')
[(b'p\xf6stal', 'iso-8859-1')]

email.header.make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')

从 decode_header() 返回的对序列创建 Header 实例。

decode_header() 接受一个标头值字符串并返回格式为 (decoded_string, charset) 的对序列，其中 charset 是字符集的名称。

此函数采用这些对序列之一并返回 Header 实例。 可选的 maxlinelen、header_name 和 continuation_ws 与 Header 构造函数中的一样。