"email.utils": 多方面のユーティリティ
*************************************

There are several useful utilities provided in the "email.utils"
module:

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

   Returns a string suitable for an **RFC 2822**-compliant *Message-
   ID* header.  Optional *idstring* if given, is a string used to
   strengthen the uniqueness of the message 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]])

   When a header parameter is encoded in **RFC 2231** format,
   "Message.get_param" may return a 3-tuple containing the character
   set, language, and value.  "collapse_rfc2231_value()" turns this
   into a unicode string.  Optional *errors* is passed to the *errors*
   argument of the built-in "unicode()" function; it defaults to
   "replace".  Optional *fallback_charset* specifies the character set
   to use if the one in the **RFC 2231** header is not known by
   Python; it defaults to "us-ascii".

   便宜上、 "collapse_rfc2231_value()" に渡された引数 *value* がタプル
   でない場合には、これは文字列でなければなりません。その場合にはクォ
   ートを除いた文字列を返します。

email.utils.decode_params(params)

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

バージョン 2.4 で変更: The "dump_address_pair()" function has been
removed; use "formataddr()" instead.

バージョン 2.4 で変更: The "decode()" function has been removed; use
the "Header.decode_header" method instead.

バージョン 2.4 で変更: The "encode()" function has been removed; use
the "Header.encode" method instead.

-[ 脚注 ]-

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