19.1.3. email.generator:MIMEドキュメントの生成—Pythonドキュメント
19.1.3。 email.generator :MIMEドキュメントの生成
ソースコード: :source: `Lib / email / generator.py`
最も一般的なタスクの1つは、メッセージオブジェクト構造で表されるフラット(シリアル化)バージョンの電子メールメッセージを生成することです。 smtplib.SMTP.sendmail()または nntplib モジュールを介してメッセージを送信する場合、またはコンソールにメッセージを印刷する場合は、これを行う必要があります。 メッセージオブジェクト構造を取得し、シリアル化された表現を生成することは、ジェネレータクラスの仕事です。
email.parser モジュールと同様に、バンドルされたジェネレーターの機能に制限されません。 自分で一から書くことができます。 ただし、バンドルされたジェネレーターは、ほとんどの電子メールを標準に準拠した方法で生成する方法を知っており、MIMEおよび非MIMEの電子メールメッセージを適切に処理する必要があり、バイト指向の解析および生成操作が逆になるように設計されています。変換ポリシーは両方に使用されます。 つまり、 BytesParser クラスを介してシリアル化されたバイトストリームを解析し、 BytesGenerator を使用してシリアル化されたバイトストリームを再生成すると、入力 1 と同じ出力が生成されます。 (一方、プログラムによって構築された EmailMessage でジェネレーターを使用すると、デフォルトが入力されているため、 EmailMessage オブジェクトが変更される可能性があります。)
Generator クラスを使用すると、メッセージを(バイナリではなく)テキストのシリアル化された表現にフラット化できますが、Unicodeはバイナリデータを直接表現できないため、メッセージは必然的にASCII文字のみを含むものに変換されます。 、「8ビットクリーン」ではないチャネルを介した転送用の電子メールメッセージをエンコードするための標準の電子メールRFCコンテンツ転送エンコード技術を使用します。
- class email.generator.BytesGenerator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)
flatten()メソッドに提供されたメッセージ、または write()メソッドに提供された代理エスケープエンコードテキストを書き込む BytesGenerator オブジェクトをに返します。 ファイルのようなオブジェクト outfp 。 outfp は、バイナリデータを受け入れる
write
メソッドをサポートする必要があります。オプションの mangle_from_ が
True
の場合、正確な文字列"From "
で始まる本文の行の前に、>
文字を配置します。 X160X] の後に行頭にスペースが続きます。 mangle_from_ は、デフォルトでポリシーのmangle_from_
設定の値になります( compat32 ポリシーおよび compat32 ポリシーの場合はTrue
です。他のすべての場合はX149X] )。 mangle_from_ は、メッセージがUNIXのmbox形式で保存されている場合に使用することを目的としています(メールボックスおよびコンテンツの長さの形式が不適切な理由を参照)。maxheaderlen が
None
でない場合は、 maxheaderlen より長いヘッダー行を折りたたむか、0
の場合はヘッダーを再折り返しません。 manheaderlen がNone
(デフォルト)の場合、ポリシーの設定に従ってヘッダーやその他のメッセージ行を折り返します。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 を保持します。cte_type
が7bit
の場合、ASCII互換の Content-Transfer-Encoding を使用して、必要に応じて上位ビットが設定されたバイトを変換します。 つまり、非ASCII Content-Transfer-Encoding ( Content-Transfer-Encoding:8bit )のパーツをASCII互換の Content-Transfer-Encoding に変換します。 、およびMIMEunknown-8bit
文字セットを使用してヘッダー内のRFC無効な非ASCIIバイトをエンコードし、RFC準拠にします。unixfrom が
True
の場合、 の最初の前に、Unixメールボックス形式(メールボックスを参照)で使用される封筒ヘッダー区切り文字を印刷します。 ]ルートメッセージオブジェクトのRFC5322 ヘッダー。 ルートオブジェクトにエンベロープヘッダーがない場合は、標準のヘッダーを作成します。 デフォルトはFalse
です。 サブパーツの場合、エンベロープヘッダーは印刷されないことに注意してください。linesep が
None
でない場合は、フラット化されたメッセージのすべての行の間の区切り文字として使用します。 linesep がNone
(デフォルト)の場合、ポリシーで指定された値を使用します。
- clone(fp)
この BytesGenerator インスタンスの独立したクローンを、まったく同じオプション設定で返し、 fp を新しい outfp として返します。
- write(s)
ASCII
コーデックとsurrogateescape
エラーハンドラーを使用して s をエンコードし、 outfp の write メソッドに渡します。 BytesGenerator のコンストラクターに渡されます。
便宜上、 EmailMessage はメソッド as_bytes()およびbytes(aMessage)
(別名 __ bytes __())。これにより、メッセージオブジェクトのシリアル化されたバイナリ表現の生成が簡素化されます。 詳細については、 email.message を参照してください。
文字列はバイナリデータを表すことができないため、 Generator クラスは、フラット化するメッセージ内のバイナリデータを、ASCII互換の Content-Transfer_Encoding に変換することにより、ASCII互換形式に変換する必要があります。 電子メールRFCの用語を使用すると、これは Generator が「8ビットクリーン」ではないI / Oストリームにシリアル化されていると考えることができます。 つまり、ほとんどのアプリケーションは、 Generator ではなく、 BytesGenerator を使用する必要があります。
- class email.generator.Generator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)
flatten()メソッドに提供されたメッセージ、または write()メソッドに提供されたテキストをに書き込む Generator オブジェクトを返します。 ]ファイルのようなオブジェクト outfp 。 outfp は、文字列データを受け入れる
write
メソッドをサポートする必要があります。オプションの mangle_from_ が
True
の場合、正確な文字列"From "
で始まる本文の行の前に、>
文字を配置します。 X160X] の後に行頭にスペースが続きます。 mangle_from_ は、デフォルトでポリシーのmangle_from_
設定の値になります( compat32 ポリシーおよび compat32 ポリシーの場合はTrue
です。他のすべての場合はX149X] )。 mangle_from_ は、メッセージがUNIXのmbox形式で保存されている場合に使用することを目的としています(メールボックスおよびコンテンツの長さの形式が不適切な理由を参照)。maxheaderlen が
None
でない場合は、 maxheaderlen より長いヘッダー行を折りたたむか、0
の場合はヘッダーを再折り返しません。 manheaderlen がNone
(デフォルト)の場合、ポリシーの設定に従ってヘッダーやその他のメッセージ行を折り返します。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 Cotnent-Transfer-Encoding ( Content-Transfer-Encoding:8bit )のパーツをASCII互換の Content-Transfer-Encoding に変換します。 、およびMIMEunknown-8bit
文字セットを使用してヘッダー内のRFC無効な非ASCIIバイトをエンコードし、RFC準拠にします。unixfrom が
True
の場合、 の最初の前に、Unixメールボックス形式(メールボックスを参照)で使用される封筒ヘッダー区切り文字を印刷します。 ]ルートメッセージオブジェクトのRFC5322 ヘッダー。 ルートオブジェクトにエンベロープヘッダーがない場合は、標準のヘッダーを作成します。 デフォルトはFalse
です。 サブパーツの場合、エンベロープヘッダーは印刷されないことに注意してください。linesep が
None
でない場合は、フラット化されたメッセージのすべての行の間の区切り文字として使用します。 linesep がNone
(デフォルト)の場合、ポリシーで指定された値を使用します。バージョン3.2で変更:
8bit
メッセージ本文の再エンコード、および linesep 引数のサポートが追加されました。
- clone(fp)
この Generator インスタンスの独立したクローンを、まったく同じオプションで返し、 fp を新しい outfp として返します。
便宜上、 EmailMessage はメソッド as_string()およびstr(aMessage)
(別名 __ str __())。これにより、メッセージオブジェクトのフォーマットされた文字列表現の生成が簡素化されます。 詳細については、 email.message を参照してください。
email.generator モジュールは、派生クラス DecodedGenerator も提供します。これは、非 text を除いて、 Generator 基本クラスに似ています。パーツはシリアル化されませんが、代わりに、パーツに関する情報が入力されたテンプレートから派生した文字列によって出力ストリームで表されます。
- 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
–非テキスト部分の完全なMIMEタイプmaintype
–非テキスト部分のメインMIMEタイプsubtype
–非テキスト部分のサブMIMEタイプfilename
–非テキスト部分のファイル名description
–非テキスト部分に関連付けられた説明encoding
–非テキスト部分のコンテンツ転送エンコーディング
fmt が
None
の場合、次のデフォルトの fmt を使用します。「[メッセージの非テキスト(%(type)s)部分が省略され、ファイル名%(filename)s]」
オプションの _mangle_from_ および maxheaderlen は、 Generator 基本クラスと同じです。
脚注
- 1
- このステートメントは、
unixfrom
に適切な設定を使用し、自動調整を必要とするpolicy
設定がないことを前提としています(たとえば、refold_source
はnone
である必要があります]、これはデフォルトではありません)。 また、メッセージがRFC標準に準拠していない場合、解析エラーの回復中に正確な元のテキストに関する情報が失われることがあるため、100%真実ではありません。 可能であれば、これらの後者のエッジケースを修正することが目標です。