email.mime: 从头创建电子邮件和 MIME 对象

源代码： Lib/email/mime/

此模块是旧版 (Compat32) email API 的一部分。其功能在新 API 中被 contentmanager 部分取代，但在某些应用中，这些类可能仍然有用，即使在非旧版代码中也是如此。

通常，你通过将文件或一些文本传递给解析器来获取消息对象结构，解析器会解析文本并返回根消息对象。但是你也可以从头开始构建一个完整的消息结构，甚至可以手动创建单个 Message 对象。实际上，你还可以获取一个现有的结构，并添加新的 Message 对象，移动它们等等。这为分割和切分 MIME 消息提供了一个非常方便的接口。

你可以通过创建 Message 实例，手动添加附件和所有适当的标头来创建一个新的对象结构。然而，对于 MIME 消息，email 包提供了一些方便的子类来简化操作。

以下是这些类：

class email.mime.base.MIMEBase(_maintype, _subtype, *, policy=compat32, **_params)

模块： email.mime.base

这是 Message 所有 MIME 特定子类的基类。通常你不会专门创建 MIMEBase 的实例，尽管你可以这样做。MIMEBase 主要作为更具体的 MIME 感知子类的方便基类提供。

_maintype 是 Content-Type 的主类型（例如 text 或 image），而 _subtype 是 Content-Type 的次类型（例如 plain 或 gif）。_params 是一个参数键/值字典，直接传递给 Message.add_header。

如果指定了 policy（默认为 compat32 策略），它将被传递给 Message。

MIMEBase 类总是添加一个 Content-Type 标头（基于 _maintype、_subtype 和 _params）和一个 MIME-Version 标头（总是设置为 1.0）。

在 3.6 版本发生变更: 添加了 policy 仅关键字参数。

class email.mime.nonmultipart.MIMENonMultipart

模块： email.mime.nonmultipart

作为 MIMEBase 的一个子类，这是一个用于非 multipart 类型的 MIME 消息的中间基类。这个类的主要目的是防止使用 attach() 方法，该方法仅对 multipart 消息有意义。如果调用了 attach()，则会引发 MultipartConversionError 异常。

class email.mime.multipart.MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, *, policy=compat32, **_params)

模块： email.mime.multipart

作为 MIMEBase 的一个子类，这是一个用于 multipart 类型的 MIME 消息的中间基类。可选的 _subtype 默认为 mixed，但可用于指定消息的子类型。一个 Content-Type 标头，值为 multipart/_subtype，将被添加到消息对象中。同时也会添加一个 MIME-Version 标头。

可选的 boundary 是多部分边界字符串。当为 None（默认值）时，边界将在需要时计算（例如，当消息被序列化时）。

_subparts 是有效载荷的初始子部分的序列。这个序列必须可以转换为列表。你总是可以使用 Message.attach 方法向消息中附加新的子部分。

可选的 policy 参数默认为 compat32。

Content-Type 标头的附加参数取自关键字参数，或者传入 _params 参数，它是一个关键字字典。

在 3.6 版本发生变更: 添加了 policy 仅关键字参数。

