# 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.``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 がタプルでない場合には、これは文字列でなければなりません。その場合にはクォートを除いた文字列を返します。

`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 に準拠しているからです。