`email.message` ：表示 Email 消息 ¶

3.6 版新增： 1

中心类在 email 包是 EmailMessage 类，导入自 email.message 模块。它是基类对于 email 对象模型。 EmailMessage 提供设置和查询 Header 头字段、访问消息本体、创建或修改结构化消息的核心功能。

Email 包含 headers 和 payload (也称为 content )。Header 头是 RFC 5322 or RFC 6532 样式的字段名称和值，其中字段名称和值由冒号分隔。冒号不属于字段名称或字段值。负载可以是简单文本消息、二进制对象、或结构化的子消息序列 (每个子消息有自己的一组头和负载)。后一种类型的负载由拥有 MIME (多用途 Internet 邮件扩展) 类型的消息指示，譬如 multipart/* or message/rfc822 .

概念模型的提供通过 EmailMessage 对象，它是有序 Header 头字典耦合 payload 表示 RFC 5322 本体对于消息，可能是列表的子 EmailMessage 对象。除用于访问 Header 头名称和值的正常字典方法外，还有一些方法从头访问专门信息 (例如 MIME 内容类型)、操作负载、生成消息的序列化版本及递归遍历对象树。

EmailMessage 像字典接口通过必须是 ASCII 值的 Header 头名称进行索引。字典值是带有一些额外方法的字符串。头以保留大小写的形式被存储和返回，但字段名称不区分大小写匹配。不像真实字典，键有顺序且可以重复。有提供额外方法来处理拥有重复键的 Header 头。

payload 是字符串或字节对象 (在简单消息对象情况下) 或列表的 EmailMessage 对象对于 MIME 容器文档，譬如 multipart/* and 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 为 True，信封头包括在返回字符串中。 unixfrom 默认为 False 。为向后兼容基 Message class maxheaderlen 被接受，但默认为 None ，意味着默认情况下，控制行长度通过 max_line_length 的策略。 policy 自变量可用于覆盖从消息实例获得的默认策略。这可用于控制通过方法产生的某些格式化，由于指定 policy 会被传递给 Generator .

扁平化消息可能触发改变 EmailMessage 若默认需要填充以完成字符串转换 (例如，可以生成或修改 MIME 边界)。

注意，提供此方法是为了方便，且可能不是在应用程序中序列化消息的最有用方式，尤其是处理多条消息。见 email.generator.Generator 了解用于序列化消息的更灵活 API。另请注意，此方法被限定到产生 7 bit clean 序列化消息当 utf8 is False ，默认。

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 若默认需要填充以完成字符串转换 (例如，可以生成或修改 MIME 边界)。

注意，提供此方法是为了方便，且可能不是在应用程序中序列化消息的最有用方式，尤其是处理多条消息。见 email.generator.BytesGenerator 了解用于序列化消息的更灵活 API。

__bytes__ ( ) ¶: 相当于 as_bytes() 。允许 bytes(msg) 产生包含序列化消息的字节对象。

is_multipart ( ) ¶: 返回 True 若消息负载是列表对于子 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 若从未设置信封头。

The following methods implement the mapping-like interface for accessing the message’s headers. Note that there are some semantic differences between these methods and a normal mapping (i.e. dictionary) interface. For example, in a dictionary there are no duplicate keys, but here there may be duplicate message headers. Also, in dictionaries there is no guaranteed order to the keys returned by keys() , but in an EmailMessage object, headers are always returned in the order they appeared in the original message, or in which they were added to the message later. Any header deleted and then re-added is always appended to the end of the header list.

These semantic differences are intentional and are biased toward convenience in the most common use cases.

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

__len__ ( ) ¶: 返回 Header 头的总数，包括重复的。

__contains__ ( name ) ¶

返回 True if the message object has a field named name . Matching is done without regard to case and name does not include the trailing colon. Used for the in operator. For example:

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

__getitem__ ( name ) ¶

Return the value of the named header field. name does not include the colon field separator. If the header is missing, None is returned; a KeyError 从不被引发。

Note that if the named field appears more than once in the message’s headers, exactly which of those field values will be returned is undefined. Use the get_all() method to get the values of all the extant headers named name .

使用标准 (非 compat32 ) 策略，返回值是实例化的子类 email.headerregistry.BaseHeader .

__setitem__ ( name , val ) ¶

将 Header 头添加到消息采用字段名称 name 和值 val 。将字段追加到消息的现有头末尾。

Note that this does not overwrite or delete any existing header with the same name. If you want to ensure that the new header is the only one present in the message with field name name , delete the field first, e.g.:

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

若 policy defines certain headers to be unique (as the standard policies do), this method may raise a ValueError when an attempt is made to assign a value to such a header when one already exists. This behavior is intentional for consistency’s sake, but do not depend on it as we may choose to make such assignments do an automatic deletion of the existing header in the future.

__delitem__ ( name ) ¶: Delete all occurrences of the field with name name from the message’s headers. No exception is raised if the named field isn’t present in the headers.

keys ( ) ¶: 返回所有消息头字段名称的列表。

values ( ) ¶: 返回所有消息字段值的列表。

items ( ) ¶: 返回包含所有消息的字段头和值的 2 元组列表。

get ( name , failobj=None ) ¶: 返回命名头字段的值。这等同于 __getitem__() 除了可选 failobj is returned if the named header is missing ( failobj 默认为 None ).

Here are some additional useful header related methods:

get_all ( name , failobj=None ) ¶: 返回所有值的列表对于字段命名 name 。若消息中没有这种命名头， failobj 被返回 (默认为 None ).

add_header ( _name , _value , **_params ) ¶

扩展 Header 头设置。此方法类似于 __setitem__() 除可以提供额外 Header 头参数作为关键词自变量外。 _name 是要添加的头字段和 _value 是 primary 头值。

For each item in the keyword argument dictionary _params , the key is taken as the parameter name, with underscores converted to dashes (since dashes are illegal in Python identifiers). Normally, the parameter will be added as key="value" unless the value is None , in which case only the key will be added.

If the value contains non-ASCII characters, the charset and language may be explicitly controlled by specifying the value as a three tuple in the format (CHARSET, LANGUAGE, VALUE) ，其中 CHARSET is a string naming the charset to be used to encode the value, LANGUAGE can usually be set to None or the empty string (see RFC 2231 了解其它可能性)，和 VALUE is the string value containing non-ASCII code points. If a three tuple is not passed and the value contains non-ASCII characters, it is automatically encoded in RFC 2231 format using a CHARSET of utf-8 和 LANGUAGE of None .

这里是范例：

											msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
											
										

这添加的 Header 头看起来像

											Content-Disposition: attachment; filename="bud.gif"
											
										

An example of the extended interface with non-ASCII characters:

											msg.add_header('Content-Disposition', 'attachment',
               filename=('iso-8859-1', '', 'Fußballer.ppt'))

replace_header ( _name , _value ) ¶: Replace a header. Replace the first header found in the message that matches _name , retaining header order and field name case of the original header. If no matching header is found, raise a KeyError .

get_content_type ( ) ¶

Return the message’s content type, coerced to lower case of the form maintype/subtype . If there is no Content-Type header in the message return the value returned by get_default_type() 。若 Content-Type header is invalid, return text/plain .

(According to RFC 2045 , messages always have a default type, get_content_type() will always return a value. RFC 2045 defines a message’s default type to be text/plain unless it appears inside a multipart/digest container, in which case it would be message/rfc822 。若 Content-Type header has an invalid type specification, RFC 2045 mandates that the default type be text/plain .)

get_content_maintype ( ) ¶: Return the message’s main content type. This is the maintype part of the string returned by get_content_type() .

get_content_subtype ( ) ¶: Return the message’s sub-content type. This is the subtype part of the string returned by get_content_type() .

get_default_type ( ) ¶: Return the default content type. Most messages have a default content type of text/plain , except for messages that are subparts of multipart/digest containers. Such subparts have a default content type of message/rfc822 .

set_default_type ( ctype ) ¶: Set the default content type. ctype should either be text/plain or message/rfc822 , although this is not enforced. The default content type is not stored in the Content-Type header, so it only affects the return value of the get_content_type methods when no Content-Type header is present in the message.

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

Set a parameter in the Content-Type header. If the parameter already exists in the header, replace its value with value 。当 header is Content-Type (the default) and the header does not yet exist in the message, add it, set its value to text/plain , and append the new parameter value. Optional header specifies an alternative header to Content-Type .

If the value contains non-ASCII characters, the charset and language may be explicitly specified using the optional charset and language parameters. Optional language specifies the RFC 2231 language, defaulting to the empty string. Both charset and language should be strings. The default is to use the utf8 charset and None 为 language .

若 replace is False (the default) the header is moved to the end of the list of headers. If replace is True , the header will be updated in place.

Use of the requote parameter with EmailMessage objects is deprecated.

Note that existing parameter values of headers may be accessed through the params attribute of the header value (for example, msg['Content-Type'].params['charset'] ).

3.4 版改变： replace 关键词被添加。

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

Remove the given parameter completely from the Content-Type header. The header will be re-written in place without the parameter or its value. Optional header specifies an alternative to Content-Type .

Use of the requote parameter with EmailMessage objects is deprecated.

get_filename ( failobj=None ) ¶: Return the value of the filename parameter of the Content-Disposition header of the message. If the header does not have a filename parameter, this method falls back to looking for the name parameter on the Content-Type header. If neither is found, or the header is missing, then failobj is returned. The returned string will always be unquoted as per email.utils.unquote() .

get_boundary ( failobj=None ) ¶: Return the value of the boundary parameter of the Content-Type header of the message, or failobj if either the header is missing, or has no boundary parameter. The returned string will always be unquoted as per email.utils.unquote() .

set_boundary ( boundary ) ¶

设置 boundary parameter of the Content-Type header to boundary . set_boundary() will always quote boundary if necessary. A HeaderParseError is raised if the message object has no Content-Type 头。

Note that using this method is subtly different from deleting the old Content-Type header and adding a new one with the new boundary via add_header() , because set_boundary() preserves the order of the Content-Type header in the list of headers.

get_content_charset ( failobj=None ) ¶: 返回 charset parameter of the Content-Type header, coerced to lower case. If there is no Content-Type header, or if that header has no charset 参数， failobj 被返回。

get_charsets ( failobj=None ) ¶

Return a list containing the character set names in the message. If the message is a multipart , then the list will contain one element for each subpart in the payload, otherwise, it will be a list of length 1.

Each item in the list will be a string which is the value of the charset parameter in the Content-Type header for the represented subpart. If the subpart has no Content-Type header, no charset parameter, or is not of the text main MIME type, then that item in the returned list will be failobj .

is_attachment ( ) ¶: 返回 True if there is a Content-Disposition header and its (case insensitive) value is attachment , False 否则。

3.4.2 版改变： is_attachment is now a method instead of a property, for consistency with is_multipart() .

get_content_disposition ( ) ¶: Return the lowercased value (without parameters) of the message’s Content-Disposition header if it has one, or None . The possible values for this method are inline , attachment or None if the message follows RFC 2183 .

3.5 版新增。

The following methods relate to interrogating and manipulating the content (payload) of the message.

walk ( ) ¶

walk() method is an all-purpose generator which can be used to iterate over all the parts and subparts of a message object tree, in depth-first traversal order. You will typically use walk() as the iterator in a for loop; each iteration returns the next subpart.

Here’s an example that prints the MIME type of every part of a multipart message structure:

											>>> 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 iterates over the subparts of any part where is_multipart() 返回 True , even though msg.get_content_maintype() == 'multipart' may return False . We can see this in our example by making use of the _structure debug helper function:

											>>> 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
											
										

Here the message parts are not multiparts , but they do contain subparts. is_multipart() 返回 True and walk descends into the subparts.

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

Return the MIME part that is the best candidate to be the “body” of the message.

preferencelist must be a sequence of strings from the set related , html ，和 plain , and indicates the order of preference for the content type of the part returned.

Start looking for candidate matches with the object on which the get_body 方法被调用。

若 related is not included in preferencelist , consider the root part (or subpart of the root part) of any related encountered as a candidate if the (sub-)part matches a preference.

When encountering a multipart/related , check the start parameter and if a part with a matching Content-ID is found, consider only it when looking for candidate matches. Otherwise consider only the first (default root) part of the multipart/related .

If a part has a Content-Disposition header, only consider the part a candidate match if the value of the header is inline .

If none of the candidates matches any of the preferences in preferencelist ，返回 None .

Notes: (1) For most applications the only preferencelist combinations that really make sense are ('plain',) , ('html', 'plain') , and the default ('related', 'html', 'plain') . (2) Because matching starts with the object on which get_body is called, calling get_body 在 multipart/related will return the object itself unless preferencelist has a non-default value. (3) Messages (or message parts) that do not specify a Content-Type or whose Content-Type header is invalid will be treated as if they are of type text/plain , which may occasionally cause get_body to return unexpected results.

iter_attachments ( ) ¶: Return an iterator over all of the immediate sub-parts of the message that are not candidate “body” parts. That is, skip the first occurrence of each of text/plain , text/html , multipart/related ，或 multipart/alternative (unless they are explicitly marked as attachments via Content-Disposition: attachment ), and return all remaining parts. When applied directly to a multipart/related , return an iterator over the all the related parts except the root part (ie: the part pointed to by the start parameter, or the first part if there is no start parameter or the start parameter doesn’t match the Content-ID of any of the parts). When applied directly to a multipart/alternative or a non- multipart , return an empty iterator.

iter_parts ( ) ¶: Return an iterator over all of the immediate sub-parts of the message, which will be empty for a non- 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 is specified, use it as the boundary string in the multipart, otherwise leave the boundary to be automatically created when it is needed (for example, when the message is serialized).

make_alternative ( boundary=None ) ¶: 转换非 multipart 或 multipart/related 成 multipart/alternative ，移动任何现有 Content- 头和负载到 (新的) 第一部分的 multipart 。若 boundary is specified, use it as the boundary string in the multipart, otherwise leave the boundary to be automatically created when it is needed (for example, when the message is serialized).

make_mixed ( boundary=None ) ¶: 转换非 multipart ， multipart/related ，或 multipart-alternative 成 multipart/mixed ，移动任何现有 Content- 头和负载到 (新的) 第一部分的 multipart 。若 boundary is specified, use it as the boundary string in the multipart, otherwise leave the boundary to be automatically created when it is needed (for example, when the message is serialized).

add_related ( *args , content_manager=None , **kw ) ¶: 若消息为 multipart/related ，创建新的消息对象，将所有自变量传递给其 set_content() 方法，和 attach() 它到 multipart 。若消息是非 multipart ，调用 make_related() 然后按上文继续进行。若消息是任何其它类型的 multipart ，引发 TypeError 。若 content_manager 未指定，使用 content_manager 指定通过当前 policy 。若添加部分没有 Content-Disposition header, add one with the value inline .

add_alternative ( *args , content_manager=None , **kw ) ¶: 若消息为 multipart/alternative ，创建新的消息对象，将所有自变量传递给其 set_content() 方法，和 attach() 它到 multipart 。若消息是非 multipart or 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() and then proceed as above. If content_manager 未指定，使用 content_manager 指定通过当前 policy 。若添加部分没有 Content-Disposition header, add one with the value attachment . This method can be used both for explicit attachments ( Content-Disposition: attachment ) 和 inline attachments ( Content-Disposition: inline ), by passing appropriate options to the content_manager .

clear ( ) ¶: 移除负载和所有头。

clear_content ( ) ¶: 移除负载和所有 Content- 头，完整保留所有其它头及其原始次序。

EmailMessage 对象拥有下列实例属性：

preamble ¶

The format of a MIME document allows for some text between the blank line following the headers, and the first multipart boundary string. Normally, this text is never visible in a MIME-aware mail reader because it falls outside the standard MIME armor. However, when viewing the raw text of the message, or when viewing the message in a non-MIME aware reader, this text can become visible.

preamble attribute contains this leading extra-armor text for MIME documents. When the Parser discovers some text after the headers but before the first boundary string, it assigns this text to the message’s preamble attribute. When the Generator is writing out the plain text representation of a MIME message, and it finds the message has a preamble attribute, it will write this text in the area between the headers and the first boundary. See email.parser and email.generator 了解细节。

Note that if the message object has no preamble, the preamble 属性将是 None .

epilogue ¶: epilogue attribute acts the same way as the preamble attribute, except that it contains text that appears between the last boundary and the end of the message. As with the preamble , if there is no epilog text this attribute will be None .

defects ¶: defects attribute contains a list of all the problems found when parsing this message. See email.errors for a detailed description of the possible parsing defects.

class email.message. MIMEPart ( policy=default ) ¶: This class represents a subpart of a MIME message. It is identical to EmailMessage , except that no MIME-Version headers are added when set_content() is called, since sub-parts do not need their own MIME-Version 头。

脚注

1: 最初在 3.4 添加作为暂行模块。传统消息类文档移到 email.message.Message：表示 Email 消息使用 compat32 API .

上一话题

email — Email 和 MIME 处理包

下一话题

email.parser : 剖析 Email 消息

`email.message` ：表示 Email 消息 ¶

上一话题

下一话题

本页

快速搜索

email.message ：表示 Email 消息 ¶

上一话题

下一话题

本页

快速搜索

`email.message` ：表示 Email 消息 ¶