"email.header": Internationalized headers
*****************************************

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

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

このモジュールはレガシー("Compat32")な電子メールAPIの一部です。現在の
APIではヘッダのエンコードとデコードは "EmailMessage" クラスの辞書的な
APIによって透過的に処理されます。レガシーコードでの使用に加えて、この
モジュールは、ヘッダーをエンコードする際に使用される文字セットを完全に
制御する必要があるアプリケーションで役立ちます

この節の以降のテキストはモジュールの元々のドキュメントです。

**RFC 2822** は電子メールメッセージの形式を規定する基本規格です。これ
はほとんどの電子メールが ASCII 文字のみで構成されていたころ普及した
**RFC 822** 標準から発展したものです。 **RFC 2822** は電子メールがすべ
て 7-bit ASCII 文字のみから構成されていると仮定して作られた仕様です。

もちろん、電子メールが世界的に普及するにつれ、この仕様は国際化されてき
ました。今では電子メールに言語依存の文字集合を使うことができます。基本
規格では、まだ電子メールメッセージを 7-bit ASCII 文字のみを使って転送
するよう要求していますので、多くの RFC でどうやって非ASCII の電子メー
ルを **RFC 2822** 準拠な形式にエンコードするかが記述されています。これ
らの RFC は以下のものを含みます: **RFC 2045** 、 **RFC 2046** 、 **RFC
2047** 、および **RFC 2231** 。 "email" パッケージは、 "email.header"
および "email.charset" モジュールでこれらの規格をサポートしています。

ご自分の電子メールヘッダ、たとえば *Subject* や *To* などのフィールド
に非ASCII文字を入れたい場合、 "Header" クラスを使う必要があります。
"Message" オブジェクトの該当フィールドに文字列ではなく、 "Header" イン
スタンスを使うのです。 "Header" クラスは "email.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* が与えられない場合 (デフォルト)、初期値の *s* および
   以後の "append()" 呼び出しにおける文字集合として "us-ascii" が使わ
   れます。

   The maximum line length can be specified explicitly via
   *maxlinelen*.  For splitting the first line to a shorter value (to
   account for the field header which isn't included in *s*, e.g.
   *Subject*) pass in the name of the field in *header_name*.  The
   default *maxlinelen* is 76, and the default value for *header_name*
   is "None", meaning it is not taken into account for the first line
   of a long, split header.

   オプション引数 *continuation_ws* は **RFC 2822** 準拠の折り返し用余
   白文字で、ふつうこれは空白か、ハードタブ文字 (hard tab) である必要
   があります。ここで指定された文字は複数にわたる行の行頭に挿入されま
   す。 *continuation_ws* のデフォルト値は 1 つのスペース文字です。

   オプション引数 *errors* は、 "append()" メソッドにそのまま渡されま
   す。

   append(s, charset=None, errors='strict')

      この MIME ヘッダに文字列 *s* を追加します。

      オプション引数 *charset* がもし与えられた場合、これは "Charset"
      インスタンス ("email.charset" を参照) か、あるいは文字集合の名前
      でなければなりません。この場合は "Charset" インスタンスに変換さ
      れます。この値が "None" の場合 (デフォルト)、コンストラクタで与
      えられた *charset* が使われます。

      *s* は "bytes" または "str" のインスタンスです。 "bytes" のイン
      スタンスの場合、 *charset* はその文字列のエンコーディングであり
      、この文字セットでデコードできないときは "UnicodeError" が発生し
      ます。

      *s* が "str" のインスタンスの場合、 *charset* はその文字列の文字
      セットを決定するためのヒントとして使われます。

      いずれの場合でも、 **RFC 2822** 準拠のヘッダを **RFC 2047** の規
      則を用いて生成する際、文字列は指定された文字セットの出力コーデッ
      クを用いてエンコードされます。出力コーデックを用いて文字列がエン
      コードできないときは "UnicodeError" が発生します。

      オプションの *errors* は、 *s* がバイト文字列だった場合のデコー
      ド呼び出しに errors 引数として渡されます。

   encode(splitchars=';, \t', maxlinelen=None, linesep='\n')

      メッセージヘッダを RFC に沿ったやり方でエンコードします。おそら
      く長い行は折り返され、非 ASCII 部分は base64 または quoted-
      printable エンコーディングで包含されるでしょう。

      オプション引数 *splitchars* は、通常のヘッダーの折り返し処理の間
      に分割アルゴリズムによって特別な重みが与えられるべき文字を含む文
      字列です。これは、 **RFC 2822** の 'higher level syntactic
      breaks' の非常に荒いサポートです: splitchar の後の分割点は、行分
      割において優先されます。 分割文字は文字列中での出現順に優先され
      ます。スペースとタブは、分割しようとする行に他の分割文字が出現し
      ない時に、分割点として他の文字と比べてどのような優先順位が与えら
      れるべきかを示すために、文字列に含めることができます。
      Splitchars は **RFC 2047** エンコードされた行には影響しません。

      与えられた場合、*maxlinelen* はインスタンスの最大行長の値を上書
      きします。

      *linesep* は、折り返しヘッダの行を区切る文字を指定します。デフォ
      ルトではPythonアプリケーションコードに最も有用な値("\n")になりま
      すが、RFC準拠の行区切り文字でヘッダを生成するために``rn``を指定
      することができます。

      バージョン 3.2 で変更: *linesep* 引数が追加されました。

   "Header" クラスは、標準の演算子や組み込み関数をサポートするためのメ
   ソッドもいくつか提供しています。

   __str__()

      "Header" の概要を文字列として返します。無制限の行長を使用します
      。すべての箇所は、指定されたエンコーディングを使用してUnicodeに
      変換され、適切に結合されます。文字セット "'unknown-8bit'" を持つ
      箇所は、 "'replace'" エラーハンドラを使ってASCIIとしてデコードさ
      れます。

      バージョン 3.2 で変更: "'unknown-8bit'" 文字集合の処理が追加され
      ました。

   __eq__(other)

      このメソッドは、ふたつの "Header" インスタンスどうしが等しいかど
      うか判定するのに使えます。

   __ne__(other)

      このメソッドは、ふたつの "Header" インスタンスどうしが異なってい
      るかどうかを判定するのに使えます。

さらに、 "email.header" モジュールは以下のような簡易関数も提供していま
す。

email.header.decode_header(header)

   文字集合を変換せずにメッセージのヘッダをデコードします。ヘッダの値
   は *header* にあります。

   この関数はヘッダのそれぞれのデコードされた部分ごとに、
   "(decoded_string, charset)" という形式の 2要素タプルからなるリスト
   を返します。*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()" によって返される 2要素タプルのリストから "Header"
   インスタンスを作成します。

   "decode_header()" はヘッダの値をとってきて、 "(decoded_string,
   charset)" という形式の 2要素タプルからなるリストを返します。ここで
   *decoded_string* はデコードされた文字列、 *charset* はその文字集合
   です。

   この関数はこれらのリストの項目から、 "Header" インスタンスを返しま
   す。オプション引数 *maxlinelen* 、 *header_name* および
   *continuation_ws* は "Header" コンストラクタに与えるものと同じです
   。
