email.utils: Разные утилиты для email

Исходный код: Lib/email/utils.py

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

email.utils.quote(str)

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

email.utils.unquote(str)

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

email.utils.parseaddr(address)

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

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

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

Необязательный параметр 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]. Если в входной строке нет часового пояса, последний элемент возвращаемого кортежа — None. Обратите внимание, что индексы 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). Это применимо только когда localtime False. По умолчанию False.

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

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

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

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)

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

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

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() преобразует этот кортеж в строку Unicode. Необязательный параметр errors передаётся в аргумент errors метода str’s encode(); по умолчанию он равен 'replace'. Необязательный параметр fallback_charset задаёт кодировку, используемую, если кодировка из заголовка RFC 2231 не распознаётся Python; по умолчанию он равен 'us-ascii'.

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

email.utils.decode_params(params)

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

Примечания