"email.utils": 各種ユーティリティ
*********************************

**ソースコード:** Lib/email/utils.py

======================================================================

"email.utils" モジュールには、いくつかの便利なユーティリティがあります
:

email.utils.localtime(dt=None)

   現地時間を aware な datetime オブジェクトとして返します。 引数なし
   で呼び出すと現在時刻を返します。 引数 *dt* を指定する場合は
   "datetime" インスタンスでなければならず、システムのタイムゾーンデー
   タベースに従って現地のタイムゾーンに変換されます。 *dt* が naive (
   つまり "dt.tzinfo" が "None") の場合は、現地時間とみなされます。

   Added in version 3.3.

   バージョン 3.12 で非推奨、バージョン 3.14 で削除: *isdst* パラメー
   タ。

email.utils.make_msgid(idstring=None, domain=None)

   **RFC 2822** に準拠した *Message-ID* ヘッダに適した文字列を返します
   。 オプション引数 *idstring* は、メッセージ ID の一意性を高めるため
   に使う文字列です。 オプション引数 *domain* は、メッセージ ID の「@
   」より後の部分を指定します。 デフォルトはローカルのホスト名です。
   通常、このデフォルトを変更する必要はありませんが、複数のホストで共
   通のドメイン名を使う分散システムを構築する場合などに役立つことがあ
   ります。

   バージョン 3.2 で変更: *domain* キーワードが追加されました。

以下の関数は従来の ("Compat32") email API の一部です。 新しい API では
ヘッダの解析機構がこれらの解析や書式化を自動的に行うため、直接使う必要
はありません。

email.utils.quote(str)

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

email.utils.unquote(str)

   文字列 *str* の *クォートを外した* 新しい文字列を返します。*str* の
   先頭と末尾がダブルクォートだった場合、それらは取り除かれます。同様
   に *str* の先頭と末尾が角ブラケット (<、>) だった場合もそれらは取り
   除かれます。

email.utils.parseaddr(address, *, strict=True)

   アドレスを解析して、構成要素である *実名* と *電子メールアドレス*
   に分けます。 渡すアドレスは *To* や *Cc* など、アドレスを含むフィー
   ルドの値です。 解析に成功した場合はこれらの情報をタプルで返し、失敗
   した場合は 2 要素タプル "('', '')" を返します。

   *strict* が真の場合、不正な入力を拒否する厳格なパーザを使います。

   バージョン 3.13 で変更: オプションのパラメータ *strict* が追加され
   、デフォルトで不正な入力を拒否するようになりました。

email.utils.formataddr(pair, charset='utf-8')

   "parseaddr()" の逆の処理を行います。 "(realname, email_address)" 形
   式の 2 要素タプルを受け取り、*To* や *Cc* ヘッダに適した文字列の値
   を返します。 *pair* の最初の要素が偽の場合、2 番目の要素をそのまま
   返します。

   任意の *charset* は、 "realname" が非 ASCII 文字を含んでいる場合に
   その **RFC 2047** エンコーディングに使われる文字集合です。"str" か
   "Charset" のインスタンスで、デフォルトは "utf-8" です。

   バージョン 3.3 で変更: *charset* オプションが追加されました。

email.utils.getaddresses(fieldvalues, *, strict=True)

   "parseaddr()" が返す形式の 2 要素タプルからなるリストを返します。
   *fieldvalues* は、"Message.get_all()" が返すようなヘッダフィールド
   値のシーケンスです。

   *strict* が真の場合、不正な入力を拒否する厳格なパーザを使います。

   メッセージのすべての受信者を取得する簡単な例を示します。

      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)

   バージョン 3.13 で変更: オプションのパラメータ *strict* が追加され
   、デフォルトで不正な入力を拒否するようになりました。

email.utils.parsedate(date)

   **RFC 2822 Section 3.3** の規則に従って日付の解析を試みます。 ただ
   し、この形式に厳密に従わないメーラーもあるため、"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]。 入力文字列にタイムゾーンがなければ
   、返されるタプルの最後の要素は UTC を表す "0" です。 返されたタプル
   のインデックス 6、7、8 の要素は使用できないことに注意してください。

email.utils.parsedate_to_datetime(date)

   "format_datetime()" の逆の処理を行います。 "parsedate()" と同じ処理
   を行いますが、成功すると "datetime" を返します。 *date* に 23 を超
   える時や、-24 時間から 24 時間の範囲にないタイムゾーンオフセットな
   どの無効な値が含まれる場合は "ValueError" を送出します。 入力の日付
   のタイムゾーンが "-0000" の場合、"datetime" は naive になります。
   その日付が RFC に準拠していれば UTC の時刻を表しますが、元のメッセ
   ージの実際のタイムゾーンを示す情報はありません。 入力の日付にそれ以
   外の有効なタイムゾーンオフセットがある場合、"datetime" は aware に
   なり、対応する "tzinfo" 属性は "timezone" オブジェクトになります。

   Added in version 3.3.

email.utils.mktime_tz(tuple)

   "parsedate_tz()" が返す 10 要素のタプルを UTC のタイムスタンプ (エ
   ポックからの秒数) に変換します。与えられた時間帯が "None" である場
   合、時間帯として現地時間 (localtime) が仮定されます。

email.utils.formatdate(timeval=None, localtime=False, usegmt=False)

   **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" です。

email.utils.format_datetime(dt, usegmt=False)

   "formatdate()" と似ていますが、入力は "datetime" インスタンスです。
   naive な datetime の場合は「元のタイムゾーンの情報がない UTC」とみ
   なし、慣例に従ってタイムゾーンに "-0000" を使います。 aware な
   "datetime" の場合は数値のタイムゾーンオフセットを使います。 aware
   でオフセットがゼロの場合は *usegmt* を "True" に設定でき、その場合
   は数値のタイムゾーンオフセットの代わりに文字列 "GMT" を使います。
   これにより標準に準拠した HTTP の日付ヘッダを生成できます。

   Added in version 3.3.

email.utils.decode_rfc2231(s)

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

email.utils.encode_rfc2231(s, charset=None, language=None)

   **RFC 2231** に従って文字列 *s* をエンコードします。 オプション引数
   *charset* と *language* は、使う文字セット名と言語名です。 どちらも
   指定しなければ *s* をそのまま返します。 *charset* を指定して
   *language* を指定しない場合は、*language* に空文字列を使ってエンコ
   ードします。

email.utils.collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')

   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 string.  Optional *errors* is passed to the *errors*
   argument of "str"'s "encode()" method; 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 要素タプルからなるシーケ
   ンスです。

-[ 脚注 ]-

[1] タイムゾーンオフセットの符号は、同じタイムゾーンの "time.timezone"
    変数の符号と逆であることに注意してください。 後者は POSIX 標準に従
    いますが、このモジュールは **RFC 2822** に従います。
