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 игнорируется.

Добавлено в версии 3.3.

Устарело с версии 3.12, будет удалено в версии 3.14: Параметр isdst.

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, *, strict=True)¶

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

Если strict имеет значение true, используется строгий анализатор, который отклоняет некорректные входные данные.

Изменено в версии 3.13: Добавлен необязательный параметр strict и по умолчанию отклоняются некорректные входные данные.

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, *, strict=True)¶

Этот метод возвращает список кортежей из двух элементов вида, возвращаемого parseaddr(). fieldvalues – это последовательность значений полей заголовка, которые могут быть возвращены Message.get_all.

Если strict имеет значение true, используется строгий анализатор, который отклоняет некорректные входные данные.

Вот простой пример, который получает всех получателей сообщения:

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)

Изменено в версии 3.13: Добавлен необязательный параметр strict и по умолчанию отклоняются некорректные входные данные.

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; в противном случае возбуждается ValueError, если date содержит недопустимое значение, например час больше 23 или смещение часового пояса не в диапазоне от -24 до 24 часов. Если входная дата имеет часовой пояс -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).

Сноски