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

Источник: Lib/email/utils.py

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

email.utils.localtime(dt=None)

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

Added in version 3.3.

Утратил актуальность с версии 3.12, удален в версии 3.14: Параметр isdst.

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, *, strict=True)

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

Если strict равно true, используйте строгий синтаксический анализатор, который отвергает неправильно оформленные входные данные.

Изменено в версии 3.13: Добавьте необязательный параметр strict и по умолчанию отклоняйте неправильно оформленные входные данные.

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

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

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

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

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

Этот метод возвращает список из двух кортежей формы, возвращаемой parseaddr(). fieldvalues - это последовательность значений полей заголовка, которые могут быть возвращены методом Message.get_all.

Если strict равно true, используйте строгий синтаксический анализатор, который отвергает неправильно оформленные входные данные.

Вот простой пример, который позволяет получить всех получателей сообщения:

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)

Попытка разобрать дату в соответствии с правилами, изложенными в 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.

Added in version 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.

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

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

email.utils.decode_params(params)

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

Сноски