email.utils: Прочие утилиты¶

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

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

email.utils.localtime(dt=None)¶

Возвращает местное время как объект datetime с поддержкой 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, если указано, - это строка, используемая для повышения уникальности идентификатора сообщения. Необязательный домен, если он указан, содержит часть идентификатора 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, на составляющие его части реальное имя и адрес электронной почты. Возвращает кортеж с этой информацией, если только синтаксический анализ не завершается ошибкой, и в этом случае возвращается 2-й кортеж из ('', '').

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

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

email.utils.formataddr(pair, charset='utf-8')¶

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

Необязательный набор символов - это набор символов, который будет использоваться в RFC 2047 кодировке realname, если realname содержит символы, отличные от ASCII. Может быть экземпляром str или Charset. По умолчанию используется значение utf-8.

Изменено в версии 3.3: Добавлена опция charset.

email.utils.getaddresses(fieldvalues, *, strict=True)¶

Этот метод возвращает список из 2 кортежей формы, возвращаемой 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.11.10: Добавьте необязательный параметр strict и по умолчанию отклоняйте неверные входные данные.

email.utils.parsedate(date)¶

Пытается разобрать дату в соответствии с правилами, указанными в RFC 2822. Однако некоторые почтовые программы не придерживаются указанного формата, поэтому parsedate() в таких случаях пытается угадать правильно. дата - это строка, содержащая 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. Если это наивная дата-время, то предполагается, что это «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. Необязательные кодировка и язык, если заданы, - это имя набора символов и название языка для использования. Если ни то, ни другое не задано, s возвращается как есть. Если задана кодировка, а язык - нет, строка кодируется с использованием пустой строки для языка.

email.utils.collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')¶

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

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

email.utils.decode_params(params)¶

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

Сноски