19.1.6. email.contentmanager：管理MIME内容

新版本3.4：作为provisional module。

源代码： Lib / email / contentmanager.py

注意

The contentmanager module has been included in the standard library on a provisional basis. 如果核心开发人员认为有必要，可能会发生向后不兼容的更改（直到并包括删除模块）。

message模块提供了一个可以表示任意电子邮件消息的类。该基本消息模型具有有用且灵活的API，但是它仅提供用于与消息的通用部分交互的较低级API（头部，通用头部参数和有效载荷，其可以是子部分的列表）。此模块提供了类和工具，它们提供了增强和可扩展的API，用于处理各种特定类型的内容，包括将消息内容作为专用对象类型检索而不是作为简单字节对象。模块自动处理RFC指定的MIME详细信息（所需的标头和参数等）对于某些常见的内容类型内容属性，并且对于附加类型的支持可以由使用扩展机制的应用程序添加。

此模块定义同义的“Content Manager”类。基本ContentManager类定义用于注册从Message对象提取数据或将数据和标头插入Message对象的内容管理功能的API，从而提供在包含数据和该数据的其他表示（Python数据类型，专用Python对象，外部文件等）的Message对象之间进行转换的方法。该模块还定义了一个具体的内容管理器：raw_data_manager在MIME内容类型和str或bytes数据之间进行转换。它还提供了一个方便的API，用于在将内容插入Message时管理MIME参数。在处理message/rfc822内容类型时，它还处理插入和提取Message对象。

增强接口的另一部分是Message的子类，提供了新的方便的API函数，包括调用从此模块派生的内容管理器的方便方法。

注意

虽然EmailMessage和MIMEPart目前在此模块中有记录，因为代码的临时性，该实现存在于email.message模块中。

class email.message.EmailMessage(policy=default)

如果指定policy（它必须是policy类的实例），请使用其指定的规则来udpate和序列化消息的表示。如果未设置策略，请使用default策略，该策略遵循电子邮件RFC的规则（除了行尾）（而不是RFC强制要求的\r\n，它使用Python标准\n行结尾）。有关详细信息，请参阅policy文档。

此类是Message的子类。它添加以下方法：

is_attachment()

如果有Content-Disposition标题且其（不区分大小写）值为attachment，False，则返回True 。

在版本3.4.2中更改：为了与is_multipart()保持一致，is_attachment现在是一个方法而不是属性。

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

返回作为消息的“主体”的最佳候选者的MIME部分。

偏好列表必须是来自集合related，html和plain的字符串序列，优先选择返回的部件的内容类型。

开始查找与调用get_body方法的对象的候选匹配项。

如果related不包括在偏好列表中，如果（子）部分匹配，则将所遇到的任何相关的根部分（或根部分的子部分）偏爱。

遇到multipart/related时，请检查start参数，如果找到匹配Content-ID的部分，用于候选匹配。否则，只考虑multipart/related的第一个（默认根）部分。

如果零件具有Content-Disposition头，则只有当头的值为inline时，才考虑候选匹配的零件。

如果没有任何候选项匹配preferneclist中的任何偏好设置，则返回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 on a multipart/related will return the object itself unless preferencelist has a non-default value. （3）不指定Content-Type或其Content-Type t>头无效的消息（或消息部分）将被视为类型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或非multipart时，返回一个空的迭代器。

iter_parts()

在消息的所有直接子部分上返回迭代器，对于非multipart，该子部分将为空。（参见walk()。）

get_content(*args, content_manager=None, **kw)

调用content_manager的get_content方法，传递self作为消息对象，并传递任何其他参数或关键字作为附加参数。如果未指定content_manager，请使用当前policy指定的content_manager。

set_content(*args, content_manager=None, **kw)

调用content_manager的set_content方法，传递self作为消息对象，并传递任何其他参数或关键字作为附加参数。如果未指定content_manager，请使用当前policy指定的content_manager。

make_related(boundary=None)

