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

源代码: Lib/email/mime/

---

此模块是传统 (Compat32) 电子邮件 API 的一部分。其功能部分被新 API 中的 contentmanager 替换，但在某些应用程序中，这些类可能仍然有用，即使在非传统代码中也是如此。

通常，您通过将文件或某些文本传递给解析器来获取消息对象结构，解析器会解析文本并返回根消息对象。但是，您也可以从头开始构建完整的邮件结构，甚至可以手动构建单个 Message 对象。实际上，您还可以获取现有结构并添加新的 Message 对象，移动它们等等。这使得 MIME 消息的切片和切块变得非常方便。

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

以下是这些类

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

模块: email.mime.base

这是所有 MIME 特定 Message 子类的基类。通常您不会专门创建 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 是 multipart 边界字符串。当为 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

作为 MIMENonMultipart 的子类，MIMEApplication 类用于表示主类型为 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

作为 MIMENonMultipart 的子类，MIMEAudio 类用于创建主类型为 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

作为 MIMENonMultipart 的子类，MIMEImage 类用于创建主类型为 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

作为 MIMENonMultipart 的子类，MIMEMessage 类用于创建主类型为 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

作为 MIMENonMultipart 的子类，MIMEText 类用于创建主类型为 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 关键字参数。