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 для email. Нет необходимости напрямую использовать их с новым 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(). Принимает 2-кортеж вида (realname, email_address) и возвращает строковое значение, подходящее для заголовка To или Cc. Если первый элемент pair ложный, то возвращается второй элемент без изменений.

Дополнительный 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. Если входная дата имеет часовой пояс -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 для часового пояса. Если это явная дата 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() преобразует его в строку 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 — последовательность из пар кортежей, содержащих элементы вида (content-type, string-value).

Примечания

1

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