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

Исходный код: Lib/email/utils.py

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

email.utils.localtime(dt=None)¶

Возвращает местное время как осведомлённый объект datetime. При вызове без аргументов возвращает текущее время. В противном случае аргумент dt должен быть экземпляром datetime, и он преобразуется в местный часовой пояс согласно системной базе данных часовых поясов. Если dt наивный (то есть dt.tzinfo равно None), считается, что он задан в местном времени. В этом случае положительное или нулевое значение isdst заставляет localtime изначально предполагать, что летнее время (например, Daylight Saving Time) действует или не действует (соответственно) для указанного времени. Отрицательное значение isdst заставляет localtime пытаться определить, действует ли летнее время для указанного времени.

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

email.utils.make_msgid(idstring=None, domain=None)¶

Возвращает строку, подходящую для RFC 2822-совместимого Message-ID заголовка. Необязательный 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 – на составляющие части: 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 будет осведомлённым 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. Если это наивный 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 может вернуть 3-элементный кортеж, содержащий кодировку, язык и значение. collapse_rfc2231_value() преобразует это в строку Unicode. Необязательный параметр errors передаётся в аргумент errors метода str encode(); по умолчанию '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).

Сноски

1

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