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 для работы с email. Нет необходимости использовать их напрямую с новым 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 — это кодировка символов, которая будет использоваться в кодировании RFC 2047 части realname если realname содержит не-ASCII символы. Может быть экземпляром str или Charset. По умолчанию utf-8.

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

email.utils.getaddresses(fieldvalues)

Этот метод возвращает список 2-кортежей, аналогичных тем, которые возвращаются 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. Если в входной строке нет часового пояса, последний элемент возвращаемого кортежа — None. Обратите внимание, что индексы 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 может возвращать кортеж из трёх элементов: кодировки символов, языка и значения. 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.