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