email.utils
: Разные утилиты¶
Источник: Lib/email/utils.py
В модуле email.utils
есть несколько полезных утилит:
- email.utils.localtime(dt=None)¶
Возвращает локальное время в виде объекта datetime. Если вызывается без аргументов, возвращается текущее время. В противном случае аргумент dt должен быть экземпляром
datetime
, и он преобразуется в локальный часовой пояс в соответствии с системной базой данных часовых поясов. Если dt является наивным (то естьdt.tzinfo
равноNone
), то предполагается, что это местное время.Added in version 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. – на составляющие его части реальное имя и адрес электронной почты. Возвращает кортеж этой информации, если только разбор не завершился неудачей, в этом случае возвращается кортеж из двух
('', '')
.Если strict равно true, используйте строгий синтаксический анализатор, который отвергает неправильно оформленные входные данные.
Изменено в версии 3.13: Добавьте необязательный параметр strict и по умолчанию отклоняйте неправильно оформленные входные данные.
- email.utils.formataddr(pair, charset='utf-8')¶
Обратное значение
parseaddr()
, принимает 2-кортеж вида(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
с соответствующим atimezone
tzinfo
.Added in version 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.Added in version 3.3.
- 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()
превращает его в строку юникода. Необязательное значение 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)
.
Сноски