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)

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

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)

Этот метод возвращает список 2-кортежей, как возвращает 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 с соответствующим 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. Если это неявная дата, предполагается «UTC без информации об исходном часовом поясе», и используется стандартное обозначение -0000 для часового пояса. Если это явная дата с часовым поясом, используется числовое смещение часового пояса. Если это явный часовой пояс с нулевым смещением, 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 метода str’s encode(); по умолчанию он равен '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.