email.header ：国际化头 ¶

源代码： Lib/email/header.py

此模块属于传统 ( Compat32 ) 电子邮件 API。在当前 API 中，头编码/解码的透明处理是通过像字典 API 的 EmailMessage 类。除用于传统代码外，此模块在需要完全控制使用字符集 (当编码头时) 的应用程序中也很有用。

本章节中的其余文本是模块的原始文档编制。

RFC 2822 是描述 Email 消息格式的基标准。派生自旧 RFC 822 标准曾被广泛使用，当大多数 Email 仅以 ASCII 字符组成时。 RFC 2822 是假定 Email 仅包含 7 位 ASCII 字符而编写的规范。

当然，随着 Email 全世界部署，它已变得国际化，这样，特定语言字符集现在可以在 Email 消息中使用。基标准仍然要求仅使用 7 位 ASCII 字符传输 Email 消息，因此，已编写大量 RFC 描述如何将包含非 ASCII 字符的 Email 编码成 RFC 2822 兼容格式。这些 RFC 包括 RFC 2045 , RFC 2046 , RFC 2047 ，和 RFC 2231 。 email 包支持这些标准在其 email.header and email.charset 模块。

若想要在 Email 头中包括非 ASCII 字符，请在 Subject or To 字段，应该使用 Header 类和赋值字段在 Message 对象到实例化的 Header 而不是使用字符串对于头值。导入 Header 类从 email.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 (多用途 Internet 邮件扩展) 感知邮件阅读器将使用嵌入的 ISO-8859-1 字符展示此头。

这里是 Header 类描述：

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

创建可以包含按不同字符集的字符串的 MIME (多用途 Internet 邮件扩展) 兼容头。

可选 s 是初始 Header 头值。若 None (默认)，不设置初始头值。可以稍后追加到头采用 append() 方法调用。 s 可以是实例化的 bytes or str ，但请参阅 append() 文档编制了解语义。

可选 charset 服务于 2 个目的：它拥有的含义如同 charset 自变量到 append() 方法。它还设置默认字符集为所有后续 append() 调用省略 charset 自变量。若 charset 未在构造函数中提供 (默认)， us-ascii 字符集将用作 s 的初始字符集并作为默认对于后续 append() 调用。

最大行长度可以明确指定凭借 maxlinelen 。为将首行分割成更短值 (考虑到字段头未包括在 s ，如 Subject ) 传入字段名称在 header_name 。默认 maxlinelen 为 76，且默认值对于 header_name is None ，意味着不考虑长的、分割头的首行。

可选 continuation_ws 必须是 RFC 2822 兼容折叠空白，且通常是空格或硬 Tab 字符。此字符将前置到连续行。 continuation_ws 默认为单空格字符。

可选 errors 被直接传递给 append() 方法。

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

追加字符串 s 到 MIME (多用途 Internet 邮件扩展) 头。

可选 charset ，若给定，应为 Charset 实例 (见 email.charset ) 或字符集的名称，将被转换成 Charset 实例。值为 None (默认) 意味着 charset 使用在构造函数中给出的。

s 可以是实例化的 bytes or str 。若它是实例化的 bytes ，那么 charset 是该字节字符串的编码，和 UnicodeError 会被引发若字符串无法采用该字符集解码。

若 s 是实例化的 str ，那么 charset is a hint specifying the character set of the characters in the string.

In either case, when producing an RFC 2822 -compliant header using RFC 2047 rules, the string will be encoded using the output codec of the charset. If the string cannot be encoded using the output codec, a UnicodeError will be raised.

可选 errors 被传递作为错误自变量以解码调用若 s 是字节字符串。

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

Encode a message header into an RFC-compliant format, possibly wrapping long lines and encapsulating non-ASCII parts in base64 or quoted-printable encodings.

可选 splitchars is a string containing characters which should be given extra weight by the splitting algorithm during normal header wrapping. This is in very rough support of RFC 2822 ’s ‘higher level syntactic breaks’: split points preceded by a splitchar are preferred during line splitting, with the characters preferred in the order in which they appear in the string. Space and tab may be included in the string to indicate whether preference should be given to one over the other as a split point when other split chars do not appear in the line being split. Splitchars does not affect RFC 2047 encoded lines.

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

linesep specifies the characters used to separate the lines of the folded header. It defaults to the most useful value for Python application code ( \n )，但 \r\n can be specified in order to produce headers with RFC-compliant line separators.

3.2 版改变： 添加 linesep 自变量。

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

__str__ ( ) ¶

返回近似 Header 作为字符串，使用无限行长度。使用指定编码将所有片段转换成 Unicode 并适当拼接在一起。任何片段具有字符集 'unknown-8bit' 被解码为 ASCII 使用 'replace' 错误处理程序。

3.2 版改变： 添加处理 'unknown-8bit' 字符集。

__eq__ ( other ) ¶

此方法允许比较两 Header 实例对于相等。

__ne__ ( other ) ¶

此方法允许比较两 Header 实例对于不相等。

email.header 模块还提供下列方便函数。

email.header. decode_header ( header ) ¶

Decode a message header value without converting the character set. The header value is in header .

此函数返回列表对于 (decoded_string, charset) pairs containing each of the decoded parts of the header. charset is None for non-encoded parts of the header, otherwise a lower case string containing the name of the character set specified in the encoded string.

这里是范例：

>>> 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=' ' ) ¶

创建 Header instance from a sequence of pairs as returned by decode_header() .

decode_header() takes a header value string and returns a sequence of pairs of the format (decoded_string, charset) where charset is the name of the character set.

This function takes one of those sequence of pairs and returns a Header 实例。可选 maxlinelen , header_name ，和 continuation_ws are as in the Header 构造函数。

上一话题

email.mime : 从新创建 Email 和 MIME 对象

下一话题

email.charset ：表示字符集