email.utils: Разные утилиты для работы с почтой

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

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

email.utils.localtime(dt=None)

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

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

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

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

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

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

Необязательный аргумент charset — это кодировка символов, которая будет использована при кодировании realname с помощью RFC 2047, если 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. Если у входной даты часовой пояс -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. Необязательные параметры 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’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).

Примечания

1

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