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

这是 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，但可用于指定消息的子类型。将向消息对象添加 multipart/_subtype 的 Content-Type 标头。还将添加 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

作为 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 仅关键字参数。