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, *, strict=True)

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

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

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, *, 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 с соответствующим объектом 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 — это последовательность кортежей из 2 элементов, содержащих элементы вида (content-type, string-value).

Примечания