email.generator：生成 MIME 文件

原始碼: Lib/email/generator.py

最常見的任務之一是生成由訊息物件結構表示的電子郵件訊息的扁平（序列化）版本。如果您想透過 smtplib.SMTP.sendmail() 傳送訊息，或者在控制檯上列印訊息，您將需要執行此操作。獲取訊息物件結構並生成序列化表示是生成器類的工作。

與 email.parser 模組一樣，您並不侷限於捆綁的生成器的功能；您可以自己從頭開始編寫一個。但是，捆綁的生成器知道如何以符合標準的方式生成大多數電子郵件，應該可以很好地處理 MIME 和非 MIME 電子郵件訊息，並且其設計使得面向位元組的解析和生成操作是相反的，假設兩者都使用相同的非轉換 policy 。也就是說，透過 BytesParser 類解析序列化的位元組流，然後使用 BytesGenerator 重新生成序列化的位元組流，應該會產生與輸入相同的輸出 [1]。（另一方面，在程式構建的 EmailMessage 上使用生成器可能會導致 EmailMessage 物件發生更改，因為會填充預設值。）

Generator 類可用於將訊息展平為文字（而不是二進位制）序列化表示，但由於 Unicode 無法直接表示二進位制資料，因此必須使用標準的電子郵件 RFC 內容傳輸編碼技術將訊息轉換為僅包含 ASCII 字元的內容，以便在不是“8 位乾淨”的通道上傳輸電子郵件訊息。

為了適應對 SMIME 簽名訊息的可重複處理，Generator 停用 multipart/signed 型別和所有子部分的訊息部分的標頭摺疊。

class email.generator.BytesGenerator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

返回一個 BytesGenerator 物件，該物件將把提供給 flatten() 方法的任何訊息或提供給 write() 方法的任何 surrogateescape 編碼的文字寫入 類檔案物件 outfp。outfp 必須支援一個接受二進位制資料的 write 方法。

如果可選的 mangle_from_ 為 True，則在正文中任何以確切字串 "From " 開頭的行前面放置一個 > 字元，即 From 後跟一個空格，在行的開頭。mangle_from_ 預設為 policy 的 mangle_from_ 設定的值（對於 compat32 策略為 True，對於所有其他策略為 False）。mangle_from_ 旨在用於訊息以 Unix mbox 格式儲存時（請參閱 mailbox 和 為什麼內容長度格式是錯誤的）。

如果 maxheaderlen 不是 None，則重新摺疊任何長於 maxheaderlen 的標頭行，或者如果為 0，則不重新包裝任何標頭。如果 manheaderlen 為 None（預設值），則根據 policy 設定包裝標頭和其他訊息行。

如果指定了 policy，則使用該策略來控制訊息生成。如果 policy 為 None（預設值），則使用與傳遞給 flatten 的 Message 或 EmailMessage 物件關聯的策略來控制訊息生成。有關 policy 控制的詳細資訊，請參閱 email.policy。

3.2 版本新增。

在 3.3 版本中更改: 添加了 policy 關鍵字。

在 3.6 版本中更改: mangle_from_ 和 maxheaderlen 引數的預設行為是遵循策略。

flatten(msg, unixfrom=False, linesep=None)

將以 msg 為根的訊息物件結構的文字表示形式列印到建立 BytesGenerator 例項時指定的輸出檔案。

如果 policy 選項 cte_type 為 8bit (預設值)，則將原始解析訊息中任何未修改的標頭複製到輸出，其中高位已設定的位元組將按原始形式重現，並保留具有非 ASCII Content-Transfer-Encoding 的任何正文部分的非 ASCII Content-Transfer-Encoding。如果 cte_type 為 7bit，則使用與 ASCII 相容的 Content-Transfer-Encoding 根據需要轉換高位設定的位元組。也就是說，將具有非 ASCII Content-Transfer-Encoding（Content-Transfer-Encoding: 8bit）的部分轉換為與 ASCII 相容的 Content-Transfer-Encoding，並使用 MIME unknown-8bit 字元集對標頭中不符合 RFC 的非 ASCII 位元組進行編碼，從而使其符合 RFC 規範。

如果 unixfrom 為 True，則在根訊息物件的第一個 RFC 5322 標頭之前，列印 Unix 郵箱格式使用的信封標頭分隔符（請參閱 mailbox）。如果根物件沒有信封標頭，則建立一個標準信封標頭。預設值為 False。請注意，對於子部分，永遠不會列印信封標頭。

如果 linesep 不為 None，則將其用作平面訊息的所有行之間的分隔符。如果 linesep 為 None（預設值），則使用 policy 中指定的值。

clone(fp)

返回此 BytesGenerator 例項的獨立副本，該副本具有完全相同的選項設定，並將 fp 作為新的 outfp。

write(s)

使用 ASCII 編解碼器和 surrogateescape 錯誤處理程式對 s 進行編碼，並將其傳遞給傳遞給 BytesGenerator 建構函式的 outfp 的 write 方法。

為了方便起見，EmailMessage 提供了方法 as_bytes() 和 bytes(aMessage)（又名 __bytes__()），它們簡化了訊息物件的序列化二進位制表示的生成。有關更多詳細資訊，請參閱 email.message。

