18.1.5. "email.header": 国際化されたヘッダ
******************************************

**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
   >>> print msg.as_string()
   Subject: =?iso-8859-1?q?p=F6stal?=

*Subject* フィールドに非ASCII文字をふくめていることに注目してください
。ここでは、含めたいバイト列がエンコードされている文字セットを指定して
"Header" インスタンスを作成することによって実現しています。のちにこの
"Message" インスタンスからフラットなテキストを生成するさいに、この
*Subject* フィールドは **RFC 2047** 準拠の適切な形式にエンコードされま
す。MIME 機能のついているメーラなら、このヘッダに埋めこまれた
ISO-8859-1 文字をただしく表示するでしょう。

バージョン 2.2.2 で追加.

以下は "Header" クラスの説明です:

class email.header.Header([s[, charset[, maxlinelen[, header_name[, continuation_ws[, errors]]]]]])

   別の文字セットの文字列をふくむ MIME準拠なヘッダを作成します。

   オプション引数 *s* はヘッダの値の初期値です。これが "None" の場合 (
   デフォルト)、ヘッダの初期値は設定されません。この値はあとから
   "append()" メソッドを呼びだすことによって追加することができます。
   *s* はバイト文字列か、あるいは Unicode 文字列でもかまいませんが、こ
   の意味については "append()" の項を参照してください。

   オプション引数 *charset* には 2つの目的があります。ひとつは
   "append()" メソッドにおける *charset* 引数と同じものです。もうひと
   つの目的は、これ以降 *charset* 引数を省略した "append()" メソッド呼
   び出しすべてにおける、デフォルト文字セットを決定するものです。コン
   ストラクタに *charset* が与えられない場合 (デフォルト)、初期値の
   *s* および以後の "append()" 呼び出しにおける文字セットとして "us-
   ascii" が使われます。

   行の最大長は *maxlinelen* によって明示的に指定できます。最初の行を
   (*Subject* などの *s* に含まれないフィールドヘッダの責任をとるため)
   短く切りとる場合、 *header_name* にそのフィールド名を指定してくださ
   い。 *maxlinelen* のデフォルト値は 76 であり、 *header_name* のデフ
   ォルト値は "None" です。これはその最初の行を長い、切りとられたヘッ
   ダとして扱わないことを意味します。

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

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

   append(s[, charset[, errors]])

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

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

      *s* はバイト文字列か、Unicode 文字列です。これがバイト文字列
      ("isinstance(s, str)" が真) の場合、 *charset* はその文字列のエ
      ンコーディングであり、これが与えられた文字セットでうまくデコード
      できないときは "UnicodeError" が発生します。

      一方 *s* が Unicode 文字列の場合、 *charset* はその文字列の文字
      セットを決定するためのヒントとして使われます。この場合、 **RFC
      2822** 準拠のヘッダを **RFC 2047** の規則を用いて生成する際、
      Unicode 文字列は以下の文字セットを (この優先順位で) 適用してエン
      コードされます: "us-ascii" 、 *charset* で与えられたヒント、それ
      もなければ "utf-8" 。最初の文字セットは "UnicodeError" をなるべ
      く防ぐために使われます。

      オプション引数 *errors* は "unicode()" または "unicode.encode()"
      の呼び出し時に使用し、デフォルト値は "strict" です。

   encode([splitchars])

      メッセージヘッダを RFC に沿ったやり方でエンコードします。おそら
      く長い行は折り返され、非 ASCII 部分は base64 または quoted-
      printable エンコーディングで包含されるでしょう。オプション引数
      *splitchars* には長い ASCII 行を分割する区切り文字群を文字列とし
      て指定し、 **RFC 2822** の *highest level syntactic breaks* の大
      まかなサポートの為に使用します。この引数は **RFC 2047** でエンコ
      ードされた行には影響しません。

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

   __str__()

      "Header.encode()" と同じです。 "str(aHeader)" などとすると有用で
      しょう。

   __unicode__()

      組み込みの "unicode()" 関数の補助です。ヘッダを Unicode 文字列と
      して返します。

   __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?=')
      [('p\xf6stal', 'iso-8859-1')]

email.header.make_header(decoded_seq[, maxlinelen[, header_name[, continuation_ws]]])

   "decode_header()" によって返される 2要素タプルのリストから "Header"
   インスタンスを作成します。

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

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