"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 準拠なヘッダを作成します。

   Optional *s* is the initial header value.  If "None" (the default),
   the initial header value is not set.  You can later append to the
   header with "append()" method calls.  *s* may be a byte string or a
   Unicode string, but see the "append()" documentation for semantics.

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

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

   Optional *continuation_ws* must be **RFC 2822**-compliant folding
   whitespace, and is usually either a space or a hard tab character.
   This character will be prepended to continuation lines.
   *continuation_ws* defaults to a single space character (」 「).

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

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

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

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

      *s* may be a byte string or a Unicode string.  If it is a byte
      string (i.e.  "isinstance(s, str)" is true), then *charset* is
      the encoding of that byte string, and a "UnicodeError" will be
      raised if the string cannot be decoded with that character set.

      If *s* is a Unicode string, then *charset* is a hint specifying
      the character set of the characters in the string.  In this
      case, when producing an **RFC 2822**-compliant header using
      **RFC 2047** rules, the Unicode string will be encoded using the
      following charsets in order: "us-ascii", the *charset* hint,
      "utf-8".  The first character set to not provoke a
      "UnicodeError" is used.

      Optional *errors* is passed through to any "unicode()" or
      "unicode.encode()" call, and defaults to 「strict」.

   encode([splitchars])

      Encode a message header into an RFC-compliant format, possibly
      wrapping long lines and encapsulating non-ASCII parts in base64
      or quoted-printable encodings.  Optional *splitchars* is a
      string containing characters to split long ASCII lines on, in
      rough support of **RFC 2822**’s *highest level syntactic
      breaks*.  This doesn’t affect **RFC 2047** encoded lines.

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

   __str__()

      A synonym for "Header.encode()".  Useful for "str(aHeader)".

   __unicode__()

      A helper for the built-in "unicode()" function.  Returns the
      header as a Unicode string.

   __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" コンストラクタに与えるものと同じです
   。