由於字串不能表示二進位制資料，因此 Generator 類必須將其平展的任何訊息中的任何二進位制資料轉換為 ASCII 相容格式，方法是將它們轉換為與 ASCII 相容的 Content-Transfer_Encoding。使用電子郵件 RFC 的術語，您可以將其視為 Generator 序列化到不是“8 位乾淨”的 I/O 流。換句話說，大多數應用程式將希望使用 BytesGenerator，而不是 Generator。

class email.generator.Generator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

返回一個 Generator 物件，該物件會將提供給 flatten() 方法的任何訊息或提供給 write() 方法的任何文字寫入到 類檔案物件 outfp。outfp 必須支援一個接受字串資料的 write 方法。

如果可選的 mangle_from_ 為 True，則在正文中任何以確切字串 "From " 開頭的行前面放置一個 > 字元，即 From 後跟一個空格，在行的開頭。mangle_from_ 預設為 policy 的 mangle_from_ 設定的值（對於 compat32 策略為 True，對於所有其他策略為 False）。mangle_from_ 旨在用於訊息以 Unix mbox 格式儲存時（請參閱 mailbox 和 為什麼內容長度格式是錯誤的）。

如果 maxheaderlen 不是 None，則重新摺疊任何長於 maxheaderlen 的標頭行，或者如果為 0，則不重新包裝任何標頭。如果 manheaderlen 為 None（預設值），則根據 policy 設定包裝標頭和其他訊息行。

如果指定了 policy，則使用該策略來控制訊息生成。如果 policy 為 None（預設值），則使用與傳遞給 flatten 的 Message 或 EmailMessage 物件關聯的策略來控制訊息生成。有關 policy 控制的詳細資訊，請參閱 email.policy。

在 3.3 版本中更改: 添加了 policy 關鍵字。

在 3.6 版本中更改: mangle_from_ 和 maxheaderlen 引數的預設行為是遵循策略。

flatten(msg, unixfrom=False, linesep=None)

將以 msg 為根的訊息物件結構的文字表示形式列印到建立 Generator 例項時指定的輸出檔案。

如果 policy 選項 cte_type 為 8bit，則生成訊息，如同該選項設定為 7bit 一樣。（這是必需的，因為字串不能表示非 ASCII 位元組。）使用 ASCII 相容的 Content-Transfer-Encoding 根據需要轉換任何高位設定的位元組。也就是說，將具有非 ASCII Content-Transfer-Encoding（Content-Transfer-Encoding: 8bit）的部分轉換為與 ASCII 相容的 Content-Transfer-Encoding，並使用 MIME unknown-8bit 字元集對標頭中不符合 RFC 的非 ASCII 位元組進行編碼，從而使其符合 RFC 規範。

如果 unixfrom 為 True，則在根訊息物件的第一個 RFC 5322 標頭之前，列印 Unix 郵箱格式使用的信封標頭分隔符（請參閱 mailbox）。如果根物件沒有信封標頭，則建立一個標準信封標頭。預設值為 False。請注意，對於子部分，永遠不會列印信封標頭。

如果 linesep 不為 None，則將其用作平面訊息的所有行之間的分隔符。如果 linesep 為 None（預設值），則使用 policy 中指定的值。

在 3.2 版本中變更: 添加了對重新編碼 8bit 訊息正文和 linesep 引數的支援。

clone(fp)

返回此 Generator 例項的獨立副本，該副本具有完全相同的選項，並將 fp 作為新的 outfp。

write(s)

將 s 寫入傳遞給 Generator 建構函式的 outfp 的 write 方法。這為 Generator 例項提供足夠的檔案類 API，以便在 print() 函式中使用。

為了方便起見，EmailMessage 提供了方法 as_string() 和 str(aMessage)（又名 __str__()），它們簡化了訊息物件的格式化字串表示的生成。有關更多詳細資訊，請參閱 email.message。

email.generator 模組還提供了一個派生類 DecodedGenerator。它與 Generator 基類類似，但不同之處在於，非 text 部分不會被序列化，而是透過一個字串表示在輸出流中，該字串源自一個模板，並使用有關該部分的資訊進行填充。

class email.generator.DecodedGenerator(outfp, mangle_from_=None, maxheaderlen=None, fmt=None, *, policy=None)

它的行為類似於 Generator，但對於傳遞給 Generator.flatten() 的訊息的任何子部分，如果該子部分的主要型別為 text，則列印該子部分的解碼有效負載；如果主要型別不是 text，則不列印，而是使用該部分的資訊填充字串 fmt，並列印填充後的字串。

為了填充 fmt，執行 fmt % part_info，其中 part_info 是一個由以下鍵和值組成的字典：

  • type – 非 text 部分的完整 MIME 型別

  • maintype – 非 text 部分的主要 MIME 型別

  • subtype – 非 text 部分的子 MIME 型別

  • filename – 非 text 部分的檔名

  • description – 與非 text 部分關聯的描述

  • encoding – 非 text 部分的內容傳輸編碼

如果 fmt 是 None，則使用以下預設 fmt

“[非文字 (%(type)s) 訊息部分已省略，檔名 %(filename)s]”

可選的 _mangle_from_ 和 maxheaderlen 與 Generator 基類相同。

腳註