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

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

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

email.utils.localtime(dt=None)

Return local time as an aware datetime object. If called without arguments, return the current time. Otherwise the 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.

Added in version 3.3.

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

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 normally not necessary to override this default, but may be useful in certain cases, such as constructing a distributed system that uses a consistent domain name across multiple hosts.

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

The inverse of parseaddr(), this takes a 2-tuple of the form (realname, email_address) and returns the string value suitable for a To or Cc header. If the first element of pair is false, then the second element is returned unmodified.

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

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

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

This function returns a list of 2-tuples of the form returned by parseaddr(). fieldvalues is a sequence of header field values as might be returned by 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)

Attempts to parse a date according to the rules in RFC 2822 Section 3.3. However, some mailers don't follow that format as specified, so parsedate() tries to guess correctly in such cases. date is a string containing an RFC 2822 date, such as "Mon, 20 Nov 1995 19:12:08 -0500". If it succeeds in parsing the date, parsedate() returns a 9-tuple that can be passed directly to time.mktime(); otherwise None will be returned. Note that indexes 6, 7, and 8 of the result tuple are not usable.

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)

The inverse of format_datetime(). Performs the same function as parsedate(), but on success returns a datetime; otherwise ValueError is raised if date contains an invalid value such as an hour greater than 23 or a timezone offset not between -24 and 24 hours. If the input date has a timezone of -0000, the datetime will be a naive datetime, and if the date conforms to the RFCs it will represent a time in UTC but with no indication of the actual source timezone of the message the date comes from. If the input date has any other valid timezone offset, the datetime will be an aware datetime whose corresponding tzinfo attribute is a timezone object.

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)

Returns a date string as per RFC 2822, for example:

Fri, 09 Nov 2001 01:08:47 -0000

Optional timeval, if given, is a floating-point time value as accepted by time.gmtime() and time.localtime(), otherwise the current time is used.

Optional localtime is a flag that when True, interprets timeval, and returns a date relative to the local timezone instead of UTC, properly taking daylight saving time into account. The default is False meaning UTC is used.

Optional usegmt is a flag that when True, outputs a date string with the timezone as an ASCII string GMT, rather than a numeric -0000. This is needed for some protocols (such as HTTP). This only applies when localtime is False. The default is 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.

Added in version 3.3.

email.utils.decode_rfc2231(s)

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

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

Encode the string s according to RFC 2231. Optional charset and language, if given, are the character set name and language name to use. If neither is given, s is returned as-is. If charset is given but language is not, the string is encoded using the empty string for 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 要素タプルからなるシーケンスです。

脚注