email.message: Representing an email message

email包中的中心类是Message从email.message模块导入的类。它是email对象模型的基类。Message提供了设置和查询标题字段以及访问消息体的核心功能。

从概念上讲，一个Message对象由标题和有效载荷组成。标题是RFC 2822风格的字段名称和值，其中字段名称和值由冒号分隔。冒号不是字段名称或字段值的一部分。

标题以保存案例的形式存储和返回，但不区分大小写。也可能有一个信封头，也称为Unix-From头或From_头。负载是简单消息对象的字符串或MessageMIME容器文档的对象列表（例如multipart / *和message / rfc822）。

Message对象提供一个用于访问消息头的映射样式接口，以及一个用于访问头和净荷的显式接口。它为生成消息对象树的平面文本表示，访问常用头参数以及递归遍历对象树提供了便利的方法。

这里是这个Message类的方法：

class email.message.Message

构造函数不带任何参数。

as_string([unixfrom])

将整个消息以字符串的形式展平。当可选的unixfrom是True，信封头包含在返回的字符串中。unixfrom默认为False。Message如果需要填充默认值以完成对字符串的转换（例如，可能会生成或修改MIME边界），则消除该消息可能会触发更改。

请注意，此方法是为了方便而提供的，可能并不总是按照您想要的方式格式化消息。例如，默认情况下，它会破坏以其开头的行From。为了更灵活，实例化一个Generator实例并flatten()直接使用它的方法。例如：

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

__str__()

相当于as_string(unixfrom=True)。

is_multipart()

返回True如果消息的有效载荷子的列表Message对象，否则返回False。当is_multipart()返回False时，有效载荷应该是一个字符串对象。

set_unixfrom(unixfrom)

将消息的信封头设置为unixfrom，它应该是一个字符串。

get_unixfrom()

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

attach(payload)

将给定的有效负载添加到当前有效负载，该有效负载必须是调用前的对象None列表Message。调用之后，有效负载将始终是Message对象列表。如果你想将有效负载设置为标量对象（例如字符串），请set_payload()改为使用。

get_payload([i[, decode]])

返回当前的有效载荷，这将是一个列表Message，当对象is_multipart()是True时，或者一个字符串is_multipart()是False。如果有效载荷是一个列表，并且您改变了列表对象，那么您可以修改消息的有效载荷。

使用可选参数i，get_payload()将返回有效负载的第i个元素，如果is_multipart()是从零开始计数True。一个IndexError如果将提高我是大于或等于在所述有效载荷的项目数小于0或。如果有效负载是一个字符串（即is_multipart()是False）并且我给出，一个TypeError上升。

根据Content-Transfer-Encoding标头，可选解码是指示是否应解码有效载荷的标志。当和消息不是多部分时，如果该头部的值为或，则有效载荷将被解码。如果使用其他编码，或Content-Transfer-Encoding标头丢失，或者有效负载具有伪造的base64数据，则有效负载将按原样返回（未解码）。如果消息是多部分并且解码标记是，则返回。解码的默认值是。Truequoted-printablebase64TrueNoneFalse

set_payload(payload[, charset])

将整个消息对象的有效载荷设置为有效载荷。确保有效载荷不变量是客户的责任。可选字符集设置消息的默认字符集; set_charset()详情请参阅。

在版本2.2.2中更改：添加了charset参数。

set_charset(charset)

将有效负载的字符集设置为charset，它可以是Charset实例（请参阅email.charset），命名字符集的字符串或None。如果它是一个字符串，它将被转换为一个Charset实例。如果charset是None，则该charset参数将从Content-Type头中删除（该消息不会被修改）。其他任何东西都会生成一个TypeError。

如果没有现有的MIME-Version标头，则会添加一个。如果没有现有的Content-Type标头，则会添加一个值为text / plain的值。Content-Type头是否已经存在，其charset参数将被设置为charset.output_charset。如果charset.input_charset和charset.output_charset不同，负载将被重新编码到output_charset。如果没有现有的Content-Transfer-Encoding头部，则有效载荷将在需要时使用指定的进行传输编码Charset，并且将添加具有适当值的头部。如果一个Content-Transfer-Encoding头已经存在，假定已经使用该Content-Transfer-Encoding正确地编码了有效载荷，并且没有被修改。

该消息将被假定为text / *类型，有效负载可以是unicode或使用charset.input_charset编码。当生成消息的纯文本表示时，它将被编码或转换为charset.output_charset并在需要时正确传输编码。将根据需要添加MIME头（MIME版本，内容类型，内容传输编码）。

