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

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

Обратная функция к parseaddr(). Принимает кортеж из двух элементов вида (realname, email_address) и возвращает строку, подходящую для заголовка To или Cc. Если первый элемент pair равен False, то возвращается второй элемент без изменений.

Необязательный параметр charset – кодировка символов, которая будет использована для кодирования RFC 2047 в случае, если pair содержит символы, не относящиеся к 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. Если входящая дата имеет часовой пояс -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.