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

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

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

email.utils.localtime(dt=None): Возвращает локальное время в виде объекта datetime с часовым поясом. Если функция вызвана без аргументов, возвращается текущее время. В противном случае аргумент dt должен быть экземпляром datetime; он преобразуется в локальный часовой пояс в соответствии с системной базой данных часовых поясов. Если dt не содержит часового пояса (то есть dt.tzinfo равно None), предполагается, что время указано в локальном часовом поясе.

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

Устарело с версии 3.12, удалено в версии 3.14: Параметр isdst.

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

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

Если strict имеет значение true, используется строгий анализатор, отклоняющий некорректные входные данные.

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

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

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

Необязательный параметр charset задаёт кодировку, используемую при кодировании в формате RFC 2047 значения realname, если realname содержит символы, отличные от ASCII. Это может быть экземпляр str или Charset. По умолчанию используется utf-8.

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

email.utils.getaddresses(fieldvalues, *, strict=True)

Этот метод возвращает список 2-элементных кортежей в формате, возвращаемом функцией 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)

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). Применяется только при значении False для localtime. По умолчанию используется 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 может вернуть 3-элементный кортеж, содержащий кодировку, язык и значение. collapse_rfc2231_value() преобразует его в строку. Необязательный параметр errors передаётся в аргумент errors метода encode() объекта str; по умолчанию используется '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).

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

Сноски