# `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'

Notice here how we wanted the Subject field to contain a non-ASCII character? We did this by creating a `Header` instance and passing in the character set to use when encoding it. When the subsequent `Message` instance was flattened, the Subject field was properly RFC 2047 encoded. MIME-aware mail readers would show this header using the embedded ISO-8859-1 character.

以下は `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__()

    Returns an approximation of the `Header` as a string, using an unlimited line length. All pieces are decoded using the specified encoding and joined together appropriately. Any pieces with a charset of `'unknown-8bit'` are decoded as ASCII using the `'replace'` error handler.

    バージョン 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.