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

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

There are a couple of useful utilities provided in the email.utils module:

email.utils.localtime(dt=None)

Return local time as an aware datetime object. If called without arguments, return current time. Otherwise dt argument should be a datetime instance, and it is converted to the local time zone according to the system time zone database. If dt is naive (that is, dt.tzinfo is None), it is assumed to be in local time. In this case, a positive or zero value for isdst causes localtime to presume initially that summer time (for example, Daylight Saving Time) is or is not (respectively) in effect for the specified time. A negative value for isdst causes the localtime to attempt to divine whether summer time is in effect for the specified time.

バージョン 3.3 で追加.

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

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. Optional domain if given provides the portion of the msgid after the '@'. The default is the local hostname. It is not normally necessary to override this default, but may be useful certain cases, such as a constructing distributed system that uses a consistent domain name across multiple hosts.

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

The remaining functions are part of the legacy (Compat32) email API. There is no need to directly use these with the new API, since the parsing and formatting they provide is done automatically by the header parsing machinery of the new API.

email.utils.quote(str)

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

email.utils.unquote(str)

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

email.utils.parseaddr(address)

To や Cc のようなフィールドを持つアドレスをパースして、構成要素の 実名 と 電子メールアドレス を取り出します。 パースに成功した場合、これらの情報持つタプルを返します。失敗した場合は 2 要素のタプル ('', '') を返します。

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

parseaddr() の逆で、2 要素のタプル (realname, email_address) を取って To や Cc ヘッダに適した文字列を返します。タプル pair の第1要素が偽である場合、第2要素の値をそのまま返します。

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

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

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.parsedate_to_datetime(date)

format_datetime() の逆です。 parsedate() と同様に機能しますが、成功時に datetime を返します。 入力文字列がタイムゾーン -0000 を持つ場合、datetime はナイーブな datetime です。 日付が RFC に従っている場合、datetime は UTC での時間を表しますが、日付の元になったメッセージの実際のタイムゾーンについての情報を持ちません。 入力データにその他の有効なタイムゾーンの差がある場合、 datetime は対応する timezone tzinfo のあるそつのない datetime です。

バージョン 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)

Like formatdate, but the input is a datetime instance. If it is a naive datetime, it is assumed to be "UTC with no information about the source timezone", and the conventional -0000 is used for the timezone. If it is an aware datetime, then the numeric timezone offset is used. If it is an aware timezone with offset zero, then usegmt may be set to True, in which case the string GMT is used instead of the numeric timezone offset. This provides a way to generate standards conformant HTTP date headers.

バージョン 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 が与えられていない場合、文字列 s は language の空文字列を使ってエンコードされます。

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

ヘッダのパラメータが RFC 2231 形式でエンコードされている場合、 Message.get_param は 3 要素からなるタプルを返すことがあります。ここには、そのパラメータの文字セット、言語、および値の順に格納されています。 collapse_rfc2231_value() はこのパラメータをひとつの Unicode 文字列にまとめます。オプション引数 errors は str の encode() メソッドの引数 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 要素タプルです。

脚注

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