class email.mime.application.MIMEApplication(_data, _subtype='octet-stream', _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

模块： email.mime.application

MIMEApplication 类是 MIMENonMultipart 的子类，用于表示主类型为 application 的 MIME 消息对象。_data 包含原始应用程序数据的字节。可选的 _subtype 指定 MIME 子类型，默认为 octet-stream。

可选的 _encoder 是一个可调用对象（即函数），它将对数据进行实际的传输编码。这个可调用对象接受一个参数，即 MIMEApplication 实例。它应该使用 get_payload() 和 set_payload() 来将有效载荷更改为编码形式。它还应根据需要向消息对象添加任何 Content-Transfer-Encoding 或其他标头。默认编码是 base64。有关内置编码器的列表，请参见 email.encoders 模块。

可选的 policy 参数默认为 compat32。

_params 直接传递给基类的构造函数。

在 3.6 版本发生变更: 添加了 policy 仅关键字参数。

class email.mime.audio.MIMEAudio(_audiodata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

模块： email.mime.audio

MIMEAudio 类是 MIMENonMultipart 的子类，用于创建主类型为 audio 的 MIME 消息对象。_audiodata 包含原始音频数据的字节。如果这些数据可以被解码为 au、wav、aiff 或 aifc，那么子类型将自动包含在 Content-Type 标头中。否则，你可以通过 _subtype 参数显式指定音频子类型。如果无法猜测出次要类型且未提供 _subtype，则会引发 TypeError。

可选的 _encoder 是一个可调用对象（即函数），它将对音频数据进行实际的传输编码。这个可调用对象接受一个参数，即 MIMEAudio 实例。它应该使用 get_payload() 和 set_payload() 来将有效载荷更改为编码形式。它还应根据需要向消息对象添加任何 Content-Transfer-Encoding 或其他标头。默认编码是 base64。有关内置编码器的列表，请参见 email.encoders 模块。

可选的 policy 参数默认为 compat32。

_params 直接传递给基类的构造函数。

在 3.6 版本发生变更: 添加了 policy 仅关键字参数。

class email.mime.image.MIMEImage(_imagedata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

模块： email.mime.image

MIMEImage 类是 MIMENonMultipart 的子类，用于创建主类型为 image 的 MIME 消息对象。_imagedata 包含原始图像数据的字节。如果可以检测到此数据类型（尝试检测 jpeg、png、gif、tiff、rgb、pbm、pgm、ppm、rast、xbm、bmp、webp 和 exr），那么子类型将自动包含在 Content-Type 标头中。否则，你可以通过 _subtype 参数显式指定图像子类型。如果无法猜测出次要类型且未提供 _subtype，则会引发 TypeError。

可选的 _encoder 是一个可调用对象（即函数），它将对图像数据进行实际的传输编码。这个可调用对象接受一个参数，即 MIMEImage 实例。它应该使用 get_payload() 和 set_payload() 来将有效载荷更改为编码形式。它还应根据需要向消息对象添加任何 Content-Transfer-Encoding 或其他标头。默认编码是 base64。有关内置编码器的列表，请参见 email.encoders 模块。

可选的 policy 参数默认为 compat32。

_params 直接传递给 MIMEBase 构造函数。

在 3.6 版本发生变更: 添加了 policy 仅关键字参数。

class email.mime.message.MIMEMessage(_msg, _subtype='rfc822', *, policy=compat32)

模块： email.mime.message

MIMEMessage 类是 MIMENonMultipart 的子类，用于创建主类型为 message 的 MIME 对象。_msg 被用作有效载荷，并且必须是 Message 类（或其子类）的一个实例，否则会引发 TypeError。

可选的 _subtype 设置消息的子类型；默认为 rfc822。

可选的 policy 参数默认为 compat32。

在 3.6 版本发生变更: 添加了 policy 仅关键字参数。

class email.mime.text.MIMEText(_text, _subtype='plain', _charset=None, *, policy=compat32)

模块： email.mime.text

MIMEText 类是 MIMENonMultipart 的子类，用于创建主类型为 text 的 MIME 对象。_text 是有效载荷的字符串。_subtype 是次要类型，默认为 plain。_charset 是文本的字符集，作为参数传递给 MIMENonMultipart 构造函数；如果字符串只包含 ascii 码点，则默认为 us-ascii，否则默认为 utf-8。_charset 参数接受字符串或 Charset 实例。

除非 _charset 参数被显式设置为 None，否则创建的 MIMEText 对象将同时拥有一个带有 charset 参数的 Content-Type 标头和一个 Content-Transfer-Encoding 标头。这意味着，即使在 set_payload 命令中传入了字符集，随后的 set_payload 调用也不会导致有效载荷被编码。你可以通过删除 Content-Transfer-Encoding 标头来“重置”此行为，之后 set_payload 调用将自动编码新的有效载荷（并添加一个新的 Content-Transfer-Encoding 标头）。

可选的 policy 参数默认为 compat32。

在 3.5 版本发生变更: _charset 也接受 Charset 实例。

在 3.6 版本发生变更: 添加了 policy 仅关键字参数。