email.message：代表电子邮件

源代码： Lib / email / message.py

email包中的中心类是EmailMessage类，从email.message模块。它是email对象模型的基类。EmailMessage提供了设置和查询标题字段，访问消息体，创建或修改结构化消息的核心功能.

电子邮件由headers和payload（也称为content）。标题是 RFC 5322 或 RFC 6532 样式字段名称和值，其中字段名称和值由冒号分隔。冒号不是字段名称或字段值的一部分。有效载荷可以是简单的文本消息，或二进制对象，或子消息的结构化序列，每个子消息具有它们自己的标题集和它们自己的有效载荷。有效负载的类型由具有MIME类型的消息表示，例如multipart/*或message/rfc822.

EmailMessage对象提供的概念模型是带有payload的标题的无序字典，代表 RFC 5322 消息的正文，可能是一个子列表EmailMessage对象。除了用于访问headernames和值的常规字典方法之外，还有用于从头部访问专用信息的方法（例如MIME内容类型），用于在有效载荷上操作，用于生成消息的序列化版本以及递归地走过对象树

EmailMessage类似字典的接口由headernames索引，它必须是ASCII值。字典的值是带有一些额外方法的字符串。标头以case-preservingform形式存储和返回，但字段名称不区分大小写。与真正的字典不同，键有一个排序，可能有重复的键。提供了额外的方法来处理具有重复键的标题.

payload是一个字符串或字节对象，在简单的messageobjects的情况下，或者是EmailMessage对象，用于MIME容器文档，如multipart/*和message/rfc822消息对象.

class email.message.EmailMessage（policy=default）

如果指定了policy，请使用它指定的规则来更新和序列化消息的表示。如果没有设置policy，请使用default策略，遵循emailRFCs的规则，除了行结尾（而不是RFC强制\r\n，它使用Python标准\n行结尾）。有关更多信息，请参阅policydocumentation.

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

把整个信息整理成一个字符串。当可选unixfrom为true时，包络头包含在返回的字符串中。unixfrom默认为False。为了向后兼容基地Message class maxheaderlen isaccepted，但默认为None，这意味着默认情况下，linelength由策略的max_line_length控制。该policy参数可用于覆盖从消息实例获取的默认策略。这可以用来控制方法产生的一些格式，因为指定的policy将被带到Generator.

展平消息可能会触发对EmailMessage如果需要填写默认值以完成到astring的转换（例如，可以生成或修改MIME边界）.

请注意，此方法是为方便起见而提供的，可能不是在应用程序中序列化消息的最有用方法，尤其是在处理多个消息时。看到email.generator.Generator用于更灵活的API forserializing消息。另请注意，当utf8是False时，此方法被限制产生序列化为“7位清除”的消息，这是默认值.

版本3.6更改：未指定maxheaderlen时的默认行为从默认更改为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为true时，包络头包含在返回的字符串中。unixfrom默认为False。policy参数可以用来覆盖从消息实例中获取的默认策略。这可以用来控制由方法生成的一些格式，因为指定的policy将被传递给BytesGenerator.

展平消息可能会触发对EmailMessage的更改，如果需要填写默认值以完成转换为astring（例如，可能生成或修改MIME边界）.

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

__bytes__ ()

等于as_bytes()。允许bytes(msg)生成包含序列化信息的abytes对象.

is_multipart ()

返回True如果消息的有效载荷是子列表EmailMessage对象，否则返回False。当is_multipart()返回False，有效载荷应该是一个stringobject（可能是CTE编码的二进制有效载荷）。注意is_multipart()返回True并不一定意味着“msg.get_content_maintype（）==’multipart’”将返回True。例如， is_multipart将返回 True当。。。的时候EmailMessage是message/rfc822.

set_unixfrom（unixfrom）

将邮件的信封标题设置为unixfrom，该标题应为astring。（有关此标题的简要说明，请参见mboxMessage。）

get_unixfrom（）

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

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

这些语义差异是有意的，在最常见的使用案例中偏向于方便.

请注意，在所有情况下，消息中存在的任何信封标题都不包含在映射界面中.

__len__ ()

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

__contains__（name）

如果消息对象具有名为name的字段，则返回true。匹配是没有考虑的情况和name不包括尾随。用于in运算符。例如：

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

__getitem__（name）

返回指定标题字段的值。name不包括colon字段分隔符。如果缺少标题，则返回None;a KeyError永远不会被抬起来

请注意，如果命名字段在消息的标题中出现多次，则将确定将返回哪些字段值。使用 get_all()获取所有名为name.

的现有头的值的方法使用标准（非compat32）策略，返回的值是email.headerregistry.BaseHeader.

__setitem__的子类的实例（name, val）

使用字段名称name和值val为邮件添加标题。该字段附加到邮件现有标题的末尾.

注意这是not覆盖或删除任何具有相同名称的现有标头。如果你想确保新标题是featuressage中唯一一个字段名为name的标题，请首先删除该字段，例如：

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

如果policy定义了某些标题为了是唯一的（如标准政策所做的那样），当一个已经存在的企图将一个值分配给这样的标题时，这个方法可能会引发一个ValueError。这个行为是为了一致性而故意，但不依赖于它，我们可以选择让这样的作业在将来自动删除现有的标题.

__delitem__ (name )

从消息的标题中删除名称为name的所有字段。如果在标题中没有指定的字段，则不会引发异常.

keys ()

返回所有消息标题字段名称的列表.

values（）

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

items ()

返回列表2元组包含所有消息的字段标题和值.

get (name, failobj=None )

返回指定标头字段的值。这与__getitem__()完全相同，只是如果缺少已知的标题，则返回可选的failobj（failobj默认为None).

这里是一些额外有用的标题相关方法：

get_all（name, failobj=None）

返回名为name的字段的所有值的列表。如果消息中没有这样的命名标题，则返回failobj（默认为None).

add_header(_name, _value, **_params)

扩展标题设置。此方法类似于__setitem__()，但可以将其他标头参数作为keywordarguments提供。_name是要添加的标题字段，_value是标题的primary值.

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

如果值包含非ASCII字符，则可以通过在格式(CHARSET, LANGUAGE, VALUE)中将值指定为三元组来明确控制字符集和语言，其中CHARSET是一个用于编码值的字符串，LANGUAGE通常可以设置为None或空字符串（参见 RFC 2231 for其他可能性）和VALUE是包含非ASCIIcode点的字符串值。如果没有传递三元组并且值包含非ASCII字符，它将自动编码在 RFC 2231 格式中使用CHARSET对utf-8和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 要求defaulttype为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）

设置默认内容类型。ctype应该是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和language明确指定字符集和语言参数。可选language指定 RFC 2231 语言，默认为空字符串。charset和language都应该是弦乐。默认是使用utf8 charset和None language.

如果replace是False（默认值）标题移动到标题列表的末尾。如果replace是True，那么会更新标题

//使用requote参数和EmailMessage对象已经过去了

注意标题的现有参数值可以通过标题值的params属性访问（例如msg["Content-Type"].params["charset"]).

更改版本3.4：replace关键字已添加.

del_param (param, header=”content-type”, requote=True）

从Content-Type标题中完全删除给定的参数。标题将在没有参数orits值的情况下重新编写。可选header指定Content-Type.

的替代方法requote参数与EmailMessage对象的使用isdeprecated.

get_filename(failobj=None）

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

get_boundary（failobj=None）

返回消息的boundary标题的Content-Type参数的值，或者failobj如果缺少标题，或者没有boundary参数。返回的字符串将始终不加引号email.utils.unquote().

set_boundary（boundary）

将boundary标题的Content-Type参数设置为boundary. set_boundary()如果有必要，总会引用boundary。一个 HeaderParseError如果themessage对象没有Content-Type header.

注意使用这种方法与删除旧的Content-Type标题并添加一个新的newbound通过add_header()，因为set_boundary()保留了页面中Content-Type标题的顺序

get_content_charset// (failobj=None)

返回charset Content-Type标题的参数，强制为小写。如果没有Content-Type标题，或者如果标题没有charset参数，则返回failobj.

get_charsets(failobj=None)

返回包含该字符的列表在邮件中设置名称。如果主题是multipart，然后列表将包含有效负载中每个子部分的一个元素，否则，它将是一个长度为1.的列表

列表中的每个项目都是一个字符串，它是charset所有子部分的Content-Type标题中的参数。如果子部分没有Content-Type标题，没有charset参数，或者不是textmainMIME类型，然后返回列表中的那个项目将是failobj.

is_attachment（）

返回True如果有Content-Disposition headerand它（不区分大小写）的值是attachment, False否则

版本3.4.2更改： is_attachment现在是一个方法而不是属性，与is_multipart().

get_content_disposition（）

一致返回小写值（没有参数）的消息Content-Disposition标题如果有一个，或None。该方法的可能值为inline, attachment或None如果消息如下 RFC 2183 .

版本3.5中的新内容

以下方法涉及询问和操纵信息的内容（有效载荷）.

walk (）

walk()method是一个通用的生成器，可用于对消息对象树的所有部分和子部分进行深思熟虑，即深度优先遍历顺序。你通常会使用walk()作为中的主人for环;每次迭代都会返回下一个子部分.

这是一个打印多部分消息结构的每个部分的MIME类型的示例：

>>> for part in msg.walk():...     print(part.get_content_type())multipart/reporttext/plainmessage/delivery-statustext/plaintext/plainmessage/rfc822text/plain

walk迭代is_multipart()返回True的任何部分的子部分，即使msg.get_content_maintype() == "multipart"可能会返回False。在我们的例子中我们可以通过使用_structure debughelper函数来看到这个：

>>> for part in msg.walk():...     print(part.get_content_maintype() == "multipart",...           part.is_multipart())True TrueFalse FalseFalse TrueFalse FalseFalse FalseFalse TrueFalse 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“))

返回作为themessage“body”的最佳候选者的MIME部分.

preferencelist必须是来自集合related,html和plain，并指示返回部分的内容类型的首选顺序.

开始寻找与get_body方法被调用的对象的候选匹配.

如果related不包含在preferencelist，如果（子）部分与首选项匹配，则考虑遇到的任何相关的根部（或根部分的子部分）.

遇到multipart/related，检查start参数，如果找到一个匹配Content-ID的部分，那么在寻找候选匹配时就更合适了。否则只考虑multipart/related.

如果一个部分有Content-Disposition标题，如果标题的值是inline.

，则只考虑候选匹配的部分如果没有一个候选符合preferencelist中的任何首选项，返回None.

注意：（1）对于大多数应用来说，唯一真正有意义的preferencelist组合是("plain",), ("html", "plain")和默认的("related", "html", "plain")。（2）因为匹配从调用get_body的对象开始，所以调用get_bodyona multipart/related将返回对象本身，除非preferencelist具有非默认值。（3）未指定的消息（或消息部分）Content-Type或者Content-Type标题无效将被视为类型为text/plain，这可能偶尔会导致get_body返回意外结果.

iter_attachments ( )

将迭代器返回到消息的所有直接子部分，这些子部分不是候选“正文”部分。也就是说，跳过text/plain, text/html, multipart/related或multipart/alternative（除非它们通过Content-Disposition: attachment明确标记为附件），并返回所有剩余部分。直接应用于multipart/related，在所有相关部分上返回一个迭代器，除了根部分（即：start参数，或第一部分，如果没有start参数或start参数与任何部分的Content-ID不匹配。当直接应用于multipart/alternative或anon – 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.

make_related（boundary=None）

转换非_multipart消息进入multipart/related消息，移动任何现有的Content-标题和有效负载进入multipart。如果boundary指定，useit作为multipart中的边界字符串，否则在需要时自动创建边界（例如，当themessage被序列化时）.

make_alternative（boundary=None）

转换非_multipart或者multipart/related进入multipart/alternative，移动任何现有的Content-标题和有效负载进入multipart。如果boundary指定时，将其用作multipart中的边界字符串，否则在需要时自动创建边界（例如，当序列化消息时）.

make_mixed（boundary=None）

将非multipart，multipart/related或multipart-alternative转换为multipart/mixed，将任何现有的Content-标题和有效负载转换为（新）multipart的第一部分。如果boundary指定时，将其用作multipart中的边界字符串，否则在需要时自动创建边界（例如，当序列化消息时）.

add_related（*args, content_manager=None, **kw）

如果消息是multipart/related，创建一个新的messageobject，将所有参数传递给它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。如果featuressage是非_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。如果themessage是非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识别阅读器中查看邮件时，此文本可以变为可见.

preamble属性包含此主要的额外装甲文本MIMEdocuments。当Parser在标题之后但在第一个边界字符串之前发现一些文本时，它会将此文本分配给消息的preamble属性。当Generator写出MIME消息的纯文本表示，并且它发现themessage具有preamble属性时，它会将这个文本写在标题和第一个边界之间。详见email.parser和email.generator .

请注意，如果消息对象没有序言，preamble属性将是None.

epilogue

epilogueattribute的行为方式与preamble属性相同，只是它包含出现在最后一个边界和消息末尾之间的文本。和preamble，如果没有epilog文本，该属性将是None.

defects

defects属性包含解析此消息时发现的所有问题的列表。见email.errors有关可能的解析缺陷的详细说明.

class email.message.MIMEPart（policy=default）

此类表示MIME消息的子部分。它与EmailMessage，除了没有MIME-Version调用set_content()时添加标题，因为子部分不需要自己的MIME-Version标题

Footnotes