"email.generator": MIME 文書の生成
**********************************

**ソースコード:** Lib/email/generator.py

======================================================================

メッセージオブジェクトの構造で表された電子メールメッセージから、フラッ
トな (直列化された) 表現を生成することは、よく行う処理の一つです。
"smtplib.SMTP.sendmail()" で送信したり、コンソールに表示したりするには
、この処理が必要です。 メッセージオブジェクトの構造を受け取り、直列化
された表現を作成するのがジェネレータークラスの役割です。

"email.parser" モジュールと同様に、付属のジェネレーターの機能だけを使
う必要はなく、自分で一から実装することもできます。 ただし、付属のジェ
ネレーターはほとんどの電子メールを標準に準拠して生成でき、MIME メッセ
ージも非 MIME メッセージも適切に扱えるはずです。 また、変換を行わない
同じ "policy" を両方に使えば、バイト列の解析と生成が互いに逆の操作にな
るよう設計されています。 つまり、直列化されたバイトストリームを
"BytesParser" で解析し、"BytesGenerator" で再生成すると、入力と同じ出
力が得られるはずです [1]。 (一方、プログラムで構築した "EmailMessage"
にジェネレーターを使うと、デフォルト値が補われる際に "EmailMessage" オ
ブジェクトが変更されることがあります。)

"Generator" クラスを使うと、メッセージをバイナリではなくテキストの直列
化表現にフラット化できます。 ただし、Unicode はバイナリデータを直接表
現できないため、メッセージを ASCII 文字だけからなる形式に変換する必要
があります。 そのために、8 ビットデータをそのまま通せない経路で電子メ
ールを送信するための、標準の電子メール RFC に定められたコンテンツ転送
エンコーディングを使います。

SMIME で署名されたメッセージを再現可能な形で処理できるよう、
"Generator" は "multipart/signed" 型のパートとそのすべてのサブパートで
、ヘッダーの折り返しを無効にします。

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

   "flatten()" に渡されたメッセージ、または "write()" に渡された
   surrogateescape でエンコードされたテキストを、*ファイルライクオブジ
   ェクト* *outfp* に書き込む "BytesGenerator" オブジェクトを返します
   。 *outfp* は、バイナリデータを受け取る "write()" メソッドを持つ必
   要があります。

   オプションの *mangle_from_* が "True" の場合、本体中で正確に文字列
   ""From "" から始まる行、つまり行頭の "From" の後に空白がある行の先
   頭に ">" を追加します。 *mangle_from_* のデフォルトは、*policy* の
   "mangle_from_" 設定の値です ("compat32" ポリシーでは "True"、それ以
   外では "False" です)。 *mangle_from_* は、メッセージを Unix mbox 形
   式で保存する場合を想定しています ("mailbox" と WHY THE CONTENT-
   LENGTH FORMAT IS BAD を参照してください)。

   If *maxheaderlen* is not "None", refold any header lines that are
   longer than *maxheaderlen*, or if "0", do not rewrap any headers.
   If *maxheaderlen* is "None" (the default), wrap headers and other
   message lines according to the *policy* settings.

   *policy* が指定されていれば、そのポリシーでメッセージの生成を制御し
   ます。 *policy* が "None" (デフォルト) であれば、"flatten()" に渡さ
   れた "Message" または "EmailMessage" オブジェクトに関連付けられたポ
   リシーを使います。 *policy* が制御する内容については "email.policy"
   を参照してください。

   Added in version 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* を持つ本文パートではそれを
      保持します。 "cte_type" が "7bit" の場合は、ASCII 互換の
      *Content-Transfer-Encoding* を使い、最上位ビットが立っているバイ
      トを必要に応じて変換します。 つまり、非 ASCII の *Content-
      Transfer-Encoding* (*Content-Transfer-Encoding: 8bit*) を持つパ
      ートを ASCII 互換の *Content-Transfer-Encoding* に変換し、ヘッダ
      ー中の RFC に反する非 ASCII バイトを MIME の "unknown-8bit" 文字
      セットでエンコードして、RFC に準拠させます。

      *unixfrom* が "True" の場合、最上位のメッセージオブジェクトの最
      初の **RFC 5322** ヘッダーより前に、Unix メールボックス形式で使
      うエンベロープヘッダーの区切りを出力します ("mailbox" を参照)。
      最上位のオブジェクトにエンベロープヘッダーがなければ、標準的なも
      のを作成します。 デフォルトは "False" です。 サブパートではエン
      ベロープヘッダーは出力されません。

      *linesep* が "None" でない場合、フラット化されたメッセージのすべ
      ての行を区切る文字として使います。 *linesep* が "None" (デフォル
      ト) の場合、*policy* で指定された値を使います。

   clone(fp)

      この "BytesGenerator" インスタンスとまったく同じオプション設定で
      、新しい *outfp* を *fp* とした、独立した複製を返します。

   write(s)

      *s* を "ASCII" コーデックと "surrogateescape" エラーハンドラーで
      エンコードし、"BytesGenerator" のコンストラクタに渡された
      *outfp* の "write()" メソッドに渡します。

