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.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 с соответствующим 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 может вернуть кортеж из 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).

Примечания

1

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