email.utils: Прочие утилиты


В модуле email.utils есть пара полезных утилит:

email.utils.localtime(dt=None)

Возвращает локальное время как осведомлённый объект datetime. Если вызывается без аргументов, возвращает текущее время. В противном случае аргумент dt должен быть экземпляром datetime, и он преобразуется в местный часовой пояс согласно базе данных часовых поясов системы. Если dt является наивным (т. е. dt.tzinfo — это None), предполагается, что он находится в местном времени. В этом случае положительное или нулевое значение для isdst заставляет localtime изначально предполагать, что летнее время (например, летнее время) действует или не действует (соответственно) в течение указанного времени. Отрицательное значение isdst заставляет localtime пытаться определить, действует ли летнее время в течение указанного времени.

Добавлено в версии 3.3.

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

Возвращает строку, подходящую для RFC 2822-совместимого заголовка Message-ID. Необязательный idstring, если он задан, представляет собой строку, используемую для усиления уникальности идентификатора сообщения. Необязательный domain, если он указан, предоставляет часть msgid после «@». По умолчанию используется локальное имя хоста. Обычно нет необходимости отменять это значение по умолчанию, но может быть полезно в определенных случаях, например, при построении распределенной системы, которая использует согласованное доменное имя на нескольких хостах.

Изменено в версии 3.2: Добавлено ключевой аргумент domain.

Остальные функции являются частью устаревшего (Compat32) почтового API. Нет необходимости напрямую использовать их с новым API, поскольку парсинг и форматирование, которые они предоставляют, выполняются автоматически механизмом парсинга заголовков нового API.

email.utils.quote(str)

Возвращает новую строку с обратной косой чертой в str, замененной двумя обратными косыми чертами, и двойными кавычками, замененными обратной косой чертой с двойными кавычками.

email.utils.unquote(str)

Возвращает новую строку, которая представляет собой расковыченную версию str. Если str заканчивается и начинается с двойных кавычек, они удаляются. Аналогичным образом, если str заканчивается и начинается с угловых скобок, они удаляются.

email.utils.parseaddr(address)

Разобрать адрес, который должен быть значением некоторого поля, содержащего адрес, например To или Cc, на его составные части realname и email адрес. Возвращает кортеж этой информации, если парсинг не завершился неудачно, и в этом случае возвращается 2-кортеж ('', '').

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

Это обратный parseaddr(), он принимает кортеж из двух форм (realname, email_address) и возвращает строковое значение, подходящее для заголовка To или Cc. Если у первого элемента pair значение ложь, второй элемент возвращается без изменений.

Необязательный charset — это множество символов, который будет использоваться в кодировке RFC 2047 для realname, если realname содержит символы, отличные от ASCII. Может быть экземпляром str или Charset. По умолчанию utf-8.

Изменено в версии 3.3: Добавлена опция charset.

email.utils.getaddresses(fieldvalues)

Метод возвращает список из двух кортежей формы, возвращаемой parseaddr(). 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 — это строка, содержащая дату RFC 2822, например "Mon, 20 Nov 1995 19:12:08 -0500". Если удаётся распарсить дату, parsedate() возвращает кортеж из 9 элементов, который может быть передан непосредственно time.mktime(); в противном случае будет возвращено None. Обратите внимание, что индексы 6, 7 и 8 результирующего кортежа не используются.

email.utils.parsedate_tz(date)

Выполняет ту же функцию, что и parsedate(), но возвращает либо None, либо 10-кортеж; первые 9 элементов составляют кортеж, который можно передать непосредственно в time.mktime(), а десятый — это смещение часового пояса даты от UTC (что является официальным термином для среднего времени по Гринвичу) [1]. Если во входной строке нет часового пояса, последним элементом возвращаемого кортежа будет 0, который представляет UTC. Обратите внимание, что индексы 6, 7 и 8 результирующего кортежа не используются.

email.utils.parsedate_to_datetime(date)

Обратна format_datetime(). Выполняет ту же функцию, что и parsedate(), но в случае успеха возвращает datetime. Если у даты ввода часовой пояс -0000, datetime будет наивным datetime, а если дата соответствует RFC, она будет представлять время в формате UTC, но без указания фактического часового пояса источника сообщения, из которого происходит дата. Если дата ввода имеет любое другое допустимое смещение часового пояса, datetime будет осведомленным datetime с соответствующим timezone tzinfo.

Добавлено в версии 3.3.

email.utils.mktime_tz(tuple)

Превратить кортеж из 10 элементов, возвращенный parsedate_tz(), в метку времени в формате UTC (секунды с начала эпохи). Если элемент часового пояса в кортеже None, предполагается местное время.

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 выводит строку даты с часовым поясом в виде строки ascii GMT, а не числового -0000. Это необходимо для некоторых протоколов (например, HTTP). Это применимо, только если localtimeFalse. По умолчанию — False.

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

Как formatdate, но на входе — экземпляр datetime. Если наивный datetime, предполагается, что это «UTC без информации об исходном часовом поясе», а для часового пояса используется обычный -0000. Если это известно datetime, то используется числовое смещение часового пояса. Если это известный часовой пояс со смещением нуля, то для usegmt может быть установлено значение True, и в этом случае вместо числового смещения часового пояса используется строка GMT. Это дает возможность генерировать заголовки даты HTTP, соответствующие стандартам.

Добавлено в версии 3.3.

email.utils.decode_rfc2231(s)

Расшифровать строку s согласно RFC 2231.

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

Кодировать строку s согласно RFC 2231. Необязательные charset и language, если указаны имя набора символов и имя языка для использования. Если ни один из них не указан, s возвращается как есть. Если задано charset, но не language, строка кодируется с использованием пустой строки для language.

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

Когда параметр заголовка закодирован в формате RFC 2231, Message.get_param может возвращать 3-кортеж, содержащий множество символов, язык и значение. collapse_rfc2231_value() превращает это в строку Юникод. Необязательный errors передается аргументу errors метода encode() str; по умолчанию это 'replace'. Необязательный fallback_charset указывает множество символов, который будет использоваться, если тот, который указан в заголовке RFC 2231, не известен Python; по умолчанию это 'us-ascii'.

Для удобства, если value, переданный в collapse_rfc2231_value(), не является кортежем, это должна быть строка, и она возвращается без кавычек.

email.utils.decode_params(params)

Список параметров декодирования согласно RFC 2231. params — это последовательность из двух кортежей, содержащих элементы формы (content- type, string-value).

Сноски

[1]Обратите внимание, что знак смещения часового пояса противоположен знаку time.timezone переменная для того же часового пояса; следует последняя переменная стандарт POSIX, в то время как этот модуль следует RFC 2822.