Skip to main content

19.1.10. 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感知子类的方便的基类。

_maintypeContent-Type 主要类型(例如 textimage),_subtypeContent-Type 次要类型(例如 plaingif)。 _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/_subtypeContent-Type 头将添加到消息对象。还将添加 MIME-Version 头。

可选 boundary 是多部分边界字符串。当 None (默认值)时,在需要时计算边界(例如,当消息被序列化时)。

_subparts 是有效载荷的初始子部分的序列。必须可以将此序列转换为列表。您可以随时使用 Message.attach 方法将新的子部件附加到消息。

可选的 policy 参数默认为 compat32

Content-Type 头的附加参数取自关键字参数,或传递到 _params 参数,_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 是可执行(即函数),其将执行用于传输的数据的实际编码。这个callable接受一个参数,它是 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 是包含原始音频数据的字符串。如果该数据可以由标准Python模块 sndhdr 解码,则子类型将被自动包括在 Content-Type 头部中。否则,您可以通过 _subtype 参数显式指定音频子类型。如果次要类型不能被猜出并且没有给出 _subtype,则提出 TypeError

可选的 _encoder 是将对音频数据进行实际编码以进行传输的可调用(即函数)。这个callable接受一个参数,它是 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 是包含原始图像数据的字符串。如果该数据可以由标准Python模块 imghdr 解码,则子类型将被自动包括在 Content-Type 头部中。否则,您可以通过 _subtype 参数显式指定图像子类型。如果次要类型不能被猜出并且没有给出 _subtype,则提出 TypeError

可选的 _encoder 是可调用的(即函数),其将执行用于传输的图像数据的实际编码。这个callable接受一个参数,它是 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-Endcoding 头部。这意味着后续的 set_payload 调用不会产生编码的有效载荷,即使在 set_payload 命令中传递了字符集。您可以通过删除 Content-Transfer-Encoding 头来“重置”此行为,之后 set_payload 调用将自动编码新的有效内容(并添加一个新的 Content-Transfer-Encoding 头)。

可选的 policy 参数默认为 compat32

在 3.5 版更改: _charset 也接受 Charset 实例。

在 3.6 版更改: 添加了仅 policy 关键字参数。