You are here:  Home » Python » :代表电子邮件 – 电子邮件和MIME处理包(Python教程)(参考资料)

email.message:代表电子邮件

源代码: Lib / email / message.py


版本3.6中新增: [1]

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

电子邮件由headerspayload(也称为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.EmailMessagepolicy=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消息。另请注意,当utf8False时,此方法被限制产生序列化为“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_bytesunixfrom=False, policy=None

的直接别名返回整个消息扁平化为字节对象。当可选unixfrom为true时,包络头包含在返回的字符串中。unixfrom默认为Falsepolicy参数可以用来覆盖从消息实例中获取的默认策略。这可以用来控制由方法生成的一些格式,因为指定的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当。。。的时候EmailMessagemessage/rfc822.

set_unixfromunixfrom

将邮件的信封标题设置为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__()完全相同,只是如果缺少已知的标题,则返回可选的failobjfailobj默认None).

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

get_allname, 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 格式中使用CHARSETutf-8LANGUAGENone.

这是一个例子:

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

返回邮件的主要内容类型。这是maintypeget_content_type().

get_content_subtype

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

get_default_type

返回的字符串的一部分//返回默认的内容类型。大多数消息的默认内容类型为text/plain,除了作为multipart/digest容器的子部分的消息。这些子部分的默认内容类型为message/rfc822.

set_default_typectype

设置默认内容类型。ctype应该是text/plainmessage/rfc822,尽管这不是强制执行的。默认内容类型不存储在Content-Type标题中,因此当消息中没有get_content_type标题时,它只会影响Content-Type方法的返回值.

set_paramparam, value, header=”Content-Type”, requote=True, charset=None, language=””, replace=False

Content-Type标题中设置一个参数。如果参数已经存在于标题中,则将其值替换为value。当headerContent-Type(默认值)并且标题不存在于消息中时,添加它,将其值设置为text/plain,并附加新参数值。可选header指定Content-Type.

的替代标题如果值包含非ASCII字符,则可以使用可选的charsetlanguage明确指定字符集和语言参数。可选language指定 RFC 2231 语言,默认为空字符串。charsetlanguage都应该是弦乐。默认是使用utf8 charsetNone language.

如果replaceFalse(默认值)标题移动到标题列表的末尾。如果replaceTrue,那么会更新标题

//使用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_boundaryfailobj=None

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

set_boundaryboundary

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, attachmentNone如果消息如下 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()返回Truewalk下降到子部分

get_body (preferencelist=(“related, “html”, plain“))

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

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

开始寻找与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/relatedmultipart/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_managerpolicy.

set_content*args, content_manager=None, **kw指定的

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

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

make_alternativeboundary=None

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

make_mixedboundary=None

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

如果消息是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/relatedmultipart/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.parseremail.generator .

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

epilogue

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

defects

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

class email.message.MIMEPartpolicy=default

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

Footnotes

[1] 最初添加在3.4作为临时模块。旧邮件类的文档已移至 email.message.Message:使用compat32 API表示电子邮件.

评论被关闭。