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 僅關鍵字引數。