19.1.9. email.message.Message: 使用 compat32 API 来表示电子邮件消息

Message 类与 EmailMessage 类非常相似，但没有该类所添加的方法，并且某些方法的默认行为也略有不同。 我们还在这里记录了一些虽然被 EmailMessage 类所支持但并不推荐的方法，除非你是在处理旧有代码。

在其他情况下这两个类的理念和结构都是相同的。

本文档描述了默认 (对于 Message) 策略 Compat32 之下的行为。 如果你要使用其他策略，你应当改用 EmailMessage 类。

电子邮件消息是由多个 标头 和一个 payload 载荷组成的。 标头必须为 RFC 5233 风格的名称和值，其中字段名和值由冒号分隔。 冒号不是字段名或字段值的组成部分。 载荷可以是简单的文本消息，或是二进制对象，或是多个子消息的结构化序列，每个子消息都有自己的标头集合和自己的载荷。 后一种类型的载荷是由具有 multipart/* 或 message/rfc822 等 MIME 类型的消息来指明的。

Message 对象所提供了概念化模型是由标头组成的有序字典，加上用于访问标头中的特殊信息以及访问载荷的额外方法，以便能生成消息的序列化版本，并递归地遍历对象树。 请注意重复的标头是受支持的，但必须使用特殊的方法来访问它们。

Message 伪字典以标头名作为索引，标头名必须为 ASCII 值。 字典的值为应当只包含 ASCII 字符的字符串；对于非 ASCII 输入有一些特殊处理，但这并不总能产生正确的结果。 标头以保留原大小写的形式存储和返回，但字段名称匹配对大小写不敏感。 还可能会有一个单独的封包标头，也称 Unix-From 标头或 From_ 标头。 载荷 对于简单消息对象的情况是一个字符串或字节串，对于 MIME 容器文档的情况 (例如 multipart/* 和 message/rfc822) 则是一个 Message 对象。

以下是 Message 类的方法:

class email.message.Message(policy=compat32)

如果指定了 policy (它必须为 policy 类的实例) 则使用它所设置的规则来更新和序列化消息的表示形式。 如果未设置 policy，则使用 compat32 策略，该策略会保持对 Python 3.2 版 email 包的向下兼容性。 更多信息请参阅 policy 文档。

在 3.3 版更改: 增加了 policy 关键字参数。

as_string(unixfrom=False, maxheaderlen=0, policy=None)

以展平的字符串形式返回整个消息对象。 或可选的 unixfrom 为真值，返回的字符串会包括封包标头。 unixfrom 的默认值是 False。 出于保持向下兼容性的原因，maxheaderlen 的默认值是 0，因此如果你想要不同的值你必须显式地重载它（在策略中为 max_line_length 指定的值将被此方法忽略）。 policy 参数可被用于覆盖从消息实例获取的默认策略。 这可以用来对该方法所输出的格式进行一些控制，因为指定的 policy 将被传递给 Generator。

如果需要填充默认值以完成对字符串的转换则展平消息可能触发对 Message 的修改（例如，MIME 边界可能会被生成或被修改）。

请注意此方法是出于便捷原因提供的，可能无法总是以你想要的方式格式化消息。 例如，在默认情况下它不会按 unix mbox 格式的要求对以 From 打头的行执行调整。 为了获得更高灵活性，请实例化一个 Generator 实例并直接使用其 flatten() 方法。 例如:

from io import StringIO
from email.generator import Generator
fp = StringIO()
g = Generator(fp, mangle_from_=True, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()

如果消息对象包含未按照 RFC 标准进行编码的二进制数据，则这些不合规数据将被 unicode “unknown character” 码位值所替代。 （另请参阅 as_bytes() 和 BytesGenerator。）

在 3.4 版更改: 增加了 policy 关键字参数。

__str__()

与 as_string() 等价。 这将让 str(msg) 产生一个包含已格式化消息的字符号。

as_bytes(unixfrom=False, policy=None)

以字节串对象的形式返回整个扁平化后的消息。 当可选的 unixfrom 为真值时，返回的字符串会包括封包标头。 unixfrom 的默认值为 False。 policy 参数可被用于重载从消息实例获取的默认策略。 这可被用来控制该方法所产生的部分格式化效果，因为指定的 policy 将被传递给 BytesGenerator。

如果需要填充默认值以完成对字符串的转换则展平消息可能触发对 Message 的修改（例如，MIME 边界可能会被生成或被修改）。

请注意此方法是出于便捷原因提供的，可能无法总是以你想要的方式格式化消息。 例如，在默认情况下它不会按 unix mbox 格式的要求对以 From 打头的行执行调整。 为了获得更高灵活性，请实例化一个 BytesGenerator 实例并直接使用其 flatten() 方法。 例如:

from io import BytesIO
from email.generator import BytesGenerator
fp = BytesIO()
g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()

3.4 新版功能.

__bytes__()

与 as_bytes() 等价。 这将让 bytes(msg) 产生一个包含已格式化消息的字节串对象。

3.4 新版功能.

is_multipart()

如果该消息的载荷是一个子 Message 对象列表则返回 True，否则返回 False。 当 is_multipart() 返回 False 时，载荷应当是一个字符串对象（有可能是一个 CTE 编码的二进制载荷）。 （请注意 is_multipart() 返回 True 并不意味着 “msg.get_content_maintype() == ‘multipart’” 将返回 True。 例如，is_multipart 在 Message 类型为 message/rfc822 时也将返回 True。）

set_unixfrom(unixfrom)

将消息的封包标头设为 unixfrom，这应当是一个字符串。

get_unixfrom()

返回消息的信封头。如果信封头从未被设置过，默认返回 None 。

attach(payload)

将给定的 payload 添加到当前载荷中，当前载荷在该调用之前必须为 None 或是一个 Message 对象列表。 在调用之后，此载荷将总是一个 Message 对象列表。 如果你想将此载荷设为一个标量对象（如字符串），请改用 set_payload()。

这是一个过时的方法。 在 EmailMessage 类上它的功能已被 set_content() 及相应的 make 和 add 方法所替代。

get_payload(i=None, decode=False)

返回当前的载荷，它在 is_multipart() 为 True 时将是一个 Message 对象列表，在 is_multipart() 为 False 时则是一个字符串。 如果该载荷是一个列表且你修改了这个列表对象，那么你就是原地修改了消息的载荷。

传入可选参数 i 时，如果 is_multipart() 为 True，get_payload() 将返回载荷从零开始计数的第 i 个元素。 如果 i 小于 0 或大于等于载荷中的条目数则将引发 IndexError。 如果载荷是一个字符串 (即 is_multipart() 为 False) 且给出了 i，则会引发 TypeError。

可选的 decode 是一个指明载荷是否应根据 Content-Transfer-Encoding 标头被解码的旗标。 当其值为 True 且消息没有多个部分时，如果此标头值为 quoted-printable 或 base64 则载荷将被解码。 如果使用了其他编码格式，或者找不到 Content-Transfer-Encoding 标头时，载荷将被原样返回（不编码）。 在所有情况下返回值都是二进制数据。 如果消息有多个部分且 decode 旗标为 True，则将返回 None。 如果载荷为 base64 但内容不完全正确（如缺少填充符、存在 base64 字母表以外的字符等），则将在消息的缺陷属性中添加适当的缺陷值 (分别为 InvalidBase64PaddingDefect 或 InvalidBase64CharactersDefect)。

当 decode 为 False (默认值) 时消息体会作为字符串返回而不解码 Content-Transfer-Encoding。 但是，对于 Content-Transfer-Encoding 为 8bit 的情况，会尝试使用 Content-Type 标头指定的 charset 来解码原始字节串，并使用 replace 错误处理程序。 如果未指定 charset，或者如果指定的 charset 未被 email 包所识别，则会使用默认的 ASCII 字符集来解码消息体。

这是一个过时的方法。 在 EmailMessage 类上它的功能已被 get_content() 和 iter_parts() 方法所替代。

set_payload(payload, charset=None)

将整个消息对象的载荷设为 payload。 客户端要负责确保载荷的不变性。 可选的 charset 用于设置消息的默认字符集；详情请参阅 set_charset()。

这是一个过时的方法。 在 EmailMessage 类上它的功能已被 set_content() 方法所替代。

set_charset(charset)

Set the character set of the payload to charset, which can either be a Charset instance (see email.charset), a string naming a character set, or None. If it is a string, it will be converted to a Charset instance. If charset is None, the charset parameter will be removed from the Content-Type header (the message will not be otherwise modified). Anything else will generate a TypeError.

If there is no existing MIME-Version header one will be added. If there is no existing Content-Type header, one will be added with a value of text/plain. Whether the Content-Type header already exists or not, its charset parameter will be set to charset.output_charset. If charset.input_charset and charset.output_charset differ, the payload will be re-encoded to the output_charset. If there is no existing Content-Transfer-Encoding header, then the payload will be transfer-encoded, if needed, using the specified Charset, and a header with the appropriate value will be added. If a Content-Transfer-Encoding header already exists, the payload is assumed to already be correctly encoded using that Content-Transfer-Encoding and is not modified.

This is a legacy method. On the EmailMessage class its functionality is replaced by the charset parameter of the email.emailmessage.EmailMessage.set_content() method.

get_charset()

Return the Charset instance associated with the message’s payload.

This is a legacy method. On the EmailMessage class it always returns None.

The following methods implement a mapping-like interface for accessing the message’s RFC 2822 headers. Note that there are some semantic differences between these methods and a normal mapping (i.e. dictionary) interface. For example, in a dictionary there are no duplicate keys, but here there may be duplicate message headers. Also, in dictionaries there is no guaranteed order to the keys returned by keys(), but in a Message object, headers are always returned in the order they appeared in the original message, or were added to the message later. Any header deleted and then re-added are always appended to the end of the header list.

These semantic differences are intentional and are biased toward maximal convenience.

还请留意，无论在什么情况下，消息当中的任何信封头字段都不会包含在映射接口当中。

In a model generated from bytes, any header values that (in contravention of the RFCs) contain non-ASCII bytes will, when retrieved through this interface, be represented as Header objects with a charset of unknown-8bit.

__len__()

返回头字段的总数，重复的也计算在内。

__contains__(name)

Return true if the message object has a field named name. Matching is done case-insensitively and name should not include the trailing colon. Used for the in operator, e.g.:

if 'message-id' in myMessage:
   print('Message-ID:', myMessage['message-id'])

__getitem__(name)

Return the value of the named header field. name should not include the colon field separator. If the header is missing, None is returned; a KeyError is never raised.

Note that if the named field appears more than once in the message’s headers, exactly which of those field values will be returned is undefined. Use the get_all() method to get the values of all the extant named headers.

__setitem__(name, val)

Add a header to the message with field name name and value val. The field is appended to the end of the message’s existing fields.

请注意，这个方法 既不会 覆盖 也不会 删除任何字段名重名的已有字段。如果你确实想保证新字段是整个信息头当中唯一拥有 name 字段名的字段，你需要先把旧字段删除。例如：

del msg['subject']
msg['subject'] = 'Python roolz!'

__delitem__(name)

删除信息头当中字段名匹配 name 的所有字段。如果匹配指定名称的字段没有找到，也不会抛出任何异常。

keys()

以列表形式返回消息头中所有的字段名。

values()

以列表形式返回消息头中所有的字段值。

items()

以二元元组的列表形式返回消息头中所有的字段名和字段值。

get(name, failobj=None)

Return the value of the named header field. This is identical to __getitem__() except that optional failobj is returned if the named header is missing (defaults to None).

以下是一些有用的附加方法:

get_all(name, failobj=None)

返回字段名为 name 的所有字段值的列表。如果信息内不存在匹配的字段，返回 failobj （其默认值为 None ）。

add_header(_name, _value, **_params)

高级头字段设定。这个方法与 __setitem__() 类似，不过你可以使用关键字参数为字段提供附加参数。 _name 是字段名， _value 是字段 主 值。

For each item in the keyword argument dictionary _params, the key is taken as the parameter name, with underscores converted to dashes (since dashes are illegal in Python identifiers). Normally, the parameter will be added as key="value" unless the value is None, in which case only the key will be added. If the value contains non-ASCII characters, it can be specified as a three tuple in the format (CHARSET, LANGUAGE, VALUE), where CHARSET is a string naming the charset to be used to encode the value, LANGUAGE can usually be set to None or the empty string (see RFC 2231 for other possibilities), and VALUE is the string value containing non-ASCII code points. If a three tuple is not passed and the value contains non-ASCII characters, it is automatically encoded in RFC 2231 format using a CHARSET of utf-8 and a LANGUAGE of None.

以下是为示例代码:

msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')

会添加一个形如下文的头字段：

Content-Disposition: attachment; filename="bud.gif"

使用非 ASCII 字符的示例代码:

msg.add_header('Content-Disposition', 'attachment',
               filename=('iso-8859-1', '', 'Fußballer.ppt'))

它的输出结果为

Content-Disposition: attachment; filename*="iso-8859-1''Fu%DFballer.ppt"

replace_header(_name, _value)

Replace a header. Replace the first header found in the message that matches _name, retaining header order and field name case. If no matching header was found, a KeyError is raised.

get_content_type()

Return the message’s content type. The returned string is coerced to lower case of the form maintype/subtype. If there was no Content-Type header in the message the default type as given by get_default_type() will be returned. Since according to RFC 2045, messages always have a default type, get_content_type() will always return a value.

RFC 2045 defines a message’s default type to be text/plain unless it appears inside a multipart/digest container, in which case it would be message/rfc822. If the Content-Type header has an invalid type specification, RFC 2045 mandates that the default type be text/plain.

get_content_maintype()

返回信息的主要内容类型。准确来说，此方法返回的是 get_content_type() 方法所返回的形如 maintype/subtype 的字符串当中的 maintype 部分。

get_content_subtype()

返回信息的子内容类型。准确来说，此方法返回的是 get_content_type() 方法所返回的形如 maintype/subtype 的字符串当中的 subtype 部分。

get_default_type()

返回默认的内容类型。绝大多数的信息，其默认内容类型都是 text/plain 。作为 multipart/digest 容器内子部分的信息除外，它们的默认内容类型是 message/rfc822 。

set_default_type(ctype)

Set the default content type. ctype should either be text/plain or message/rfc822, although this is not enforced. The default content type is not stored in the Content-Type header.

get_params(failobj=None, header='content-type', unquote=True)

Return the message’s Content-Type parameters, as a list. The elements of the returned list are 2-tuples of key/value pairs, as split on the '=' sign. The left hand side of the '=' is the key, while the right hand side is the value. If there is no '=' sign in the parameter the value is the empty string, otherwise the value is as described in get_param() and is unquoted if optional unquote is True (the default).

Optional failobj is the object to return if there is no Content-Type header. Optional header is the header to search instead of Content-Type.

This is a legacy method. On the EmailMessage class its functionality is replaced by the params property of the individual header objects returned by the header access methods.

get_param(param, failobj=None, header='content-type', unquote=True)

Return the value of the Content-Type header’s parameter param as a string. If the message has no Content-Type header or if there is no such parameter, then failobj is returned (defaults to None).

Optional header if given, specifies the message header to use instead of Content-Type.

Parameter keys are always compared case insensitively. The return value can either be a string, or a 3-tuple if the parameter was RFC 2231 encoded. When it’s a 3-tuple, the elements of the value are of the form (CHARSET, LANGUAGE, VALUE). Note that both CHARSET and LANGUAGE can be None, in which case you should consider VALUE to be encoded in the us-ascii charset. You can usually ignore LANGUAGE.

If your application doesn’t care whether the parameter was encoded as in RFC 2231, you can collapse the parameter value by calling email.utils.collapse_rfc2231_value(), passing in the return value from get_param(). This will return a suitably decoded Unicode string when the value is a tuple, or the original string unquoted if it isn’t. For example:

rawparam = msg.get_param('foo')
param = email.utils.collapse_rfc2231_value(rawparam)

In any case, the parameter value (either the returned string, or the VALUE item in the 3-tuple) is always unquoted, unless unquote is set to False.

This is a legacy method. On the EmailMessage class its functionality is replaced by the params property of the individual header objects returned by the header access methods.

set_param(param, value, header='Content-Type', requote=True, charset=None, language='', replace=False)

Set a parameter in the Content-Type header. If the parameter already exists in the header, its value will be replaced with value. If the Content-Type header as not yet been defined for this message, it will be set to text/plain and the new parameter value will be appended as per RFC 2045.

Optional header specifies an alternative header to Content-Type, and all parameters will be quoted as necessary unless optional requote is False (the default is True).

If optional charset is specified, the parameter will be encoded according to RFC 2231. Optional language specifies the RFC 2231 language, defaulting to the empty string. Both charset and language should be strings.

如果 replace 为 False （默认值），该头字段会被移动到所有头字段的末尾。如果 replace 为 True ，字段会被原地更新。

在 3.4 版更改: 添加了 replace 关键字。

del_param(param, header='content-type', requote=True)

Remove the given parameter completely from the Content-Type header. The header will be re-written in place without the parameter or its value. All values will be quoted as necessary unless requote is False (the default is True). Optional header specifies an alternative to Content-Type.

set_type(type, header='Content-Type', requote=True)

Set the main type and subtype for the Content-Type header. type must be a string in the form maintype/subtype, otherwise a ValueError is raised.

This method replaces the Content-Type header, keeping all the parameters in place. If requote is False, this leaves the existing header’s quoting as is, otherwise the parameters will be quoted (the default).

An alternative header can be specified in the header argument. When the Content-Type header is set a MIME-Version header is also added.

This is a legacy method. On the EmailMessage class its functionality is replaced by the make_ and add_ methods.

get_filename(failobj=None)

返回信息头当中 Content-Disposition 字段当中名为 filename 的参数值。如果该字段当中没有此参数，该方法会退而寻找 Content-Type 字段当中的 name 参数值。如果这个也没有找到，或者这些个字段压根就不存在，返回 failobj 。返回的字符串永远按照 email.utils.unquote() 方法去除引号。

get_boundary(failobj=None)

返回信息头当中 Content-Type 字段当中名为 boundary 的参数值。如果字段当中没有此参数，或者这些个字段压根就不存在，返回 failobj 。返回的字符串永远按照 email.utils.unquote() 方法去除引号。

set_boundary(boundary)

将 Content-Type 头字段的 boundary 参数设置为 boundary 。 set_boundary() 方法永远都会在必要的时候为 boundary 添加引号。如果信息对象中没有 Content-Type 头字段，抛出 HeaderParseError 异常。

Note that using this method is subtly different than deleting the old Content-Type header and adding a new one with the new boundary via add_header(), because set_boundary() preserves the order of the Content-Type header in the list of headers. However, it does not preserve any continuation lines which may have been present in the original Content-Type header.

get_content_charset(failobj=None)

返回 Content-Type 头字段中的 charset 参数，强制小写。如果字段当中没有此参数，或者这个字段压根不存在，返回 failobj 。

Note that this method differs from get_charset() which returns the Charset instance for the default encoding of the message body.

get_charsets(failobj=None)

返回一个包含了信息内所有字符集名字的列表。如果信息是 multipart 类型的，那么列表当中的每一项都对应其负载的子部分的字符集名字。否则，该列表是一个长度为1的列表。

Each item in the list will be a string which is the value of the charset parameter in the Content-Type header for the represented subpart. However, if the subpart has no Content-Type header, no charset parameter, or is not of the text main MIME type, then that item in the returned list will be failobj.

get_content_disposition()

如果信息的 Content-Disposition 头字段存在，返回其字段值；否则返回 None 。返回的值均为小写，不包含参数。如果信息遵循 RFC 2183 标准，则返回值只可能在 inline 、 attachment 和 None 之间选择。

3.5 新版功能.

walk()

walk() 方法是一个多功能生成器。它可以被用来以深度优先顺序遍历信息对象树的所有部分和子部分。一般而言， walk() 会被用作 for 循环的迭代器，每一次迭代都返回其下一个子部分。

以下例子会打印出一封具有多部分结构之信息的每个部分的 MIME 类型。

>>> for part in msg.walk():
...     print(part.get_content_type())
multipart/report
text/plain
message/delivery-status
text/plain
text/plain
message/rfc822
text/plain

walk 会遍历所有 is_multipart() 方法返回 True 的部分之子部分，哪怕 msg.get_content_maintype() == 'multipart' 返回的是 False 。使用 _structure 除错帮助函数可以帮助我们在下面这个例子当中看清楚这一点：

>>> for part in msg.walk():
...     print(part.get_content_maintype() == 'multipart'),
...           part.is_multipart())
True True
False False
False True
False False
False False
False True
False False
>>> _structure(msg)
multipart/report
    text/plain
message/delivery-status
    text/plain
    text/plain
message/rfc822
    text/plain

在这里， message 的部分并非 multiparts ，但是它们真的包含子部分！ is_multipart() 返回 True ， walk 也深入进这些子部分中。

Message objects can also optionally contain two instance attributes, which can be used when generating the plain text of a MIME message.

preamble

MIME 文档格式在标头之后的空白行以及第一个多部分的分界字符串之间允许添加一些文本， 通常，此文本在支持 MIME 的邮件阅读器中永远不可见，因为它处在标准 MIME 防护范围之外。 但是，当查看消息的原始文本，或当在不支持 MIME 的阅读器中查看消息时，此文本会变得可见。

preamble 属性包含 MIME 文档开头部分的这些处于保护范围之外的文本。 当 Parser 在标头之后及第一个分界字符串之前发现一些文本时，它会将这些文本赋值给消息的 preamble 属性。 当 Generator 写出 MIME 消息的纯文本表示形式时，如果它发现消息具有 preamble 属性，它将在标头及第一个分界之间区域写出这些文本。 请参阅 email.parser 和 email.generator 了解更多细节。

请注意如果消息对象没有前导文本，则 preamble 属性将为 None。

epilogue

The epilogue attribute acts the same way as the preamble attribute, except that it contains text that appears between the last boundary and the end of the message.

You do not need to set the epilogue to the empty string in order for the Generator to print a newline at the end of the file.

defects

defects 属性包含在解析消息时发现的所有问题的列表。 请参阅 email.errors 了解可能的解析缺陷的详细描述。