email.utils: Вспомогательные функции для работы с почтой

В модуле email.utils представлены несколько полезных вспомогательных функций:

email.utils.quote(str)

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

email.utils.unquote(str)

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

email.utils.parseaddr(address)

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

email.utils.formataddr(pair)

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

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. Если в строке отсутствует часовой пояс, последний элемент возвращаемого кортежа — None. Обратите внимание, что элементы с индексами 6, 7 и 8 результата кортежа не могут быть использованы.

email.utils.mktime_tz(tuple)

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

email.utils.formatdate([timeval[, localtime][, usegmt]])

Возвращает строку даты в соответствии с 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). Это применимо только тогда, когда localtime — False. По умолчанию False.

Новое в версии 2.4.

email.utils.make_msgid([idstring])

Возвращает строку, подходящую для заголовка Message-ID, соответствующего RFC 2822. Необязательное idstring, если задано, — это строка, используемая для повышения уникальности идентификатора сообщения.

email.utils.decode_rfc2231(s)

Декодирует строку s в соответствии с RFC 2231.

email.utils.encode_rfc2231(s[, charset[, language]])

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

email.utils.collapse_rfc2231_value(value[, errors[, fallback_charset]])

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

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

email.utils.decode_params(params)

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

Примечания

1

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