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)

Возвращает значение строка, подходящее для заголовка RFC 2822-совместимого Message-ID. Необязательный idstring, если задан, является строка используемый для усиления уникальности сообщения id. Необязательный domain, если задан, предоставляет часть msgid после «@». По умолчанию используется имя узла локальная. Обычно нет необходимости переопределять это значение по умолчанию, но могут быть полезны некоторые случаи, такие как создание распределенной системы, использующей согласованное имя домена на нескольких хостах.

Изменено в версии 3.2: Добавлен domain ключевой аргумент.

Остальные функции являются частью устаревшего API электронной почты (Compat32). Нет никакой потребности непосредственно использовать их с новым API, начиная с парсинг и форматирования, они обеспечивают, сделан автоматически заголовком механизм парсинг нового API.

email.utils.quote(str)

Возвращает новая строка с обратной косой чертой в str заменена двумя обратной косой чертой, а двойные кавычки заменены обратной косой чертой.

email.utils.unquote(str)

Возвращает новый строка, который является unquoted версией 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 является ложным, то второй элемент является возвращенныйunmodified.

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

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

email.utils.getaddresses(fieldvalues)

Этот метод возвращает список 2-кортежей формы возвращенныйby parseaddr(). fieldvalues представляет собой последовательность полей заголовка значения, как это может быть возвращенныйby 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]. Если входной строка не имеет часового пояса, последний элемент кортежа возвращенныйis 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 кортежами как возвращенныйby 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 может возвращает с 3 кортежами содержащий набор символ, язык и значение. collapse_rfc2231_value() превращает это в Юникод строка. Дополнительный errors передан к аргументу errors метода str 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).

Сноски

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