2.2.2版中的新功能。

get_charset()

返回Charset与消息有效负载相关的实例。

2.2.2版中的新功能。

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

这些语义差异是有意的，并且偏向于最大的方便。

Note that in all cases, any envelope header present in the message is not included in the mapping interface.

__len__()

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

__contains__(name)

如果消息对象具有名为name的字段，则返回true 。匹配不区分大小写，名称不应包含尾部冒号。用于in操作员，例如：

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

__getitem__(name)

返回指定标题字段的值。名称不应包含冒号字段分隔符。如果标题丢失，None则返回; a KeyError永远不会升起。

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

__setitem__(name, val)

将字段添加到带有字段名称和值val的消息中。该字段附加到消息现有字段的末尾。

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

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

__delitem__(name)

从消息的标题中删除所有出现的具有名称名称的字段。如果名称字段不存在于标题中，则不会引发异常。

has_key(name)

如果消息包含名为name的头字段，则返回true，否则返回false。

keys()

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

values()

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

items()

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

get(name[, failobj])

返回指定标题字段的值。这与__getitem__()除了如果命名标题丢失（缺省为）时返回可选failobj相同None。

以下是一些其他有用的方法：

get_all(name[, failobj])

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

add_header(_name, _value, **_params)

扩展标题设置。__setitem__()除了可以提供额外的头部参数作为关键字参数之外，此方法类似。_name是要添加的标题字段，而_value是标题的主要值。

对于关键字参数字典_params中的每个项目，都将该关键字作为参数名称，并将下划线转换为破折号（因为破折号在Python标识符中是非法的）。通常，该参数将被添加，key="value"除非该值为None，在这种情况下，只有该键将被添加。如果该值包含非ASCII字符，则必须将其指定为格式中的三元组(CHARSET, LANGUAGE, VALUE)，其中CHARSET是指定用于对值进行编码的字符集的字符串，LANGUAGE通常可以设置为None空字符串（请参阅RFC 2231 for其他可能性），并且VALUE是包含非ASCII码点的字符串值。

这是一个例子：

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)

替换标题。替换消息中找到的与_name匹配的第一个标头，保留标头顺序和字段名称大小写。如果找不到匹配的标题，KeyError则会引发。

2.2.2版中的新功能。

get_content_type()

返回消息的内容类型。将返回的字符串强制为maintype / subtype形式的小写字母。如果消息中没有Content-Type头，则get_default_type()返回给定的默认类型。由于根据RFC 2045，消息始终有一个默认类型，get_content_type()将始终返回一个值。

RFC 2045将消息的默认类型定义为 text / plain，除非它出现在 multipart / digest容器中，在这种情况下，它将是 message / rfc822。如果 Content-Type头的类型规范无效，则 RFC 2045要求默认类型为 text / plain。

2.2.2版中的新功能。

get_content_maintype()

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

2.2.2版中的新功能。

get_content_subtype()

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

2.2.2版中的新功能。

get_default_type()

返回默认的内容类型。除了作为多部分/摘要容器的子部分的消息之外，大多数消息具有默认的文本/纯文本内容类型。这样的子部分有一个默认的内容类型的消息/ rfc822。

2.2.2版中的新功能。

set_default_type(ctype)

设置默认的内容类型。ctype应该是text / plain或message / rfc822，尽管这不是强制执行的。默认内容类型不存储在Content-Type标头中。

2.2.2版中的新功能。

get_params([failobj[, header[, unquote]]])

以列表形式返回消息的Content-Type参数。返回列表的元素是键/值对的2元组，在'='符号上分割。左侧'='是键，右侧是值。如果'='参数中没有任何符号，则值为空字符串，否则该值get_param()如上所述，如果可选unquote为True（默认值），则为未引用。

如果没有Content-Type标头，可选的failobj是要返回的对象。可选标题是要搜索的标题而不是Content-Type。

改变在2.2.2版本：引文结束参数添加。

get_param(param[, failobj[, header[, unquote]]])

以字符串形式返回Content-Type头的参数param的值。如果消息没有Content-Type头或者没有这样的参数，则返回failobj（默认为None）。

可选标题（如果给出）指定要使用的消息标题而不是Content-Type。

