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

email.utils.parsedate_to_datetime(date)¶

Обратная функция к format_datetime(). Выполняет ту же функцию, что и parsedate(), но в случае успеха возвращает datetime. Если входная дата имеет часовой пояс -0000, datetime будет наивным datetime, и если дата соответствует RFC, она будет представлять время в UTC, но без указания фактического исходного часового пояса сообщения, из которого взята дата. Если входная дата имеет любое другое допустимое смещение часового пояса, datetime будет осознанным (aware) datetime с соответствующим timezone tzinfo.

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

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.format_datetime(dt, usegmt=False)¶

Как formatdate, но входными данными является экземпляр datetime. Если это наивный datetime, он считается «UTC без информации об исходном часовом поясе», и для часового пояса используется обычное -0000. Если это осознанный datetime, то используется числовое смещение часового пояса. Если это осознанный часовой пояс с нулевым смещением, то usegmt может быть установлен в True, и тогда вместо числового смещения используется строка GMT. Это позволяет создавать соответствующие стандартам HTTP-заголовки даты.

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

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

Возвращает строку, подходящую для 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')¶

Когда параметр заголовка закодирован в формате RFC 2231, Message.get_param может вернуть кортеж из трёх элементов, содержащий кодировку, язык и значение. collapse_rfc2231_value() преобразует его в строку Unicode. Необязательный параметр errors передаётся в аргумент errors метода str. encode(); по умолчанию 'replace'. Необязательный fallback_charset задаёт кодировку, которая будет использоваться, если кодировка из заголовка RFC 2231 неизвестна Python; по умолчанию 'us-ascii'.

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

email.utils.decode_params(params)¶

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

Сноски