`email.util.md`

285 строк · 11.4 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.1/library/email.util.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 18.1.9. [`email`](https://python-all.ru/3.1/library/email.html#module-email): Разные утилиты89Модуль `email.utils` предоставляет несколько полезных утилит:1011#### `email.utils.quote(str)`1213Возвращает новую строку, в которой обратная косая черта в1415*str*1617заменена двумя обратными косыми чертами, а двойные кавычки – на обратную косую черту с двойной кавычкой.1819#### `email.utils.unquote(str)`2021Возвращает новую строку, которая является2223*расквотированной*2425версией2627*str*2829. Если3031*str*3233начинается и заканчивается двойными кавычками, они удаляются. Аналогично, если3435*str*3637начинается и заканчивается угловыми скобками, они удаляются.3839#### `email.utils.parseaddr(address)`4041Разбирает адрес – который должен быть значением какого-либо поля, содержащего адрес, такого как4243*To*4445или4647*Cc*4849– на составляющие части:5051*realname*5253и5455*адрес электронной почты*5657. Возвращает кортеж с этой информацией, если только разбор не завершится ошибкой; в этом случае возвращается кортеж из двух элементов5859`('', '')`6061.6263#### `email.utils.formataddr(pair)`6465Обратная функция к6667[`parseaddr()`](https://python-all.ru/3.1/library/email.util.html#email.utils.parseaddr)6869; принимает кортеж из двух элементов вида7071`(realname, email_address)`7273и возвращает строковое значение, подходящее для заголовка7475*To*7677или7879*Cc*8081. Если первый элемент8283*pair*8485равен false, то возвращается второй элемент без изменений.8687#### `email.utils.getaddresses(fieldvalues)`8889Этот метод возвращает список кортежей из двух элементов в том же формате, что и `parseaddr()`. *fieldvalues* – последовательность значений полей заголовка, как может быть возвращена методом `Message.get_all()`. Вот простой пример получения всех получателей сообщения:9091```python92from email.utils import getaddresses9394tos = msg.get_all('to', [])95ccs = msg.get_all('cc', [])96resent_tos = msg.get_all('resent-to', [])97resent_ccs = msg.get_all('resent-cc', [])98all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)99```100101#### `email.utils.parsedate(date)`102103Пытается разобрать дату в соответствии с правилами104105[**RFC 2822**](https://python-all.ru/3.1/library/email.util.html)106107. Однако некоторые почтовые программы не следуют этому формату, поэтому108109[`parsedate()`](https://python-all.ru/3.1/library/email.util.html#email.utils.parsedate)110111старается правильно угадать в таких случаях.112113*date*114115– строка, содержащая дату в формате116117[**RFC 2822**](https://python-all.ru/3.1/library/email.util.html)118119, например120121`"Mon, 20 Nov 1995 19:12:08 -0500"`122123. Если разбор выполнен успешно,124125[`parsedate()`](https://python-all.ru/3.1/library/email.util.html#email.utils.parsedate)126127возвращает кортеж из 9 элементов, который можно напрямую передать128129[`time.mktime()`](https://python-all.ru/3.1/library/time.html#time.mktime)130131; иначе возвращается132133`None`134135. Обратите внимание, что индексы 6, 7 и 8 результирующего кортежа непригодны для использования.136137#### `email.utils.parsedate_tz(date)`138139Выполняет ту же функцию, что и140141[`parsedate()`](https://python-all.ru/3.1/library/email.util.html#email.utils.parsedate)142143, но возвращает либо144145`None`146147, либо кортеж из 10 элементов; первые 9 элементов образуют кортеж, который можно напрямую передать148149[`time.mktime()`](https://python-all.ru/3.1/library/time.html#time.mktime)150151, а десятый – смещение часового пояса даты от UTC (официальный термин для среднего времени по Гринвичу)152153[\[1\]](https://python-all.ru/3.1/library/email.util.html#id2)154155. Если входная строка не содержит часового пояса, последним элементом возвращаемого кортежа будет156157`None`158159. Обратите внимание, что индексы 6, 7 и 8 результирующего кортежа непригодны для использования.160161#### `email.utils.mktime_tz(tuple)`162163Преобразует 10-кортеж, возвращаемый164165[`parsedate_tz()`](https://python-all.ru/3.1/library/email.util.html#email.utils.parsedate_tz)166167, в метку времени UTC. Если элемент часового пояса в кортеже равен168169`None`170171, предполагается местное время. Небольшой недостаток:172173[`mktime_tz()`](https://python-all.ru/3.1/library/email.util.html#email.utils.mktime_tz)174175интерпретирует первые 8 элементов176177*tuple*178179как местное время, а затем компенсирует разницу часовых поясов. Это может привести к небольшой ошибке при переходе на летнее время, но для обычного использования это несущественно.180181#### `email.utils.formatdate(timeval=None, localtime=False, usegmt=False)`182183Возвращает строку даты в соответствии с [**RFC 2822**](https://python-all.ru/3.1/library/email.util.html), например:184185```python186Fri, 09 Nov 2001 01:08:47 -0000187```188189Необязательный параметр *timeval*, если указан, представляет собой время в виде числа с плавающей запятой, как принимается [`time.gmtime()`](https://python-all.ru/3.1/library/time.html#time.gmtime) и [`time.localtime()`](https://python-all.ru/3.1/library/time.html#time.localtime); в противном случае используется текущее время.190191Необязательный параметр *localtime* – флаг; если он равен `True`, то *timeval* интерпретируется и возвращается дата относительно местного часового пояса, а не UTC, с правильным учётом летнего времени. По умолчанию `False`, то есть используется UTC.192193Необязательный параметр *usegmt* – флаг; если он равен `True`, то выводится строка даты с часовым поясом в виде ASCII-строки `GMT`, а не числового `-0000`. Это необходимо для некоторых протоколов (например, HTTP). Применяется только когда *localtime* равно `False`. По умолчанию `False`.194195#### `email.utils.make_msgid(idstring=None)`196197Возвращает строку, подходящую для198199[**RFC 2822**](https://python-all.ru/3.1/library/email.util.html)200201-совместимого202203*Message-ID*204205заголовка. Необязательный параметр206207*idstring*208209, если задан, представляет собой строку, используемую для усиления уникальности идентификатора сообщения.210211#### `email.utils.decode_rfc2231(s)`212213Декодирует строку214215*s*216217в соответствии с218219[**RFC 2231**](https://python-all.ru/3.1/library/email.util.html)220221.222223#### `email.utils.encode_rfc2231(s, charset=None, language=None)`224225Кодирует строку226227*s*228229в соответствии с230231[**RFC 2231**](https://python-all.ru/3.1/library/email.util.html)232233. Необязательные параметры234235*charset*236237и238239*language*240241, если заданы, указывают имя кодировки и язык. Если ни один не задан,242243*s*244245возвращается как есть. Если246247*charset*248249задан, а250251*language*252253нет, строка кодируется с пустой строкой для254255*language*256257.258259#### `email.utils.collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')`260261When a header parameter is encoded in [**RFC 2231**](https://python-all.ru/3.1/library/email.util.html) format, `Message.get_param()` may return a 3-tuple containing the character set, language, and value. [`collapse_rfc2231_value()`](https://python-all.ru/3.1/library/email.util.html#email.utils.collapse_rfc2231_value) turns this into a unicode string. Optional *errors* is passed to the *errors* argument of [`str`](https://python-all.ru/3.1/library/functions.html#str)‘s `encode()` method; it defaults to `'replace'`. Optional *fallback\_charset* specifies the character set to use if the one in the [**RFC 2231**](https://python-all.ru/3.1/library/email.util.html) header is not known by Python; it defaults to `'us-ascii'`.262263Для удобства, если *значение*, переданное в [`collapse_rfc2231_value()`](https://python-all.ru/3.1/library/email.util.html#email.utils.collapse_rfc2231_value), не является кортежем, оно должно быть строкой и возвращается без кавычек.264265#### `email.utils.decode_params(params)`266267Декодировать список параметров в соответствии с268269[**RFC 2231**](https://python-all.ru/3.1/library/email.util.html)270271.272273*params*274275– это последовательность кортежей из двух элементов вида276277`(content-type, string-value)`278279.280281Сноски282283| [\[1\]](https://python-all.ru/3.1/library/email.util.html#id1) | Обратите внимание, что знак смещения часового пояса противоположен знаку переменной `time.timezone` для того же часового пояса; последняя переменная следует стандарту POSIX, в то время как данный модуль следует [**RFC 2822**](https://python-all.ru/3.1/library/email.util.html). |284| --- | --- |285