将非multipart消息转换为multipart/related消息，将任何现有的Content - multipart。如果指定boundary，则使用它作为多部分中的边界字符串，否则在需要时（例如，当消息被序列化时）保留要自动创建的边界。

make_alternative(boundary=None)

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

make_mixed(boundary=None)

Convert a non-multipart, a multipart/related, or a multipart-alternative into a multipart/mixed, moving any existing Content- headers and payload into a (new) first part of the multipart. 如果指定boundary，则使用它作为多部分中的边界字符串，否则在需要时（例如，当消息被序列化时）保留要自动创建的边界。

add_related(*args, content_manager=None, **kw)

If the message is a multipart/related, create a new message object, pass all of the arguments to its set_content() method, and attach() it to the multipart. 如果消息是非multipart，请调用make_related()，然后按照上述步骤操作。如果消息是任何其他类型的multipart，则引发TypeError。如果未指定content_manager，请使用当前policy指定的content_manager。如果添加的部分没有Content-Disposition头，请添加值inline的值。

add_alternative(*args, content_manager=None, **kw)

If the message is a multipart/alternative, create a new message object, pass all of the arguments to its set_content() method, and attach() it to the multipart. 如果消息是非multipart或multipart/related，请调用make_alternative()，然后按上述步骤操作。如果消息是任何其他类型的multipart，则引发TypeError。如果未指定content_manager，请使用当前policy指定的content_manager。

add_attachment(*args, content_manager=None, **kw)

If the message is a multipart/mixed, create a new message object, pass all of the arguments to its set_content() method, and attach() it to the multipart. 如果消息是非multipart，multipart/related或multipart/alternative，则调用make_mixed()然后如上所述进行。如果未指定content_manager，请使用当前policy指定的content_manager。如果添加的部分没有Content-Disposition标题，请添加值为attachment的值。此方法可用于显式附件（Content-Disposition：附件和inline附件（Content-Disposition：inline），选项至content_manager。

clear()

删除有效负载和所有标题。

clear_content()

删除有效内容和所有Content-标头，保留所有其他标头，并保持其原始顺序。

class email.message.MIMEPart(policy=default)

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

class email.contentmanager.ContentManager

内容管理器的基类。提供标准注册表机制，以在MIME内容和其他表示以及get_content和set_content调度方法之间注册转换器。

get_content(msg, *args, **kw)

查找基于msg（见下一段）的mimetype的处理函数，调用它，传递所有参数，并返回调用的结果。期望处理程序将从msg提取有效负载，并返回编码有关提取的数据的信息的对象。

要找到处理程序，在注册表中查找以下键，停止与找到的第一个：

• the string representing the full MIME type (maintype/subtype)
• the string representing the maintype
• the empty string

如果这些键都不产生处理程序，请为完整的MIME类型引用KeyError。

set_content(msg, obj, *args, **kw)

如果maintype是multipart，则引发TypeError；否则基于obj类型查看处理函数（见下一段），在msg上调用clear_content()处理函数，传递所有参数。期望的是处理程序将转换并将obj存储到msg中，也可能对msg进行其他更改，以对解释所存储的数据所需的信息进行编码。

要找到处理程序，请获取类型obj（typ = type（obj） t1>），并在注册表中查找以下键，停止与找到的第一个：

• the type itself (typ)
• the type’s fully qualified name (typ.__module__ + '.' + typ.__qualname__).
• the type’s qualname (typ.__qualname__)
• the type’s name (typ.__name__).

如果以上没有匹配，请重复上述对MRO（typ.__mro__）中的每个类型的所有检查。最后，如果没有其他键产生处理程序，请检查键None的处理程序。如果没有None的处理程序，请为类型的完全限定名引入KeyError。

如果不存在，请添加MIME-Version标头（另请参阅MIMEPart）。

add_get_handler(key, handler)

记录函数处理程序作为键的处理程序。有关键的可能值，请参阅get_content()。

add_set_handler(typekey, handler)

记录处理程序作为当匹配typekey的类型的对象传递到set_content()时调用的函数。有关typekey的可能值，请参阅set_content()。

