email.mime: 從頭創(chuàng)建電子郵件和 MIME 對(duì)象

源代碼: Lib/email/mime/

---

此模塊是舊版 (Compat32) 電子郵件 API 的組成部分。 它的功能在新版 API 中被 contentmanager 部分替代，但在某些應(yīng)用中這些類仍可能有用，即使是在非舊版代碼中。

通常，你是通過傳遞一個(gè)文件或一些文本到解析器來獲得消息對(duì)象結(jié)構(gòu)體的，解析器會(huì)解析文本并返回根消息對(duì)象。 不過你也可以從頭開始構(gòu)建一個(gè)完整的消息結(jié)構(gòu)體，甚至是手動(dòng)構(gòu)建單獨(dú)的 Message 對(duì)象。 實(shí)際上，你也可以接受一個(gè)現(xiàn)有的結(jié)構(gòu)體并添加新的 Message 對(duì)象并移動(dòng)它們。 這為切片和分割 MIME 消息提供了非常方便的接口。

你可以通過創(chuàng)建 Message 實(shí)例并手動(dòng)添加附件和所有適當(dāng)?shù)臉?biāo)頭來創(chuàng)建一個(gè)新的對(duì)象結(jié)構(gòu)體。 不過對(duì)于 MIME 消息來說，email 包提供了一些便捷子類來讓事情變得更容易。

這些類列示如下:

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

模塊: email.mime.base

這是 Message 的所有 MIME 專屬子類。 通常你不會(huì)創(chuàng)建專門的 MIMEBase 實(shí)例，盡管你可以這樣做。 MIMEBase 主要被提供用來作為更具體的 MIME 感知子類的便捷基類。

_maintype 是 Content-Type 的主類型 (例如 text 或 image)，而 _subtype 是 Content-Type 的次類型 (例如 plain 或 gif)。 _params 是一個(gè)形參鍵/值字典并會(huì)被直接傳遞給 Message.add_header。

如果指定了 policy (默認(rèn)為 compat32 策略)，它將被傳遞給 Message。

MIMEBase 類總是會(huì)添加一個(gè) Content-Type 標(biāo)頭 (基于 _maintype, _subtype 和 _params)，以及一個(gè) MIME-Version 標(biāo)頭 (總是設(shè)為 1.0)。

在 3.6 版更改: 添加了 policy 僅限關(guān)鍵字形參。

class email.mime.nonmultipart.MIMENonMultipart

模塊: email.mime.nonmultipart

MIMEBase 的子類，這是用于非 multipart MIME 消息的中間基類。 這個(gè)類的主要目標(biāo)是避免使用 attach() 方法，該方法僅對(duì) multipart 消息有意義。 如果 attach() 被調(diào)用，則會(huì)引發(fā) MultipartConversionError 異常。

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

模塊: email.mime.multipart

MIMEBase 的子類，這是用于 multipart MIME 消息的中間基類。 可選的 _subtype 默認(rèn)為 mixed，但可被用來指定消息的子類型。 將會(huì)在消息對(duì)象中添加一個(gè):mimetype:multipart/_subtype 的 Content-Type 標(biāo)頭。 并還將添加一個(gè) MIME-Version 標(biāo)頭。

可選的 boundary 是多部分邊界字符串。 當(dāng)為 None (默認(rèn)值) 時(shí)，則會(huì)在必要時(shí)（例如當(dāng)消息被序列化時(shí)）計(jì)算邊界。

_subparts 是載荷初始子部分的序列。 此序列必須可以被轉(zhuǎn)換為列表。 你總是可以使用 Message.attach 方法將新的子部分附加到消息中。

可選的 policy 參數(shù)默認(rèn)為 compat32。

用于 Content-Type 標(biāo)頭的附加形參會(huì)從關(guān)鍵字參數(shù)中獲取，或者傳入到 _params 參數(shù)，該參數(shù)是一個(gè)關(guān)鍵字的字典。

在 3.6 版更改: 添加了 policy 僅限關(guān)鍵字形參。

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 是包含原始字節(jié)數(shù)據(jù)的字符串。 可選的 _subtype 指定 MIME 子類型并默認(rèn)為 octet-stream。

可選的 _encoder 是一個(gè)可調(diào)用對(duì)象（即函數(shù)），它將執(zhí)行實(shí)際的數(shù)據(jù)編碼以便傳輸。 這個(gè)可調(diào)用對(duì)象接受一個(gè)參數(shù)，該參數(shù)是 MIMEApplication 的實(shí)例。 它應(yīng)當(dāng)使用 get_payload() 和 set_payload() 來將載荷改為已編碼形式。 它還應(yīng)根據(jù)需要將任何 Content-Transfer-Encoding 或其他標(biāo)頭添加到消息對(duì)象中。 默認(rèn)編碼格式為 base64。 請(qǐng)參閱 email.encoders 模塊來查看內(nèi)置編碼器列表。

可選的 policy 參數(shù)默認(rèn)為 compat32。

_params 會(huì)被直接傳遞給基類的構(gòu)造器。

在 3.6 版更改: 添加了 policy 僅限關(guān)鍵字形參。

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

模塊: email.mime.audio

