18.1.9. email.utils: 雑用ユーティリティ

email.utils モジュールではいくつかの便利なユーティリティを提供しています:

email.utils.quote(str)

文字列 str 内のバックスラッシュをバックスラッシュ2つに置換した新しい文字列を返します。また、ダブルクォートはバックスラッシュ + ダブルクォートに置換されます。

email.utils.unquote(str)

文字列 str を 逆クォート した新しい文字列を返します。もし str の先頭あるいは末尾がダブルクォートだった場合、これらは単に切りおとされます。同様にもし str の先頭あるいは末尾が角ブラケット (<、>) だった場合も切りおとされます。

email.utils.parseaddr(address)

アドレスをパーズします。 To や Cc のようなアドレスをふくんだフィールドの値を与えると、構成部分の実名 と 電子メールアドレス を取り出します。パーズに成功した場合、これらの情報をタプル (realname, email_address) にして返します。失敗した場合は 2要素のタプル ('', '') を返します。

email.utils.formataddr(pair)

parseaddr() の逆で、実名と電子メールアドレスからなる 2要素のタプル(realname, email_address) を引数にとり、 To あるいは Cc ヘッダに適した形式の文字列を返します。タプル pair の第1要素が偽である場合、第2要素の値をそのまま返します。

email.utils.getaddresses(fieldvalues)

このメソッドは 2要素タプルのリストを parseaddr() と同じ形式で返します。 fieldvalues はたとえば Message.get_all が返すような、ヘッダのフィールド値からなるシーケンスです。以下はある電子メールメッセージからすべての受け取り人を得る一例です:

from email.utils import getaddresses

tos = msg.get_all('to', [])
ccs = msg.get_all('cc', [])
resent_tos = msg.get_all('resent-to', [])
resent_ccs = msg.get_all('resent-cc', [])
all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)
email.utils.parsedate(date)

RFC 2822 に記された規則にもとづいて日付を解析します。しかし、メイラーによってはここで指定された規則に従っていないものがあり、そのような場合 parsedate() はなるべく正しい日付を推測しようとします。 date は RFC 2822 形式の日付を保持している文字列で、 "Mon, 20 Nov 1995 19:12:08 -0500" のような形をしています。日付の解析に成功した場合、 parsedate() は関数 time.mktime() に直接渡せる形式の9要素からなるタプルを返し、失敗した場合は None を返します。返されるタプルの 6、7、8番目は有効ではないので注意してください。

email.utils.parsedate_tz(date)

parsedate() と同様の機能を提供しますが、 None または 10要素のタプルを返すところが違います。最初の 9つの要素は time.mktime() に直接渡せる形式のものであり、最後の 10番目の要素は、その日付の時間帯の UTC (グリニッジ標準時の公式な呼び名です) に対するオフセットです [1] 。入力された文字列に時間帯が指定されていなかった場合、10番目の要素には None が入ります。タプルの 6、7、8番目は有効ではないので注意してください。

email.utils.mktime_tz(tuple)

parsedate_tz() が返す 10要素のタプルを UTC のタイムスタンプ (エポックからの秒数) に変換します。与えられた時間帯が None である場合、時間帯として現地時間 (localtime) が仮定されます。

email.utils.formatdate([timeval[, localtime][, usegmt]])

日付を RFC 2822 形式の文字列で返します。例:

Fri, 09 Nov 2001 01:08:47 -0000

オプションとして float 型の値をもつ引数 timeval が与えられた場合、これは time.gmtime() および time.localtime() に渡されます。それ以外の場合、現在の時刻が使われます。

オプション引数 localtime はフラグです。これが True の場合、この関数は timeval を解析したあと UTC のかわりに現地時間 (localtime) の時間帯をつかって変換します。おそらく夏時間も考慮に入れられるでしょう。デフォルトではこの値は False で、UTC が使われます。

オプション引数 usegmt が True のときは、タイムゾーンを表すのに数値の -0000 ではなく ascii文字列である GMT が使われます。これは (HTTP などの) いくつかのプロトコルで必要です。この機能は localtime が False のときのみ適用されます。デフォルトは False です。

バージョン 2.4 で追加.

email.utils.make_msgid([idstring])

RFC 2822 準拠形式の Message-ID ヘッダに適した文字列を返します。オプション引数 idstring が文字列として与えられた場合、これはメッセージ ID の一意性を高めるのに利用されます。

email.utils.decode_rfc2231(s)

RFC 2231 に従って文字列 s をデコードします。

email.utils.encode_rfc2231(s[, charset[, language]])

RFC 2231 に従って s をエンコードします。オプション引数 charset および language が与えられた場合、これらは文字セット名と言語名として使われます。もしこれらのどちらも与えられていない場合、 s はそのまま返されます。 charset は与えられているが language が与えられていない場合、文字列 s は language の空文字列を使ってエンコードされます。

email.utils.collapse_rfc2231_value(value[, errors[, fallback_charset]])

ヘッダのパラメータが RFC 2231 形式でエンコードされている場合、 Message.get_param は 3 要素からなるタプルを返すことがあります。ここには、そのパラメータの文字セット、言語、および値の順に格納されています。 collapse_rfc2231_value() はこのパラメータをひとつの Unicode 文字列にまとめます。オプション引数 errors は built-in である unicode() 関数の引数 errors に渡されます。このデフォルト値は replace となっています。オプション引数 fallback_charset は、もし RFC 2231 ヘッダの使用している文字セットが Python の知っているものではなかった場合の非常用文字セットとして使われます。デフォルトでは、この値は us-ascii です。

便宜上、 collapse_rfc2231_value() に渡された引数 value がタプルでない場合には、これは文字列である必要があります。その場合には unquote された文字列が返されます。

email.utils.decode_params(params)

RFC 2231 に従ってパラメータのリストをデコードします。 params は (content-type, string-value) のような形式の 2要素からなるタプルです。

バージョン 2.4 で変更: dump_address_pair() 関数は削除されました。かわりに formataddr() 関数を使ってください。

バージョン 2.4 で変更: decode() 関数は削除されました。かわりに Header.decode_header メソッドを使ってください。

バージョン 2.4 で変更: encode() 関数は削除されました。かわりに Header.encode メソッドを使ってください。

脚注

[1]注意: この時間帯のオフセット値は time.timezone の値と符号が逆です。これは time.timezone が POSIX 標準に準拠しているのに対して、こちらは RFC 2822 に準拠しているからです。