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

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

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

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

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

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

Of course, as email has been deployed worldwide, it has become
internationalized, such that language specific character sets can now
be used in email messages.  The base standard still requires email
messages to be transferred using only 7-bit ASCII characters, so a
slew of RFCs have been written describing how to encode email
containing non-ASCII characters into **RFC 2822**-compliant format.
These RFCs include **RFC 2045**, **RFC 2046**, **RFC 2047**, and **RFC
2231**. The "email" package supports these standards in its
"email.header" and "email.charset" modules.

If you want to include non-ASCII characters in your email headers, say
in the *Subject* or *To* fields, you should use the "Header" class and
assign the field in the "Message" object to an instance of "Header"
instead of using a string for the header value.  Import the "Header"
class from the "email.header" module. For example:

   >>> 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" が使わ
   れます。

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

   オプション引数 *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" インスタンスどうしが異なってい
      るかどうかを判定するのに使えます。

The "email.header" module also provides the following convenient
functions.

email.header.decode_header(header)

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

   For historical reasons, this function may return either:

   1. A list of pairs containing each of the decoded parts of the
      header, "(decoded_bytes, charset)", where *decoded_bytes* is
      always an instance of "bytes", and *charset* is either:

         * A lower case string containing the name of the character
           set specified.

         * "None" for non-encoded parts of the header.

   2. A list of length 1 containing a pair "(string, None)", where
      *string* is always an instance of "str".

   An "email.errors.HeaderParseError" may be raised when certain
   decoding errors occur (e.g. a base64 decoding exception).

   Here are examples:

   >>> from email.header import decode_header
   >>> decode_header('=?iso-8859-1?q?p=F6stal?=')
   [(b'p\xf6stal', 'iso-8859-1')]
   >>> decode_header('unencoded_string')
   [('unencoded_string', None)]
   >>> decode_header('bar =?utf-8?B?ZsOzbw==?=')
   [(b'bar ', None), (b'f\xc3\xb3o', 'utf-8')]

   注釈:

     This function exists for backwards compatibility only. For new
     code, we recommend using "email.headerregistry.HeaderRegistry".

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

   注釈:

     This function exists for backwards compatibility only, and is not
     recommended for use in new code.
