On this page
email.message:代表电子邮件
源代码: Lib/email/message.py
3.6 版的新Function:[1]
email包中的中心类是EmailMessage类,从email.message模块导入。它是email对象模型的 Base Class。 EmailMessage提供了用于设置和查询头字段,访问消息正文以及创建或修改结构化消息的核心Function。
电子邮件由* header 和 payload (也称为 content )组成。Headers 是 RFC 5322或 RFC 6532样式的字段名称和值,其中字段名称和值之间用冒号分隔。冒号既不是字段名也不是字段值的一部分。有效负载可以是简单的文本消息,也可以是二进制对象,也可以是子消息的结构化序列,每个子消息都具有自己的 Headers 集和自己的有效负载。有效负载的后一种类型由具有 MIME 类型的消息(例如 multipart/*或 message/rfc822 *)指示。
EmailMessage对象提供的概念模型是标题的有序词典的模型,该模板与表示消息的 RFC 5322正文的* payload *耦合,该正文可能是 subEmailMessage
对象的列表。除了用于访问 Headers 名称和值的常规词典方法之外,还有一些方法可以从 Headers 访问特殊信息(例如 MIMEContent Type),对有效负载进行操作,生成消息的序列化版本以及递归地遍历对象树。
EmailMessage类似字典的接口由 Headers 名称索引,Headers 名称必须是 ASCII 值。字典的值是带有一些额外方法的字符串。Headers 以保留大小写的形式存储和返回,但是字段名称不区分大小写。与 true 的字典不同,这些键有一个排序,并且可以有重复的键。提供了其他方法来处理具有重复键的 Headers。
对于简单的邮件对象,对于诸如* multipart/*和 message/rfc822 邮件对象之类的 MIME 容器文档, payload *是字符串对象或字节对象,或者是EmailMessage对象列表。
-
- class *
email.message.
EmailMessage
(* policy = default *)
- class *
as_string
(* unixfrom = False , maxheaderlen = None , policy = None *)
如果需要填写默认值以完成对字符串的转换(例如,可能会生成或修改 MIME 边界),则拼合消息可能会触发对EmailMessage的更改。
请注意,此方法是为了方便起见而提供的,可能不是在应用程序中序列化消息的最有用的方法,尤其是在处理多个消息时。有关用于序列化消息的更灵活的 API,请参见email.generator.Generator。另请注意,当utf8为False
时(默认设置),该方法仅限于生成序列化为“ 7 位清除”的消息。
在版本 3.6 中更改:未指定* maxheaderlen 时的默认行为已从策略更改为默认值至默认值* 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,因此可以用来控制该方法产生的某些格式。
- 返回展平为字节对象的整个消息。当可选的* unixfrom *为 true 时,信封头包含在返回的字符串中。 * unixfrom *默认为
如果需要填写默认值以完成对字符串的转换(例如,可能会生成或修改 MIME 边界),则拼合消息可能会触发对EmailMessage的更改。
请注意,此方法是为了方便起见而提供的,可能不是在应用程序中序列化消息的最有用的方法,尤其是在处理多个消息时。有关用于序列化消息的更灵活的 API,请参见email.generator.BytesGenerator。
__bytes__
( )- 等效于as_bytes()。允许
bytes(msg)
产生一个包含序列化消息的字节对象。
- 等效于as_bytes()。允许
is_multipart
( )- 如果消息的有效负载是子EmailMessage对象的列表,则返回
True
,否则返回False
。当is_multipart()返回False
时,有效负载应为字符串对象(可能是 CTE 编码的二进制有效负载)。注意is_multipart()返回True
并不一定意味着“ msg.get_content_maintype()=='multipart'”将返回True
。例如,当EmailMessage类型为message/rfc822
时,is_multipart
将返回True
。
- 如果消息的有效负载是子EmailMessage对象的列表,则返回
set_unixfrom
(* unixfrom *)- 将邮件的信封 Headers 设置为* unixfrom *,它应该是一个字符串。 (有关此 Headers 的简要说明,请参见mboxMessage。)
get_unixfrom
( )- 返回邮件的信封头。如果从未设置信封头,则默认为
None
。
- 返回邮件的信封头。如果从未设置信封头,则默认为
以下方法实现了用于访问消息头的类 Map 接口。请注意,这些方法与常规 Map(即字典)接口之间在语义上有所不同。例如,在词典中没有重复的键,但是这里可能有重复的消息头。同样,在字典中并没有保证keys()返回的键的 Sequences,但是在EmailMessage对象中,Headers 总是按照它们在原始消息中出现的 Sequences 返回,或者以后又添加到消息中。删除然后重新添加的所有 Headers 始终附加在 Headers 列表的末尾。
这些语义差异是有意的,在最常见的用例中偏向于方便。
请注意,在所有情况下,消息中存在的任何信封头都不会包含在 Map 接口中。
__len__
( )- 返回标题总数,包括重复项。
__contains__
(* name *)- 如果消息对象具有名为* name 的字段,则返回
True
。匹配时不考虑大小写,并且 name *不包括结尾的冒号。用于in
运算符。例如:
- 如果消息对象具有名为* name 的字段,则返回
if 'message-id' in myMessage:
print('Message-ID:', myMessage['message-id'])
__getitem__
(* name *)- 返回命名标题字段的值。 名称不包含冒号字段分隔符。如果缺少标题,则返回
None
;否则,返回_。永远不会提出KeyError。
- 返回命名标题字段的值。 名称不包含冒号字段分隔符。如果缺少标题,则返回
请注意,如果命名字段在消息的标题中多次出现,则将不确定返回哪个字段值。使用get_all()方法获取名为* name *的所有现有 Headers 的值。
使用标准(非compat32
)策略,返回值是email.headerregistry.BaseHeader子类的实例。
__setitem__
(* name , val *)- 向消息添加 Headers,其字段名称为* name ,值为 val *。该字段将附加到邮件现有标题的末尾。
请注意,这不会覆盖或删除任何具有相同名称的现有 Headers。如果要确保新标题是消息中字段名称为* name *的唯一字段,请首先删除该字段,例如:
del msg['subject']
msg['subject'] = 'Python roolz!'
如果policy
将某些 Headers 定义为唯一(如标准策略所做的那样),则当try为某个 Headers 分配值(如果已经存在)时,此方法可能会引发ValueError。出于一致性考虑,此行为是有意的,但不依赖于此行为,因为我们将来可能会选择使此类分配对现有 Headers 进行自动删除。
__delitem__
(* name *)- 从邮件标题中删除所有出现的名称为* name *的字段。如果标题字段中不存在命名字段,则不会引发异常。
keys
( )- 返回所有消息标题字段名称的列表。
values
( )- 返回所有消息字段值的列表。
items
( )- 返回一个包含所有消息字段标题和值的 2Tuples 列表。
get
(* name , failobj = None *)- 返回命名标题字段的值。这与getitem()相同,除了如果缺少指定的 Headers 则返回可选的* failobj ( failobj *默认为
None
)。
- 返回命名标题字段的值。这与getitem()相同,除了如果缺少指定的 Headers 则返回可选的* failobj ( failobj *默认为
以下是一些其他有用的 Headers 相关方法:
get_all
(* name , failobj = None *)- 返回名为* name 的字段的所有值的列表。如果消息中没有这样的命名头,则返回 failobj *(默认为
None
)。
- 返回名为* name 的字段的所有值的列表。如果消息中没有这样的命名头,则返回 failobj *(默认为
add_header
(* _name , _value ,** _ params *)- 扩展头设置。此方法与setitem()相似,不同之处在于可以提供其他 Headers 参数作为关键字参数。 * _name 是要添加的标题字段, _ value 是标题的 primary *值。
对于关键字参数字典* _params *中的每个项目,都将键作为参数名称,并将下划线转换为破折号(因为破折号在 Python 标识符中是非法的)。通常,除非值是None
,否则参数将被添加为key="value"
,在这种情况下,仅会添加键。
如果值包含非 ASCII 字符,则可以pass以(CHARSET, LANGUAGE, VALUE)
格式将值指定为三个 Tuples 来显式控制字符集和语言,其中CHARSET
是一个字符串,用于命名用于对值进行编码的字符集,LANGUAGE
通常可以是设置为None
或空字符串(其他可能性请参见 RFC 2231),而VALUE
是包含非 ASCII 代码点的字符串值。如果未传递三个 Tuples 并且该值包含非 ASCII 字符,则会使用utf-8
的CHARSET
和None
的LANGUAGE
自动以 RFC 2231格式进行编码。
这是一个例子:
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 *匹配的消息中找到的第一个 Headers,保留 HeadersSequences 和原始 Headers 的字段名称大小写。如果找不到匹配的 Headers,请引发KeyError。
get_content_type
( )- 返回消息的 Content Type,强制为小写形式* maintype/subtype 。如果消息中没有 Content-Type Headers,则返回get_default_type()返回的值。如果 Content-Type *Headers 无效,则返回
text/plain
。
- 返回消息的 Content Type,强制为小写形式* maintype/subtype 。如果消息中没有 Content-Type Headers,则返回get_default_type()返回的值。如果 Content-Type *Headers 无效,则返回
(根据 RFC 2045,消息始终具有默认类型,get_content_type()将始终返回值。 RFC 2045将消息的默认类型定义为* text/plain ,除非它出现在 multipart/digest 容器内,在这种情况下将是 message/rfc822 。如果 Content-Type Headers 具有无效的类型规范,则 RFC 2045要求默认类型为 text/plain *。)
get_content_maintype
( )- 返回消息的主要 Content Type。这是get_content_type()返回的字符串的* maintype *部分。
get_content_subtype
( )- 返回消息的子 Content Type。这是get_content_type()返回的字符串的* subtype *部分。
get_default_type
( )- 返回默认的 Content Type。大多数消息的默认 Content Type 为* text/plain ,但作为 multipart/digest 容器的子部分的消息除外。这些子部分的默认 Content Type 为 message/rfc822 *。
set_default_type
(* ctype *)- 设置默认的 Content Type。 * ctype 应该是 text/plain 或 message/rfc822 ,尽管这不是强制性的。默认 Content Type 未存储在 Content-Type Headers 中,因此,仅当消息中没有 Content-Type *Headers 时,它才会影响
get_content_type
方法的返回值。
- 设置默认的 Content Type。 * ctype 应该是 text/plain 或 message/rfc822 ,尽管这不是强制性的。默认 Content Type 未存储在 Content-Type Headers 中,因此,仅当消息中没有 Content-Type *Headers 时,它才会影响
set_param
((param , value , header ='Content-Type', requote = True , charset = None , language ='', replace = False *)- 在* Content-Type Headers 中设置一个参数。如果 Headers 中已经存在该参数,则将其值替换为 value 。当 header 为
Content-Type
(默认值)并且邮件中尚不存在标题时,添加它,将其值设置为 text/plain ,并附加新的参数值。可选的 header 指定 Content-Type *的替代标题。
- 在* Content-Type Headers 中设置一个参数。如果 Headers 中已经存在该参数,则将其值替换为 value 。当 header 为
如果该值包含非 ASCII 字符,则可以使用可选的* charset 和 language 参数明确指定字符集和语言。可选的 language 指定 RFC 2231语言,默认为空字符串。 * charset 和 language 都应为字符串。默认值是utf8
字符集和None
作为语言。
如果* replace 为False
(默认值),则标题将移动到标题列表的末尾。如果 replace *为True
,则标题将被适当更新。
不建议对EmailMessage个对象使用* requote *参数。
注意,可以pass Headers 值的params
属性(例如msg['Content-Type'].params['charset']
)访问 Headers 的现有参数值。
在版本 3.4 中更改:添加了replace
关键字。
del_param
(* param , header ='content-type', requote = True *)- 从* Content-Type Headers 中完全删除给定的参数。Headers 将在没有参数或其值的情况下被重写。可选的 header 指定 Content-Type *的替代形式。
不建议对EmailMessage个对象使用* requote *参数。
get_filename
(* failobj = None *)- 返回消息的* Content-Disposition Headers 的
filename
参数的值。如果标题没有filename
参数,则此方法将退回到在 Content-Type 标题上寻找name
参数。如果两者均未找到,或者标题丢失,则返回 failobj *。返回的字符串将始终按照email.utils.unquote()取消引用。
- 返回消息的* Content-Disposition Headers 的
get_boundary
(* failobj = None *)- 返回消息的* Content-Type Headers 的
boundary
参数的值;如果 Headers 丢失或没有boundary
参数,则返回 failobj *。返回的字符串将始终按照email.utils.unquote()取消引用。
- 返回消息的* Content-Type Headers 的
set_boundary
(* boundary *)- 将* Content-Type Headers 的
boundary
参数设置为 boundary 。如有必要,set_boundary()将始终引用 boundary 。如果消息对象没有 Content-Type *Headers,则引发HeaderParseError。
- 将* Content-Type Headers 的
请注意,使用此方法与passadd_header()删除旧的* Content-Type Headers 并添加具有新边界的新方法有一点不同,因为set_boundary()保留了 Content-Type *Headers 在 Headers 列表中的 Sequences。
get_content_charset
(* failobj = None *)- 返回* Content-Type Headers 的
charset
参数(强制小写)。如果没有 Content-Type 头,或者该头没有charset
参数,则返回 failobj *。
- 返回* Content-Type Headers 的
get_charsets
(* failobj = None *)- 返回包含消息中字符集名称的列表。如果消息是* multipart *,则列表将为有效负载中的每个子部分包含一个元素,否则,它将为长度为 1 的列表。
列表中的每个项目都是一个字符串,它是表示子部分的* Content-Type 标题中charset
参数的值。如果子部分没有 Content-Type 头,没有charset
参数或者不是 text 主 MIME 类型,则返回列表中的该项将是 failobj *。
is_attachment
( )- 如果存在* Content-Disposition *Headers 且其(不区分大小写)值为
attachment
,则返回True
,否则返回False
。
- 如果存在* Content-Disposition *Headers 且其(不区分大小写)值为
在版本 3.4.2 中更改:为了与is_multipart()保持一致,is_attachment 现在是方法而不是属性。
get_content_disposition
( )- 返回消息的* Content-Disposition Headers 的小写值(不带参数)(如果有的话)或
None
。如果消息遵循 RFC 2183,则此方法的可能值为 inline , attachment *或None
。
- 返回消息的* Content-Disposition Headers 的小写值(不带参数)(如果有的话)或
3.5 版中的新Function。
以下方法与查询和处理消息的内容(有效负载)有关。
walk
( )
这是一个打印 Multipart 消息结构的每个部分的 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
。我们可以pass使用_structure
debug helper 函数在示例中看到这一点:
>>> 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 部分。
- preferencelist *必须是一组来自
related
,html
和plain
的字符串序列,并指示对返回的 Component 的 Content Type 的偏好 Sequences。
开始寻找与调用get_body
方法的对象匹配的候选对象。
如果related
没有包含在* preferencelist *中,则如果(子)部分与首选项匹配,则将遇到的任何相关的根部分(或根部分的子部分)视为候选对象。
遇到multipart/related
时,请检查start
参数,并且如果找到具有匹配的* Content-ID *的 Component,则在查找候选匹配项时仅考虑它。否则,仅考虑multipart/related
的第一部分(默认根)。
如果 Component 具有* Content-Disposition *Headers,则仅当 Headers 的值为inline
时,才将该 Component 视为候选匹配项。
如果没有候选人符合* preferencelist *中的任何偏好,则返回None
。
注意:(1)对于大多数应用程序,唯一 true 有意义的* preferencelist 组合是('plain',)
,('html', 'plain')
和默认的('related', 'html', 'plain')
。 (2)因为匹配从调用get_body
的对象开始,所以在multipart/related
上调用get_body
将返回对象本身,除非 preferencelist 具有非默认值。 (3)未指定 Content-Type 或 Content-Type *Headers 无效的消息(或消息部分)将被视为text/plain
类型,这有时会导致get_body
返回意外结果。
iter_attachments
( )- 在消息的所有直接子部分(不是候选“正文”部分)上返回迭代器。也就是说,跳过
text/plain
,text/html
,multipart/related
或multipart/alternative
中的每一个的第一次出现(除非它们pass* Content-Disposition:attachment 显式标记为附件),然后返回所有其余部分。直接应用于multipart/related
时,在除根部分(即start
参数指向的部分,如果没有start
参数或start
参数不匹配的第一部分)之外的所有相关部分上返回迭代器任何部分的 Content-ID *)。直接应用于multipart/alternative
或非multipart
时,返回一个空的迭代器。
- 在消息的所有直接子部分(不是候选“正文”部分)上返回迭代器。也就是说,跳过
iter_parts
( )- 在消息的所有直接子部分上返回一个迭代器,对于非
multipart
,它将为空。 (另请参见walk()。)
- 在消息的所有直接子部分上返回一个迭代器,对于非
get_content
((args , content_manager = None ,** kw *)- 调用* content_manager 的get_content()方法,将 self 作为消息对象传递,并将其他任何参数或关键字作为附加参数传递。如果未指定 content_manager *,请使用当前policy指定的
content_manager
。
- 调用* content_manager 的get_content()方法,将 self 作为消息对象传递,并将其他任何参数或关键字作为附加参数传递。如果未指定 content_manager *,请使用当前policy指定的
set_content
((args , content_manager = None ,** kw *)- 调用* content_manager 的set_content()方法,将 self 作为消息对象传递,并将其他任何参数或关键字作为附加参数传递。如果未指定 content_manager *,请使用当前policy指定的
content_manager
。
- 调用* content_manager 的set_content()方法,将 self 作为消息对象传递,并将其他任何参数或关键字作为附加参数传递。如果未指定 content_manager *,请使用当前policy指定的
make_related
- 将非
multipart
消息转换为multipart/related
消息,将任何现有* Content- Headers 和有效负载移动到multipart
的(新)第一部分。如果指定了 boundary *,则将其用作 Multipart 中的边界字符串,否则在需要时(例如,在序列化消息时)保留要自动创建的边界。
- 将非
make_alternative
(* boundary = None *)- 将非
multipart
或multipart/related
转换为multipart/alternative
,将任何现有* Content- Headers 和有效负载移动到multipart
的(新)第一部分。如果指定了 boundary *,则将其用作 Multipart 中的边界字符串,否则在需要时(例如,在序列化消息时)保留要自动创建的边界。
- 将非
make_mixed
(* boundary = None *)- 将非
multipart
,multipart/related
或multipart-alternative
转换为multipart/mixed
,将任何现有* Content- Headers 和有效负载移动到multipart
的(新)第一部分。如果指定了 boundary *,则将其用作 Multipart 中的边界字符串,否则在需要时(例如,在序列化消息时)保留要自动创建的边界。
- 将非
add_related
((args , content_manager = None ,- 如果消息是
multipart/related
,则创建一个新的消息对象,将所有参数传递给其set_content()方法,然后将attach()传递给multipart
。如果消息不是multipart
,请致电make_related(),然后按照上述步骤进行。如果消息是其他任何类型的multipart
,请举起TypeError。如果未指定* content_manager ,请使用当前policy指定的content_manager
。如果添加的部分没有 Content-Disposition *Headers,则添加一个值为inline
的 Headers。
- 如果消息是
add_alternative
((args , content_manager = None ,** kw *)- 如果消息是
multipart/alternative
,则创建一个新的消息对象,将所有参数传递给其set_content()方法,然后将attach()传递给multipart
。如果消息不是multipart
或multipart/related
,请致电make_alternative(),然后按照上述步骤进行操作。如果消息是multipart
的任何其他类型,请举起TypeError。如果未指定* content_manager *,请使用当前policy指定的content_manager
。
- 如果消息是
add_attachment
((args , content_manager = None ,** kw *)- 如果消息是
multipart/mixed
,请创建一个新的消息对象,将所有参数传递给其set_content()方法,然后将attach()传递给multipart
。如果消息不是multipart
,multipart/related
或multipart/alternative
,请致电make_mixed(),然后按上述步骤 continue。如果未指定* content_manager ,请使用当前policy指定的content_manager
。如果添加的部分没有 Content-Disposition Headers,则添加一个值为attachment
的 Headers。pass将适当的选项传递给content_manager
,此方法可用于显式附件( Content-Disposition:attachment )和inline
附件( Content-Disposition:inline *)。
- 如果消息是
clear
( )- 删除有效负载和所有 Headers。
clear_content
( )- 删除有效负载和所有
Content-
Headers,并保留所有其他 Headers 并保持其原始 Sequences。
- 删除有效负载和所有
EmailMessage个对象具有以下实例属性:
preamble
- MIME 文档的格式允许在标题后的空白行和第一个 Multipart 边界字符串之间添加一些文本。通常,此文本在支持 MIME 的邮件阅读器中永远不可见,因为它不在标准 MIME 防护范围内。但是,在查看邮件的原始文本时,或在不支持 MIME 的阅读器中查看邮件时,此文本可能会变得可见。
- preamble 属性包含 MIME 文档的前导多余的装甲文本。当Parser在标题之后但在第一个边界字符串之前发现一些文本时,它将将此文本分配给消息的 preamble 属性。当Generator写出 MIME 消息的纯文本表示形式时,如果发现该消息具有 preamble *属性,它将在 Headers 和第一个边界之间的区域中写入此文本。有关详细信息,请参见email.parser和email.generator。
请注意,如果消息对象没有前导,则* preamble *属性将为None
。
epilogue
-
- epilogue 属性的作用方式与 preamble *属性相同,不同之处在于它包含出现在消息的最后边界和末尾之间的文本。与preamble一样,如果没有 Epilog 文本,则此属性为
None
。
- epilogue 属性的作用方式与 preamble *属性相同,不同之处在于它包含出现在消息的最后边界和末尾之间的文本。与preamble一样,如果没有 Epilog 文本,则此属性为
-
defects
-
- defects *属性包含解析此消息时发现的所有问题的列表。有关可能的解析缺陷的详细说明,请参见email.errors。
-
-
- class *
email.message.
MIMEPart
(* policy = default *)
- 此类表示 MIME 消息的子部分。它与EmailMessage相同,除了在调用set_content()时不添加* MIME-Version Headers,因为子部分不需要它们自己的 MIME-Version *Headers。
- class *
Footnotes
- [1]
- 最初在 3.4 中作为provisional module添加。旧邮件类的文档已移至email.message.Message:使用 compat32 API 表示电子邮件。