email.message ：表示电子邮件

源代码： Lib/email/message.py

3.6 新版功能: 1

中央阶级 email 包是 EmailMessage 类，从导入 email.message 模块。它是 email 对象模型。 EmailMessage 提供用于设置和查询头字段、访问消息正文以及创建或修改结构化消息的核心功能。

电子邮件包含 headers 和A payload （也称为 内容 ）报头是 RFC 5322 或 RFC 6532 样式字段名和值，其中字段名和值用冒号分隔。冒号不是字段名或字段值的一部分。有效负载可以是简单的文本消息，或者二进制对象，或者子消息的结构化序列，每个子消息都有自己的头集和自己的有效负载。后一种类型的有效负载由具有mime类型的消息指示，例如 multipart/* 或 message/rfc822 .

概念模型由 EmailMessage 对象是与 payload 代表了 RFC 5322 消息正文，可能是子“emailmessage”对象的列表。除了用于访问头名称和值的常规字典方法外，还有用于访问头中的专用信息（例如mime内容类型）、在有效负载上操作、生成消息的序列化版本以及递归遍历对象树的方法。

这个 EmailMessage 类字典的接口由头名称索引，头名称必须是ASCII值。字典的值是带有一些额外方法的字符串。头以大小写保留形式存储和返回，但字段名不区分大小写匹配。与真正的dict不同的是，对键有一个排序，并且可以有重复的键。提供了用于处理具有重复键的头的其他方法。

这个 payload 是字符串或字节对象（对于简单消息对象）或 EmailMessage 对象，用于mime容器文档，例如 multipart/* 和 message/rfc822 消息对象。

class email.message.EmailMessage(policy=default)

如果 policy 指定使用它指定的规则更新和序列化消息的表示形式。如果 policy 未设置，请使用 default 策略，遵循电子邮件RFC的规则，行尾除外（而不是强制的RFC \r\n ，它使用了python标准 \n 行尾）。有关更多信息，请参阅 policy 文档。

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

返回整个扁平化为字符串的消息。当可选时 unixfrom 为真，信封头包含在返回的字符串中。 unixfrom 默认为 False . 为了与基础的向后兼容性 Message 类 麦克海德伦 接受，但默认为 None ，这意味着默认情况下，行长度由 max_line_length 政策。这个 policy 参数可用于重写从消息实例获取的默认策略。由于指定了 policy 将传递给 Generator .

扁平化消息可能会触发对 EmailMessage 如果需要填写默认值以完成到字符串的转换（例如，可以生成或修改mime边界）。

请注意，此方法是为了方便起见而提供的，可能不是在应用程序中序列化消息的最有用方法，特别是在处理多个消息时。见 email.generator.Generator 更灵活的消息序列化API。还请注意，此方法仅限于在以下情况下生成序列化为“7位清理”的消息： utf8 是 False ，这是默认值。

在 3.6 版更改: 默认行为 麦克海德伦 未指定已从默认值更改为0，默认值更改为 max_line_length 从政策上。

__str__()

相当于 as_string(policy=self.policy.clone(utf8=True)) . 允许 str(msg) 以可读格式生成包含序列化消息的字符串。

在 3.4 版更改: 方法已更改为使用 utf8=True 从而产生 RFC 6531 -类似于消息表示，而不是作为 as_string() .

as_bytes(unixfrom=False, policy=None)

返回整个扁平化为字节对象的消息。可选时 unixfrom 为真，信封头包含在返回的字符串中。 unixfrom 默认为 False . 这个 policy 参数可用于重写从消息实例获取的默认策略。由于指定了 policy 将传递给 BytesGenerator .

扁平化消息可能会触发对 EmailMessage 如果需要填写默认值以完成到字符串的转换（例如，可以生成或修改mime边界）。

请注意，此方法是为了方便起见而提供的，可能不是在应用程序中序列化消息的最有用方法，特别是在处理多个消息时。见 email.generator.BytesGenerator 更灵活的消息序列化API。

__bytes__()

相当于 as_bytes() . 允许 bytes(msg) 生成包含序列化消息的bytes对象。

is_multipart()

返回 True 如果消息的有效负载是SUB的列表-EmailMessage 对象，否则返回 False .什么时候？ is_multipart() 返回 False ，有效负载应该是字符串对象（可能是CTE编码的二进制有效负载）。注意 is_multipart() 返回 True 不一定意味着“msg.get_content_maintype（）=‘multipart’”将返回 True . 例如， is_multipart 将返回 True 当 EmailMessage 属于类型 message/rfc822 .

set_unixfrom(unixfrom)

将邮件的信封头设置为 unixfrom ，应为字符串。（见 mboxMessage 有关此标题的简要说明。）

get_unixfrom()

返回邮件的信封头。默认为 None 如果没有设置信封头。

以下方法实现了用于访问消息头的类似映射的接口。请注意，这些方法和普通映射（即字典）接口之间存在一些语义差异。例如，在字典中没有重复的键，但这里可能有重复的消息头。此外，在字典中，对于 keys() ，但在一个 EmailMessage 对象，头总是按它们在原始消息中出现的顺序返回，或者在以后将它们添加到消息中。删除然后重新添加的任何标题都将始终附加到标题列表的末尾。

这些语义差异是有意的，在最常见的用例中倾向于方便性。

注意，在所有情况下，消息中出现的任何信封头都不包含在映射接口中。

__len__()

返回头的总数，包括重复项。

__contains__(name)

返回 True 如果消息对象有一个名为 name . 匹配是在不考虑案例和 name 不包括尾随结肠。用于 in 操作员。例如：：

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

返回命名头字段的值。 name 不包括冒号字段分隔符。如果缺少标题， None 返回；A KeyError 从未被引发。

请注意，如果命名字段在消息头中出现多次，那么将返回哪些字段值是未定义的。使用 get_all() 方法获取名为 name .

使用标准（非``compat32``）策略，返回的值是 email.headerregistry.BaseHeader .

__setitem__(name, val)

在邮件中添加域名 name 价值 val . 该字段将附加到消息现有头的末尾。

注意这是 not 覆盖或删除具有相同名称的任何现有标题。如果要确保新头是具有字段名的消息中唯一存在的头 name ，首先删除字段，例如：

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

如果 policy 将某些头定义为唯一的（与标准策略一样），此方法可能会引发 ValueError 当试图给已经存在的头赋值时。为了一致性，这种行为是有意的，但不要依赖于它，因为我们可能会选择让这样的分配在将来自动删除现有的头。

__delitem__(name)

删除名称为的所有字段 name 从邮件头。如果头中不存在命名字段，则不会引发异常。

keys()

返回所有邮件头字段名的列表。

values()

返回所有消息字段值的列表。

items()

返回包含所有消息字段头和值的2个元组的列表。

get(name, failobj=None)

返回命名头字段的值。这和 __getitem__() 除了那个可选的 故障对象 如果缺少命名头，则返回（ 故障对象 默认为 None ）

以下是一些与头相关的其他有用方法：

get_all(name, failobj=None)

返回名为的字段的所有值的列表 name . 如果消息中没有这样的命名头， 故障对象 返回（默认为 None ）

add_header(_name, _value, **_params)

扩展头段设置。这种方法类似于 __setitem__() 除了可以将其他头参数作为关键字参数提供。 _name 是要添加的标题字段，并且 _value 是 初级的 标题的值。

对于关键字参数字典中的每个项 _params ，键作为参数名，下划线转换为破折号（因为破折号在Python标识符中是非法的）。通常，参数将添加为 key="value" 除非值是 None ，在这种情况下，只添加密钥。

如果该值包含非ASCII字符，则可以通过将该值指定为格式中的三元组来显式控制字符集和语言。 (CHARSET, LANGUAGE, VALUE) 在哪里 CHARSET 是一个字符串，命名用于对值进行编码的字符集， LANGUAGE 通常可以设置为 None 或空字符串（请参见 RFC 2231 其他可能性），以及 VALUE 是包含非ASCII码位的字符串值。如果未传递三元组，且值包含非ASCII字符，则会自动将其编码为 RFC 2231 格式使用 CHARSET 属于 utf-8 和A LANGUAGE 属于 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'))
replace_header(_name, _value)

更换收割台。替换在消息中找到的第一个匹配头 _name ，保留原始标题的标题顺序和字段名称大小写。如果找不到匹配的头，则引发 KeyError .

get_content_type()

返回消息的内容类型，强制为窗体的小写 maintype/subtype . 如果没有 Content-Type 消息头返回返回的值 get_default_type() . 如果 Content-Type 头无效，返回 text/plain .

（根据 RFC 2045 ，消息始终具有默认类型， get_content_type() 将始终返回值。 RFC 2045 将消息的默认类型定义为 text/plain 除非它出现在 multipart/digest 容器，在这种情况下 message/rfc822 . 如果 Content-Type 头的类型规范无效， RFC 2045 要求默认类型为 text/plain ）

get_content_maintype()

返回消息的主要内容类型。这就是 maintype 返回的字符串的一部分 get_content_type() .

get_content_subtype()

返回消息的子内容类型。这就是 subtype 返回的字符串的一部分 get_content_type() .

get_default_type()

返回默认内容类型。大多数邮件的默认内容类型为 text/plain ，但属于以下子部分的邮件除外 multipart/digest 容器。此类子部分的默认内容类型为 message/rfc822 .

set_default_type(ctype)

设置默认内容类型。 C型 应该是 text/plain 或 message/rfc822 尽管这不是强制执行的。默认内容类型不存储在 Content-Type 头，因此它只影响 get_content_type 方法时不 Content-Type 消息中存在标题。

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

在中设置参数 Content-Type 标题。如果参数已存在于头中，则将其值替换为 value . 什么时候？ *header*是 Content-Type （默认值）并且消息中还不存在该头，请添加该头，并将其值设置为 text/plain ，并附加新的参数值。可选的 *header*指定的可选标题 Content-Type .

如果值包含非ASCII字符，则可以使用可选的 charset 和 语言 参数。可选的 语言 指定 RFC 2231 语言，默认为空字符串。两个 charset 和 语言 应该是字符串。默认值是使用 utf8 charset 和 None 对于 语言 .

如果 代替 是 False （默认设置）标题将移动到标题列表的末尾。如果 代替 是 True ，标题将就地更新。

使用 请求 参数与 EmailMessage 对象已弃用。

请注意，可以通过 params 头值的属性（例如， msg['Content-Type'].params['charset'] ）

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

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

从中完全删除给定参数 Content-Type 标题。头将在没有参数或其值的情况下重新写入。可选的 *header*指定替代 Content-Type .

使用 请求 参数与 EmailMessage 对象已弃用。

get_filename(failobj=None)

返回的值 filename 的参数 Content-Disposition 消息的标题。如果标题没有 filename 参数，此方法返回到查找 name 上的参数 Content-Type 标题。如果两者都找不到，或者头丢失，则 故障对象 返回。返回的字符串将始终按照 email.utils.unquote() .

get_boundary(failobj=None)

返回的值 boundary 的参数 Content-Type 消息头，或 故障对象 如果头丢失或没有 boundary 参数。返回的字符串将始终按照 email.utils.unquote() .

set_boundary(boundary)

设置 boundary 的参数 Content-Type 报头到 边界 . set_boundary() 将始终引用 边界 如有必要。一 HeaderParseError 如果消息对象没有 Content-Type 标题。

请注意，使用此方法与删除旧的 Content-Type 标题并通过添加新边界的新标题 add_header() ，因为 set_boundary() 保留 Content-Type 标题列表中的标题。

get_content_charset(failobj=None)

返回 charset 的参数 Content-Type 头，强制降低大小写。如果没有 Content-Type 头，或者如果头没有 charset 参数， 故障对象 返回。

get_charsets(failobj=None)

返回包含消息中字符集名称的列表。如果消息是 multipart ，则该列表将为有效载荷中的每个子部分包含一个元素，否则，它将是长度为1的列表。

列表中的每个项都将是一个字符串，该字符串是 charset 中的参数 Content-Type 所代表子部分的标题。如果本子部分没有 Content-Type 页眉，没有 charset 参数，或不是 text 主mime类型，则返回列表中的该项将 故障对象 .

is_attachment()

返回 True 如果有 Content-Disposition 头及其（不区分大小写）值为 attachment ， False 否则。

在 3.4.2 版更改: 为了与 is_multipart() .

get_content_disposition()

返回消息的低基值（不带参数） Content-Disposition 头（如果有），或 None . 此方法的可能值为 内联的 ， 附件 或 None 如果信息如下 RFC 2183 .

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 调试助手函数：

>>> from email.iterators import _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 下降到子部分。

get_body(preferencelist=('related', 'html', 'plain'))

返回作为消息“正文”的最佳候选的mime部分。

优先主义者 必须是集合中的字符串序列 related ， html 和 plain ，并指示返回部件的内容类型的首选顺序。

开始查找与在其上 get_body 方法被调用。

如果 related 不包括在 优先主义者 ，如果（子）部分与首选项匹配，则将遇到的任何相关项的根部分（或根部分的子部分）视为候选项。

当遇到 multipart/related 检查 start 参数和是否匹配零件 Content-ID 找到，仅在查找候选匹配项时考虑它。否则只考虑 multipart/related .

如果一部分有 Content-Disposition 头，仅当头的值为 inline .

如果没有任何候选人符合 优先主义者 返回 None .

注：（1）对于大多数应用，只有 优先主义者 真正有意义的组合是 ('plain',) ， ('html', 'plain') 和默认值 ('related', 'html', 'plain') . （2）因为匹配从对象开始 get_body 被调用，调用 get_body 在一 multipart/related 将返回对象本身，除非 优先主义者 具有非默认值。（3）未指定 Content-Type 或者谁的 Content-Type 头无效将被视为其类型 text/plain 可能偶尔导致 get_body 返回意外结果。

iter_attachments()

返回一个迭代器，覆盖消息中所有非候选“body”部分的直接子部分。也就是说，跳过 text/plain ， text/html ， multipart/related 或 multipart/alternative （除非通过 Content-Disposition: attachment ）并返回所有剩余零件。当直接应用于 multipart/related ，返回除根部分以外的所有相关部分的迭代器（即：由 start 参数，如果没有 start 参数或 start 参数与 Content-ID 任何部分）。当直接应用于 multipart/alternative 或者非“multipart”，返回空迭代器。

iter_parts()

对消息的所有直接子部分返回迭代器，对于非“multipart”将为空。（也见） walk() ）

get_content(*args, content_manager=None, **kw)

调用给 get_content() 方法 content_manager ，将self作为消息对象传递，并将任何其他参数或关键字作为附加参数传递。如果 content_manager 未指定，请使用 content_manager 由电流指定 policy .

set_content(*args, content_manager=None, **kw)

调用给 set_content() 方法 content_manager ，将self作为消息对象传递，并将任何其他参数或关键字作为附加参数传递。如果 content_manager 未指定，请使用 content_manager 由电流指定 policy .

将非“multipart”消息转换为 multipart/related 消息，移动任何现有的 Content- 收割台和有效载荷转换为 multipart . 如果 边界 如果已指定，请将其用作多部分中的边界字符串，否则在需要时（例如，当消息序列化时）保留自动创建的边界。

make_alternative(boundary=None)

转换非“multipart”或 multipart/related 变成一个 multipart/alternative ，移动任何现有 Content- 收割台和有效载荷转换为 multipart . 如果 边界 如果已指定，请将其用作多部分中的边界字符串，否则在需要时（例如，当消息序列化时）保留自动创建的边界。

make_mixed(boundary=None)

转换非“multipart”的 multipart/related ，或者 multipart-alternative 变成一个 multipart/mixed ，移动任何现有 Content- 收割台和有效载荷转换为 multipart . 如果 边界 如果已指定，请将其用作多部分中的边界字符串，否则在需要时（例如，当消息序列化时）保留自动创建的边界。

如果消息是 multipart/related ，创建新的消息对象，将所有参数传递给 set_content() 方法，以及 attach() 它给 multipart . 如果消息是非“multipart”，请调用 make_related() 然后按上述步骤进行。如果消息是任何其他类型的 multipart 举起一个 TypeError .如果 content_manager 未指定，请使用 content_manager 由电流指定 policy . 如果添加的零件没有 Content-Disposition 标题，添加一个值 inline .

add_alternative(*args, content_manager=None, **kw)

如果消息是 multipart/alternative ，创建新的消息对象，将所有参数传递给 set_content() 方法，以及 attach() 它给 multipart . 如果消息是非“multipart”或 multipart/related ，调用 make_alternative() 然后按上述步骤进行。如果消息是任何其他类型的 multipart 举起一个 TypeError .如果 content_manager 未指定，请使用 content_manager 由电流指定 policy .

add_attachment(*args, content_manager=None, **kw)

如果消息是 multipart/mixed ，创建新的消息对象，将所有参数传递给 set_content() 方法，以及 attach() 它给 multipart . 如果消息是非“multipart”， multipart/related 或 multipart/alternative ，调用 make_mixed() 然后按上述步骤进行。如果 content_manager 未指定，请使用 content_manager 由电流指定 policy .如果添加的零件没有 Content-Disposition 标题，添加一个值 attachment . 此方法可同时用于显式附件 (Content-Disposition: attachment ） inline 附件 (Content-Disposition: inline ，通过将适当的选项传递给 content_manager .

clear()

卸下有效负载和所有收割台。

clear_content()

移除有效负载和所有 Content- 头，保留所有其他头的完整性和原始顺序。

EmailMessage 对象具有以下实例属性：

preamble

MIME文档的格式允许在标题后面的空白行和第一个多部分边界字符串之间有一些文本。通常，此文本在支持mime的邮件阅读器中是不可见的，因为它不属于标准mime保护层。但是，在查看消息的原始文本时，或者在不支持mime的读卡器中查看消息时，可以看到此文本。

这个 序言 属性包含用于mime文档的这种前导的额外护甲文本。当 Parser 在头之后但在第一个边界字符串之前发现一些文本，它将此文本分配给消息的 序言 属性。当 Generator 正在写出一个mime消息的纯文本表示，它发现该消息具有 序言 属性，它将在标题和第一个边界之间的区域中写入此文本。见 email.parser 和 email.generator 有关详细信息。

请注意，如果message对象没有前导码，则 序言 属性将为 None .

epilogue

这个 后记 属性的作用方式与 序言 属性，但它包含出现在最后一个边界和消息结尾之间的文本。如同 preamble ，如果没有epilog文本，则此属性将 None .

defects

这个 缺陷 属性包含分析此消息时发现的所有问题的列表。见 email.errors 有关可能的分析缺陷的详细描述。

class email.message.MIMEPart(policy=default)

此类表示mime消息的子部分。它与 EmailMessage 但是没有 MIME-Version 当 set_content() 因为子部件不需要它们自己的 MIME-Version 标题。

脚注

1

最初在3.4中作为 provisional module . 旧邮件类的文档已移动到 email.message.Message ：表示使用 compat32 API .