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 のようなフィールドを持つアドレスをパースして、構成要素の 実名 と 電子メールアドレス を取り出します。 パースに成功した場合、これらの情報持つタプルを返します。失敗した場合は 2 要素のタプル
('', '')を返します。
-
email.utils.formataddr(pair)¶ parseaddr()の逆で、2 要素のタプル(realname, email_address)を取って To や Cc ヘッダに適した文字列を返します。タプル pair の第1要素が偽である場合、第2要素の値をそのまま返します。
-
email.utils.getaddresses(fieldvalues)¶ このメソッドは
parseaddr()が返す形式の 2 要素タプルのリストを返します。 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 は"Mon, 20 Nov 1995 19:12:08 -0500"のような RFC 2822 形式の日付を含む文字列です。 日付の解析に成功した場合、parsedate()は関数time.mktime()に直接渡せる形式の 9 要素からなるタプルを返します。 失敗した場合はNoneを返します。 返されるタプルの 6、7、8番目の添字は使用不可なので注意してください。
-
email.utils.parsedate_tz(date)¶ parsedate()と同様に機能しますが、Noneか 10 要素のタプルを返します。 最初の 9 要素はtime.mktime()に直接渡すことの出来るタプルを成し、10 番目はその日付のタイムゾーンの UTC (グリニッジ標準時の公式用語) からの差です 1 。 入力文字列にタイムゾーンがない場合、返されるタプルの最後の要素は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
与えられた場合、オプションの timeval は
time.gmtime()やtime.localtime()に渡すことの出来る浮動小数の時刻です。 それ以外の場合、現在時刻が使われます。オプション引数 localtime はフラグです。
Trueの場合、この関数は timeval を解析して UTC の代わりに現地のタイムゾーンに対する日付を返します。おそらく夏時間も考慮するでしょう。デフォルトは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.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 がタプルでない場合には、これは文字列でなければなりません。その場合にはクォートを除いた文字列を返します。
-
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 メソッドを使ってください。
脚注