19.1.6.1. Content Manager Instances

目前，电子邮件包只提供一个具体的内容管理器raw_data_manager，虽然将来可能会添加更多内容。raw_data_manager是由EmailPolicy提供的content_manager及其衍生物。

email.contentmanager.raw_data_manager

此内容管理器仅提供超过Message本身提供的最小接口：它仅处理文本，原始字节字符串和Message对象。然而，与基本API相比，它提供了显着的优点：get_content在文本部分将返回unicode字符串，而应用程序不需要手动解码，set_content用于控制添加到部件的报头并控制内容传输编码的选项，并且它使得能够使用各种add_方法，从而简化多部分消息的创建。

email.contentmanager.get_content(msg, errors='replace')

以零件的字符串（text），EmailMessage对象（message/rfc822零件） bytes对象（对于所有其他非多部分类型）。如果在multipart上调用，则引发KeyError。如果部分是text部分，并且指定了错误，则在将有效负载解码为unicode时将其用作错误处理程序。默认错误处理程序为replace。

email.contentmanager.set_content(msg, <'str'>, subtype="plain", charset='utf-8' cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)

email.contentmanager。 set_content （ msg，＆lt；'bytes'＆gt； ，maintype，subtype，cte =“base64”，disposition = None，/ t9>，cid = None，params = None，headers = None ）

email.contentmanager。 set_content （ msg，＆lt；'Message'＆gt； ，cte = None，disposition = None，filename = None，cid = None，无，headers =无 ）

email.contentmanager。 set_content （ msg，＆lt；'list'＆gt； ，subtype ='mixed'，disposition = None，filename = None，cid = None，params = None，headers = None ）

向msg添加标题和有效内容：

添加Content-Type标头，其中包含maintype/subtype值。

• For str, set the MIME maintype to text, and set the subtype to subtype if it is specified, or plain if it is not.
• For bytes, use the specified maintype and subtype, or raise a TypeError if they are not specified.
• For Message objects, set the maintype to message, and set the subtype to subtype if it is specified or rfc822 if it is not. If subtype is partial, raise an error (bytes objects must be used to construct message/partial parts).
• For <’list’>, which should be a list of Message objects, set the maintype to multipart, and the subtype to subtype if it is specified, and mixed if it is not. If the message parts in the <’list’> have MIME-Version headers, remove them.

如果提供charset（仅对str有效），请使用指定的字符集将字符串编码为字节。默认值为utf-8。如果指定的字符集是标准MIME字符集名称的已知别名，请改用标准字符集。

如果设置了cte，则使用指定的内容传输编码对有效载荷进行编码，并将Content-Transfer-Endcoding头设置为该值。对于str对象，如果未设置，则使用启发式来确定最紧凑的编码。cte的可能值为quoted-printable，base64，7bit，8bit和binary。如果输入不能以指定的编码进行编码（例如：7bit），则引入ValueError。For Message, per RFC 2046, raise an error if a cte of quoted-printable or base64 is requested for subtype rfc822, and for any cte other than 7bit for subtype external-body. 对于message/rfc822，如果未指定cte，请使用8bit。对于子类型的所有其他值，请使用7bit。

注意

binary的cte实际上还不能正常工作。由set_content修改的Message对象是正确的，但BytesGenerator不能正确地序列化。

如果设置了disposition t>，则将其用作Content-Disposition标头的值。如果未指定，并且指定filename，请添加带有attachment值的标头。如果未指定并且未指定filename，请不要添加标题。处置的唯一有效值为attachment和inline。

如果指定filename，则将其用作Content-Disposition头的filename参数的值。没有默认值。

如果指定cid，请添加Content-ID头，并以cid作为其值。

如果指定params，则迭代其items方法并使用结果（键， 值） / t3>对在Content-Type标题上设置其他参数。

如果指定headers并且是headername： headervalue形式的字符串列表或header对象（通过具有name属性来区分字符串），请将标头添加到msg。