18.1.9. email.utils: Разные утилиты¶email.utils: Miscellaneous utilities

Модуль email.utils предоставляет несколько полезных утилит:

email.utils.quote(str)¶

Возвращает новую строку, в которой обратная косая черта в str заменена двумя обратными косыми чертами, а двойные кавычки – на обратную косую черту с двойной кавычкой.

email.utils.unquote(str)¶

Возвращает новую строку, которая является расквотированной версией str. Если str начинается и заканчивается двойными кавычками, они удаляются. Аналогично, если str начинается и заканчивается угловыми скобками, они удаляются.

email.utils.parseaddr(address)¶

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

email.utils.formataddr(pair)¶

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

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]. Если входная строка не содержит часового пояса, последним элементом возвращаемого кортежа будет None. Обратите внимание, что индексы 6, 7 и 8 результирующего кортежа непригодны для использования.

email.utils.mktime_tz(tuple)¶

Преобразует 10-кортеж, возвращаемый parsedate_tz(), в метку времени UTC. Если элемент часового пояса в кортеже равен None, предполагается местное время. Небольшой недостаток: mktime_tz() интерпретирует первые 8 элементов tuple как местное время, а затем компенсирует разницу часовых поясов. Это может привести к небольшой ошибке при переходе на летнее время, но для обычного использования это несущественно.

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.make_msgid(idstring=None, domain=None)¶

Возвращает строку, подходящую для RFC 2822-совместимого Message-ID заголовка. Необязательный idstring, если задан, представляет собой строку, используемую для усиления уникальности идентификатора сообщения. Необязательный domain, если задан, указывает часть msgid после символа '@'. По умолчанию используется локальное имя хоста. Обычно нет необходимости переопределять это значение, но это может быть полезно в определенных случаях, например, при создании распределенной системы, которая использует единое доменное имя на нескольких хостах.

Изменено в версии 3.2: добавлен ключевой аргумент domain

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')¶

When a header parameter is encoded in RFC 2231 format, Message.get_param() may return a 3-tuple containing the character set, language, and value. collapse_rfc2231_value() turns this into a unicode string. Optional errors is passed to the errors argument of str‘s encode() method; it defaults to 'replace'. Optional fallback_charset specifies the character set to use if the one in the RFC 2231 header is not known by Python; it defaults to 'us-ascii'.

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

email.utils.decode_params(params)¶

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

Сноски