Документация Python неофициальный перевод

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, предполагается местное время.

email.utils.formatdate([timeval[, localtime][, usegmt]])

Возвращает строку даты в соответствии с 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.

Новое в версии 2.4.

email.utils.make_msgid([idstring])

Возвращает строку, подходящую для заголовка Message-ID, совместимого с RFC 2822. Необязательный параметр idstring, если задан, используется для повышения уникальности идентификатора сообщения.

email.utils.decode_rfc2231(s)

Декодирует строку s в соответствии с RFC 2231.

email.utils.encode_rfc2231(s[, charset[, language]])

Кодирует строку s в соответствии с RFC 2231. Необязательные параметры charset и language, если заданы, указывают имя кодировки и язык. Если ни один не задан, s возвращается как есть. Если charset задан, а language нет, строка кодируется с пустой строкой для language.

email.utils.collapse_rfc2231_value(value[, errors[, fallback_charset]])

Когда параметр заголовка закодирован в формате RFC 2231, Message.get_param может вернуть кортеж из трёх элементов, содержащий кодировку, язык и значение. collapse_rfc2231_value() преобразует это в строку Unicode. Необязательный errors передаётся аргументу errors встроенной функции unicode(); по умолчанию он равен 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).

Изменено в версии 2.4: Функция dump_address_pair() удалена; вместо неё используйте formataddr() .

Изменено в версии 2.4: Функция decode() удалена; вместо неё используйте метод Header.decode_header .

Изменено в версии 2.4: Функция encode() удалена; вместо неё используйте метод Header.encode.

Сноски

1

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