"EmailMessage" には、メッセージオブジェクトを直列化したバイナリ表現を
簡単に生成するための "as_bytes()" と "bytes(aMessage)" (すなわち
"__bytes__()") が用意されています。 詳しくは "email.message" を参照し
てください。

Because strings cannot represent binary data, the "Generator" class
must convert any binary data in any message it flattens to an ASCII
compatible format, by converting them to an ASCII compatible *Content-
Transfer-Encoding*.  Using the terminology of the email RFCs, you can
think of this as "Generator" serializing to an I/O stream that is not
"8 bit clean".  In other words, most applications will want to be
using "BytesGenerator", and not "Generator".

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

   "flatten()" に渡されたメッセージ、または "write()" に渡されたテキス
   トを、*ファイルライクオブジェクト* *outfp* に書き込む "Generator"
   オブジェクトを返します。 *outfp* は、文字列データを受け取る
   "write()" メソッドを持つ必要があります。

   オプションの *mangle_from_* が "True" の場合、本体中で正確に文字列
   ""From "" から始まる行、つまり行頭の "From" の後に空白がある行の先
   頭に ">" を追加します。 *mangle_from_* のデフォルトは、*policy* の
   "mangle_from_" 設定の値です ("compat32" ポリシーでは "True"、それ以
   外では "False" です)。 *mangle_from_* は、メッセージを Unix mbox 形
   式で保存する場合を想定しています ("mailbox" と WHY THE CONTENT-
   LENGTH FORMAT IS BAD を参照してください)。

   If *maxheaderlen* is not "None", refold any header lines that are
   longer than *maxheaderlen*, or if "0", do not rewrap any headers.
   If *maxheaderlen* is "None" (the default), wrap headers and other
   message lines according to the *policy* settings.

   *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* に変換し、ヘッダー中の RFC に反する
      非 ASCII バイトを MIME の "unknown-8bit" 文字セットでエンコード
      して、RFC に準拠させます。

      *unixfrom* が "True" の場合、最上位のメッセージオブジェクトの最
      初の **RFC 5322** ヘッダーより前に、Unix メールボックス形式で使
      うエンベロープヘッダーの区切りを出力します ("mailbox" を参照)。
      最上位のオブジェクトにエンベロープヘッダーがなければ、標準的なも
      のを作成します。 デフォルトは "False" です。 サブパートではエン
      ベロープヘッダーは出力されません。

      *linesep* が "None" でない場合、フラット化されたメッセージのすべ
      ての行を区切る文字として使います。 *linesep* が "None" (デフォル
      ト) の場合、*policy* で指定された値を使います。

      バージョン 3.2 で変更: "8bit" メッセージ本体の再エンコードがサポ
      ートされました。*linesep* 引数が追加されました。

   clone(fp)

      この "Generator" インスタンスとまったく同じオプションで、新しい
      *outfp* を *fp* とした、独立した複製を返します。

   write(s)

      "Generator" のコンストラクタに渡された *outfp* の "write()" メソ
      ッドに *s* を書き込みます。 これにより、"Generator" インスタンス
      を "print()" 関数で使うために必要な、最小限のファイルライク API
      を提供します。

"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* 型 subpart の MIME 形式

   * "maintype" -- 非 *text* 型 subpart の MIME 主形式 (maintype)

   * "subtype" -- 非 *text* 型 subpart の MIME 副形式 (subtype)

   * "filename" -- 非 *text* 型 subpart のファイル名

   * "description" -- 非 *text* 型 subpart につけられた説明文字列

   * "encoding" -- 非 *text* 型 subpart の Content-transfer-encoding

   *fmt* が "None" の場合、次のデフォルトの *fmt* を使います。

      "[Non-text (%(type)s) part of message omitted, filename
      %(filename)s]"

   Optional *mangle_from_* and *maxheaderlen* are as with the
   "Generator" base class.

-[ 脚注 ]-

[1] この説明は、"unixfrom" が適切に設定され、"email.policy" に自動調整
    を要求する設定がないことを前提としています (例えば "refold_source"
    は "none" でなければなりませんが、これはデフォルトでは *ありません
    *)。 また、メッセージが RFC に準拠していないと、解析エラーからの回
    復中に元のテキストの正確な情報が失われることがあるため、常に成り立
    つわけでもありません。 このような例外的な場合は、可能な限り修正し
    ていくことを目指しています。
