email.utils: Разные утилиты

Исходный код: 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)

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

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]. Если у входной строки нет часового пояса, последний элемент возвращаемого кортежа — 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 может возвращать кортеж из трёх элементов: кодировка, язык и значение. collapse_rfc2231_value() преобразует его в строку Юникод. Необязательный аргумент errors передаётся в аргумент errors метода str’s encode(); по умолчанию он равен 'replace'. Необязательный fallback_charset задаёт набор символов, который нужно использовать, если набор символов из заголовка RFC 2231 не известен Python; по умолчанию он равен 'us-ascii'.

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

email.utils.decode_params(params)

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

Примечания