MIMENonMultipart 的子類，MIMEAudio 類被用來創(chuàng)建主類型為 audio 的 MIME 消息。 _audiodata 是包含原始音頻數(shù)據(jù)的字符串。 如果此數(shù)據(jù)可由標(biāo)準(zhǔn) Python 模塊 sndhdr 來編碼，則其子類型將被自動(dòng)包括在 Content-Type 標(biāo)頭。 在其他情況下你可以通過 _subtype 參數(shù)顯式地指定音頻子類型 。 如果無法猜測(cè)出主類型并且未給出 _subtype，則會(huì)引發(fā) TypeError。

可選的 _encoder 是一個(gè)可調(diào)用對(duì)象（即函數(shù)），它將執(zhí)行實(shí)際的音頻數(shù)據(jù)編碼以便傳輸。 這個(gè)可調(diào)用對(duì)象接受一個(gè)參數(shù)，該參數(shù)是 MIMEAudio 的實(shí)例。 它應(yīng)當(dāng)使用 get_payload() 和 set_payload() 來將載荷改為已編碼形式。 它還應(yīng)根據(jù)需要將任何 Content-Transfer-Encoding 或其他標(biāo)頭添加到消息對(duì)象中。 默認(rèn)編碼格式為 base64。 請(qǐng)參閱 email.encoders 模塊來查看內(nèi)置編碼器列表。

可選的 policy 參數(shù)默認(rèn)為 compat32。

_params 會(huì)被直接傳遞給基類的構(gòu)造器。

在 3.6 版更改: 添加了 policy 僅限關(guān)鍵字形參。

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

模塊: email.mime.image

MIMENonMultipart 的子類，MIMEImage 類被用來創(chuàng)建主類型為 image 的 MIME 消息對(duì)象。 _imagedata 是包含原始圖像數(shù)據(jù)的字符串。 如果此數(shù)據(jù)可由標(biāo)準(zhǔn) Python 模塊 imghdr 來解碼，則其子類型將被自動(dòng)包括在 Content-Type 標(biāo)頭中。 在其他情況下你可以通過 _subtype 參數(shù)顯式地指定圖像子類型。 如果無法猜測(cè)出主類型并且未給出 _subtype，則會(huì)引發(fā) TypeError。

可選的 _encoder 是一個(gè)可調(diào)用對(duì)象（即函數(shù)），它將執(zhí)行實(shí)際的圖像數(shù)據(jù)編碼以便傳輸。 這個(gè)可調(diào)用對(duì)象接受一個(gè)參數(shù)，該參數(shù)是 MIMEImage 的實(shí)例。 它應(yīng)當(dāng)使用 get_payload() 和 set_payload() 來將載荷改為已編碼形式。 它還應(yīng)根據(jù)需要將任何 Content-Transfer-Encoding 或其他標(biāo)頭添加到消息對(duì)象中。 默認(rèn)編碼格式為 base64。 請(qǐng)參閱 email.encoders 模塊來查看內(nèi)置編碼器列表。

可選的 policy 參數(shù)默認(rèn)為 compat32。

_params 會(huì)被直接傳遞給 MIMEBase 構(gòu)造器。

在 3.6 版更改: 添加了 policy 僅限關(guān)鍵字形參。

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

模塊: email.mime.message

MIMENonMultipart 的子類，MIMEMessage 類被用來創(chuàng)建主類型為 message 的 MIME 對(duì)象。 _msg 將被用作載荷，并且必須為 Message 類（或其子類）的實(shí)例，否則會(huì)引發(fā) TypeError。

可選的 _subtype 設(shè)置消息的子類型；它的默認(rèn)值為 rfc822。

可選的 policy 參數(shù)默認(rèn)為 compat32。

在 3.6 版更改: 添加了 policy 僅限關(guān)鍵字形參。

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

模塊: email.mime.text

MIMENonMultipart 的子類，MIMEText 類被用來創(chuàng)建主類型為 text 的 MIME 對(duì)象。 _text 是用作載荷的字符串。 _subtype 指定子類型并且默認(rèn)為 plain。 _charset 是文本的字符集并會(huì)作為參數(shù)傳遞給 MIMENonMultipart 構(gòu)造器；如果該字符串僅包含 ascii 碼位則其默認(rèn)值為 us-ascii，否則為 utf-8。 _charset 形參接受一個(gè)字符串或是一個(gè) Charset 實(shí)例。

除非 _charset 參數(shù)被顯式地設(shè)為 None，否則所創(chuàng)建的 MIMEText 對(duì)象將同時(shí)具有附帶 charset 形參的 Content-Type 標(biāo)頭，以及 Content-Transfer-Encoding 標(biāo)頭。 這意味著后續(xù)的 set_payload 調(diào)用將不再產(chǎn)生已編碼的載荷，即使它在 set_payload 命令中被傳入。 你可以通過刪除 Content-Transfer-Encoding 標(biāo)頭來“重置”此行為，在此之后的 set_payload 調(diào)用將自動(dòng)編碼新的載荷（并添加新的 Content-Transfer-Encoding 標(biāo)頭）。

可選的 policy 參數(shù)默認(rèn)為 compat32。

在 3.5 版更改: _charset 也可接受 Charset 實(shí)例。

在 3.6 版更改: 添加了 policy 僅限關(guān)鍵字形參。