参数键始终不区分大小写。返回值可以是字符串，也可以是参数为RFC 2231编码的3元组。当它是一个三元组时，值的元素就是这种形式(CHARSET, LANGUAGE, VALUE)。请注意这两个CHARSET和LANGUAGE可能None，在这种情况下，你应该考虑VALUE在被编码us-ascii字符集。你通常可以忽略LANGUAGE。

如果您的应用程序不关心参数是否按RFC 2231编码，则可以通过调用email.utils.collapse_rfc2231_value()传入返回值来折叠参数值get_param()。当值是一个元组时，这将返回一个适当解码的Unicode字符串，或者如果原始字符串不是，则返回原始字符串。例如：

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

在任何情况下，VALUE除非设置unquote，否则参数值（返回的字符串或3元组中的项目）始终未加引号False。

在版本2.2.2中进行了更改：添加了unquote参数，以及可能的三元组返回值。

set_param(param, value[, header[, requote[, charset[, language]]]])

在Content-Type标题中设置一个参数。如果参数已经存在于标题中，它的值将被替换为值。如果尚未为此消息定义Content-Type头，则它将被设置为text / plain，并且新参数值将按照RFC 2045进行追加。

可选标题指定Content-Type的替代标题，除非可选的重新标记为False（默认为True），否则将根据需要引用所有参数。

如果指定了可选字符集，则参数将根据RFC 2231进行编码。可选语言指定RFC 2231语言，默认为空字符串。这两个字符集和语言应弦。

2.2.2版中的新功能。

del_param(param[, header[, requote]])

从Content-Type标题中完全删除给定的参数。标题将在没有参数或其值的情况下被重写。除非所有的值将被引用作为必要重新报价为False（默认为True）。可选标题指定Content-Type的替代方案。

2.2.2版中的新功能。

set_type(type[, header][, requote])

设置Content-Type标题的主类型和子类型。类型必须是maintype / subtype形式的字符串，否则ValueError会引发。

此方法替换Content-Type标头，保留所有参数。如果重新编号是，则会保留False现有标题的引用，否则参数将被引用（默认值）。

可以在标题参数中指定一个替代标头。当Content-Type头被设置时，还添加了MIME-Version头。

2.2.2版中的新功能。

get_filename([failobj])

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

get_boundary([failobj])

返回消息boundary的Content-Type头的参数值，或者如果头丢失或没有参数，则返回failobjboundary。返回的字符串将始终不加引号email.utils.unquote()。

set_boundary(boundary)

将Content-Type标头的boundary参数设置为边界。将在必要时总是引用边界。如果消息对象没有Content-Type头部，则引发A.set_boundary()HeaderParseError

请注意，使用这种方法比删除旧的稍微不同的内容类型头并添加一个新通过的新的边界add_header()，因为set_boundary()保留的顺序的Content-Type标头的列表标题。但是，它并没有保留这可能是存在于原始任何连续行的Content-Type首部。

get_content_charset([failobj])

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

请注意，此方法与get_charset()返回Charset消息正文的默认编码的实例不同。

2.2.2版中的新功能。

get_charsets([failobj])

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

列表中的每个项目都是一个字符串，它是表示子部分charset的Content-Type标题中的参数值。但是，如果子部分没有Content-Type标头，没有charset参数，或者不是文本主MIME类型，则返回列表中的该项目将为failobj。

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

改变在2.5版本：先前不赞成的方法get_type()，get_main_type()以及get_subtype()被拆除。

Message 对象还可以选择包含两个实例属性，这些属性可以在生成MIME消息的纯文本时使用。

preamble

MIME文档的格式允许标题后面的空白行和第一个多段边界字符串之间的文本。通常，这个文本在MIME感知的邮件阅读器中是不可见的，因为它不属于标准的MIME装甲。但是，查看邮件的原始文本时，或者在非MIME的阅读器中查看邮件时，可以看到该文本。

在序言属性包含MIME文件这导致额外的装甲文本。当在Parser标题后面但在第一个边界字符串之前发现一些文本时，它会将该文本分配给该消息的前导属性。当Generator写出MIME消息的纯文本表示，并且它发现消息具有前导属性时，它将在头和第一个边界之间的区域中写入该文本。请参阅email.parser并email.generator了解详情。

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

epilogue

的尾声属性作用方式与相同的前导码属性，不同之处在于它包含的最后一个边界和消息的结束之间出现的文本。

在版本2.5中更改：您不需要将尾声设置为空字符串，以便Generator在文件末尾打印换行符。

defects

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

2.4版本中的新功能。