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