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

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

もちろん、電子メールが世界的に普及するにつれ、この仕様は国際化されてきました。今では電子メールに言語依存の文字セットを使うことができます。基本規格では、まだ電子メールメッセージを 7-bit ASCII 文字のみを使って転送するよう要求していますので、多くの RFC でどうやって非ASCII の電子メールを RFC 2822 準拠な形式にエンコードするかが記述されています。これらの RFC は以下のものを含みます: RFC 2045RFC 2046RFC 2047 、および RFC 2231email パッケージは、 email.header および email.charset モジュールでこれらの規格をサポートしています。

ご自分の電子メールヘッダ、たとえば SubjectTo などのフィールドに非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_wsRFC 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-asciicharset で与えられたヒント、それもなければ utf-8 。最初の文字セットは UnicodeError をなるべく防ぐために使われます。

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

encode([splitchars])

メッセージヘッダを RFC に沿ったやり方でエンコードします。おそらく長い行は折り返され、非 ASCII 部分は base64 または quoted-printable エンコーディングで包含されるでしょう。オプション引数 splitchars には長い ASCII 行を分割する区切り文字群を文字列として指定し、 RFC 2822highest 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 インスタンスを返します。オプション引数 maxlinelenheader_name および continuation_wsHeader コンストラクタに与えるものと同じです。