19.1.7. email.header: Internationalized headers

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
>>> 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() メソッドを呼びだすことによって追加することができます。 sbytes または str のインスタンスにできます。この意味については 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=None, errors='strict')

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

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

s may be an instance of bytes or str. If it is an instance of bytes, 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 an instance of str, then charset is a hint specifying the character set of the characters in the string.

In either case, when producing an RFC 2822-compliant header using RFC 2047 rules, the string will be encoded using the output codec of the charset. If the string cannot be encoded using the output codec, a UnicodeError will be raised.

Optional errors is passed as the errors argument to the decode call if s is a byte string.

encode(splitchars=';, \t', maxlinelen=None, linesep='\n')

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 which should be given extra weight by the splitting algorithm during normal header wrapping. This is in very rough support of RFC 2822‘s ‘higher level syntactic breaks’: split points preceded by a splitchar are preferred during line splitting, with the characters preferred in the order in which they appear in the string. Space and tab may be included in the string to indicate whether preference should be given to one over the other as a split point when other split chars do not appear in the line being split. Splitchars does not affect RFC 2047 encoded lines.

maxlinelen, if given, overrides the instance’s value for the maximum line length.

linesep specifies the characters used to separate the lines of the folded header. It defaults to the most useful value for Python application code (\n), but \r\n can be specified in order to produce headers with RFC-compliant line separators.

バージョン 3.2 で変更: Added the linesep argument.

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

__str__()

Returns an approximation of the Header as a string, using an unlimited line length. All pieces are converted to unicode 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 で変更: Added handling for the 'unknown-8bit' charset.

__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?=')
[(b'p\xf6stal', 'iso-8859-1')]
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 インスタンスを返します。オプション引数 maxlinelenheader_name および continuation_wsHeader コンストラクタに与えるものと同じです。