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 要素タプルからなるシーケンスです。

脚注