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

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

В модуле 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 - на составляющие его части реальное имя и адрес электронной почты. Возвращает кортеж этой информации, если только разбор не завершился неудачей, в этом случае возвращается кортеж ('', '').

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

email.utils.parsedate_to_datetime(date)¶

Обратная функция к format_datetime(). Выполняет ту же функцию, что и parsedate(), но при успехе возвращает datetime; в противном случае будет выдано ValueError, если date содержит недопустимое значение, например, час больше 23 или смещение часового пояса не между -24 и 24 часами. Если входная дата имеет часовой пояс -0000, то datetime будет наивным datetime, и если дата соответствует RFC, то она будет представлять время в UTC, но без указания фактического часового пояса источника сообщения, из которого взята дата. Если входная дата имеет любое другое допустимое смещение часового пояса, datetime будет значением datetime с соответствующим a 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.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 может вернуть кортеж, содержащий набор символов, язык и значение. collapse_rfc2231_value() превращает это в строку юникода. Необязательное значение errors передается в аргумент errors метода str encode(); по умолчанию оно равно '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.