\declaremodule{standard}{email.utils}
\modulesynopsis{電子メールパッケージの雑多なユーティリティ。}

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

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

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

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

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

\begin{funcdesc}{getaddresses}{fieldvalues}
このメソッドは 2要素タプルのリストを \code{parseaddr()} と同じ形式で返します。
\var{fieldvalues} はたとえば \method{Message.get_all()} が返すような、
ヘッダのフィールド値からなるシーケンスです。以下はある電子メールメッセージから
すべての受け取り人を得る一例です:

\begin{verbatim}
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)
\end{verbatim}
\end{funcdesc}

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

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

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

\begin{funcdesc}{formatdate}{\optional{timeval\optional{, localtime}\optional{, usegmt}}}
日付を \rfc{2822} 形式の文字列で返します。例:

\begin{verbatim}
Fri, 09 Nov 2001 01:08:47 -0000
\end{verbatim}

オプションとして float 型の値をもつ引数 \var{timeval} が与えられた場合、
これは \function{time.gmtime()} および \function{time.localtime()} に
渡されます。それ以外の場合、現在の時刻が使われます。

オプション引数 \var{localtime} はフラグです。
これが \code{True} の場合、この関数は \var{timeval} を解析したあと
UTC のかわりに現地時間 (localtime) の時間帯をつかって変換します。
おそらく夏時間も考慮に入れられるでしょう。
デフォルトではこの値は \code{False} で、UTC が使われます。

オプション引数 \var{usegmt} が \code{True} のときは、タイムゾーンを表すのに
数値の \code{-0000} ではなく ascii文字列である \code{GMT} が使われます。
これは (HTTP などの) いくつかのプロトコルで必要です。
この機能は \var{localtime} が \code{False} のときのみ適用されます。
\versionadded{2.4}
\end{funcdesc}

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

\begin{funcdesc}{decode_rfc2231}{s}
\rfc{2231} に従って文字列 \var{s} をデコードします。
\end{funcdesc}

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

\begin{funcdesc}{collapse_rfc2231_value}{value\optional{, errors\optional{,
    fallback_charset}}}
ヘッダのパラメータが \rfc{2231} 形式でエンコードされている場合、
\method{Message.get_param()} は 3要素からなるタプルを返すことがあります。
ここには、そのパラメータの文字セット、言語、および値の順に格納されています。
\function{collapse_rfc2231_value()} はこのパラメータをひとつの Unicode 文字列に
まとめます。オプション引数 \var{errors} は built-in である \function{unicode()} 関数の
引数 \var{errors} に渡されます。このデフォルト値は \code{replace} となっています。
オプション引数 \var{fallback_charset} は、もし \rfc{2231} ヘッダの使用している
文字セットが Python の知っているものではなかった場合の非常用文字セットとして
使われます。デフォルトでは、この値は \code{us-ascii} です。

便宜上、\function{collapse_rfc2231_value()} に渡された引数 \var{value} が
タプルでない場合には、これは文字列である必要があります。その場合には
unquote された文字列が返されます。
\end{funcdesc}

\begin{funcdesc}{decode_params}{params}
\rfc{2231} に従ってパラメータのリストをデコードします。
\var{params} は \code{(content-type, string-value)} のような形式の
2要素からなるタプルです。
\end{funcdesc}

\versionchanged[\function{dump_address_pair()} 関数は撤去されました。かわりに 
\function{formataddr()} 関数を使ってください。]{2.4}

\versionchanged[\function{decode()} 関数は撤去されました。かわりに 
\method{Header.decode_header()} メソッドを使ってください。]{2.4}
 
\versionchanged[\function{encode()} 関数は撤去されました。かわりに 
\method{Header.encode()} メソッドを使ってください。]{2.4}
