## 9 雑用ユーティリティ

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

`quote`( | str)

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

`unquote`( | str)

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

`parseaddr`( | address)

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

`formataddr`( | pair)

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

`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)

`parsedate`( | date)

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

`parsedate_tz`( | date)

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

`mktime_tz`( | tuple)

  `parsedate_tz()` が返す 10要素のタプルを UTC の タイムスタンプに変換します。与えられた時間帯が `None` である場合、 時間帯として現地時間 (localtime) が仮定されます。 マイナーな欠点: `mktime_tz()` はまず tuple の最初の 8要素を localtime として変換し、つぎに時間帯の差を加味しています。 夏時間を使っている場合には、これは通常の使用にはさしつかえないものの、 わずかな誤差を生じるかもしれません。

`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` のときのみ適用されます。 バージョン 2.4 で 新たに追加 された仕様です。

`make_msgid`( | [idstring])

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

`decode_rfc2231`( | s)

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

`encode_rfc2231`( | s[, charset[, language]])

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

`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 された文字列が返されます。

`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()` メソッドを使ってください。

#### Footnotes

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