email.header ：国際化されたヘッダー
ソースコード： ：source： `Lib / email / header.py`
このモジュールは、レガシー（Compat32）電子メールAPIの一部です。 現在のAPIでは、ヘッダーのエンコードとデコードは、 EmailMessage クラスの辞書のようなAPIによって透過的に処理されます。 このモジュールは、レガシーコードでの使用に加えて、ヘッダーのエンコード時に使用される文字セットを完全に制御する必要があるアプリケーションで役立ちます。
このセクションの残りのテキストは、モジュールの元のドキュメントです。
RFC 2822 は、電子メールメッセージの形式を説明する基本標準です。 これは、ほとんどの電子メールがASCII文字のみで構成されていたときに広く使用されるようになった古い RFC 822 標準から派生しています。 RFC 2822 は、電子メールに7ビットのASCII文字のみが含まれていることを前提に記述された仕様です。
もちろん、電子メールは世界中で展開されているため、国際化されており、言語固有の文字セットを電子メールメッセージで使用できるようになっています。 基本標準では、7ビットのASCII文字のみを使用して電子メールメッセージを転送する必要があるため、非ASCII文字を含む電子メールを RFC 2822 [X226Xにエンコードする方法を説明するRFCが多数作成されています。 ]準拠の形式。 これらのRFCには、 RFC 2045 、 RFC 2046 、 RFC 2047 、および[ X107X] RFC 2231 。 email パッケージは、 email.header および email.charset モジュールでこれらの標準をサポートしています。
Subject または To フィールドなど、電子メールヘッダーに非ASCII文字を含める場合は、 Header クラスを使用してフィールドを割り当てる必要があります。 Message オブジェクトで、ヘッダー値に文字列を使用する代わりに、 Header のインスタンスに追加します。 email.header モジュールから Header クラスをインポートします。 例えば：
>>> from email.message import Message
>>> from email.header import Header
>>> msg = Message()
>>> h = Header('p\xf6stal', 'iso-8859-1')
>>> msg['Subject'] = h
>>> msg.as_string()
'Subject: =?iso-8859-1?q?p=F6stal?=\n\n'ここで、 Subject フィールドに非ASCII文字を含める方法に注目してください。 これを行うには、 Header インスタンスを作成し、バイト文字列がエンコードされた文字セットを渡します。 後続の Message インスタンスがフラット化されると、 Subject フィールドは適切に RFC 2047 でエンコードされました。 MIME対応のメールリーダーは、埋め込まれたISO-8859-1文字を使用してこのヘッダーを表示します。
Header クラスの説明は次のとおりです。
- class email.header.Header(s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict')
さまざまな文字セットの文字列を含めることができるMIME準拠のヘッダーを作成します。
オプションの s は初期ヘッダー値です。
None（デフォルト）の場合、初期ヘッダー値は設定されません。 後で append（）メソッド呼び出しを使用してヘッダーに追加できます。 s は bytes または str のインスタンスである可能性がありますが、セマンティクスについては append（）のドキュメントを参照してください。オプションの charset には、2つの目的があります。 append（）メソッドの charset 引数と同じ意味です。 また、 charset 引数を省略した後続のすべての append（）呼び出しのデフォルトの文字セットを設定します。 charset がコンストラクターで指定されていない場合（デフォルト）、
us-ascii文字セットは s の初期文字セットと後続の[のデフォルトの両方として使用されます。 X177X] append（）呼び出し。最大行長は、 maxlinelen を介して明示的に指定できます。 最初の行をより短い値に分割する場合（ s に含まれていないフィールドヘッダーを考慮して、たとえば Subject ） header_name のフィールドの名前を渡します。 デフォルトの maxlinelen は76で、 header_name のデフォルト値は
Noneです。これは、長い分割ヘッダーの最初の行では考慮されないことを意味します。オプションの continuation_ws は、 RFC 2822 準拠の折りたたみ空白である必要があり、通常はスペースまたはハードタブ文字のいずれかです。 この文字は継続行の前に付けられます。 continuation_ws のデフォルトは単一のスペース文字です。
オプションのエラーは、 append（）メソッドに直接渡されます。
- append(s, charset=None, errors='strict')
文字列 s をMIMEヘッダーに追加します。
オプションの charset は、指定されている場合、 Charset インスタンス（ email.charset を参照）または文字セットの名前である必要があります。これは[ X165X] Charset インスタンス。
None（デフォルト）の値は、コンストラクターで指定された charset が使用されることを意味します。s は、 bytes または str のインスタンスである可能性があります。 bytes のインスタンスの場合、 charset はそのバイト文字列のエンコーディングであり、文字列をそれでデコードできない場合は UnicodeError が発生します。キャラクターセット。
s が str のインスタンスである場合、 charset は文字列内の文字の文字セットを指定するヒントです。
いずれの場合も、 RFC 2047 ルールを使用して RFC 2822 準拠のヘッダーを生成する場合、文字列は出力コーデックを使用してエンコードされます。文字セットの。 出力コーデックを使用して文字列をエンコードできない場合、UnicodeErrorが発生します。
オプションの errors は、 s がバイト文字列の場合、デコード呼び出しのエラー引数として渡されます。
- encode(splitchars=';, \\t', maxlinelen=None, linesep='\\n')
メッセージヘッダーをRFC準拠の形式にエンコードします。長い行を折り返し、非ASCII部分をbase64またはquoted-printableエンコードでカプセル化することもできます。
オプションの splitchars は、通常のヘッダーの折り返し中に分割アルゴリズムによって追加の重みを与える必要がある文字を含む文字列です。 これは、 RFC 2822 'の「高レベルの構文ブレーク」を非常に大まかにサポートしています。行分割時には、splitcharが前に付いた分割ポイントが優先され、文字列に表示される順序。 スペースとタブを文字列に含めて、分割される行に他の分割文字が表示されない場合に、分割ポイントとして一方を他方よりも優先するかどうかを示すことができます。 Splitcharsは、 RFC 2047 でエンコードされた行には影響しません。
maxlinelen が指定されている場合、最大行長のインスタンスの値をオーバーライドします。
linesep は、折りたたまれたヘッダーの行を区切るために使用される文字を指定します。 デフォルトではPythonアプリケーションコードの最も有用な値（
\n）になりますが、RFC準拠の行区切り記号を使用してヘッダーを生成するために\r\nを指定できます。バージョン3.2で変更： linesep 引数が追加されました。
Header クラスは、標準の演算子と組み込み関数をサポートするための多数のメソッドも提供します。
- __str__()
無制限の行長を使用して、 Header の近似値を文字列として返します。 すべてのピースは、指定されたエンコーディングを使用してユニコードに変換され、適切に結合されます。
'unknown-8bit'の文字セットを持つすべてのピースは、'replace'エラーハンドラーを使用してASCIIとしてデコードされます。バージョン3.2で変更：
'unknown-8bit'文字セットの処理が追加されました。
- __eq__(other)
このメソッドを使用すると、2つの Header インスタンスが等しいかどうかを比較できます。
- __ne__(other)
このメソッドを使用すると、2つの Header インスタンスの不平等を比較できます。
email.header モジュールは、次の便利な機能も提供します。
- email.header.decode_header(header)
文字セットを変換せずにメッセージヘッダー値をデコードします。 ヘッダー値は header にあります。
この関数は、ヘッダーのデコードされた各部分を含む
(decoded_string, charset)ペアのリストを返します。 charset はヘッダーのエンコードされていない部分のNoneです。それ以外の場合は、エンコードされた文字列で指定された文字セットの名前を含む小文字の文字列です。次に例を示します。
>>> from email.header import decode_header >>> decode_header('=?iso-8859-1?q?p=F6stal?=') [(b'p\xf6stal', 'iso-8859-1')]
- email.header.make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')
decode_header（）によって返されるペアのシーケンスから Header インスタンスを作成します。
decode_header（）はヘッダー値の文字列を受け取り、
(decoded_string, charset)形式のペアのシーケンスを返します。 charset は文字セットの名前です。この関数は、これらのペアのシーケンスの1つを取り、 Header インスタンスを返します。 オプションの maxlinelen 、 header_name 、および continuation_ws は、 Header コンストラクターと同じです。
