This document is for an old version of Python that is no longer supported. You should upgrade and read the Python documentation for the current stable release.

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