`email.util.md`

95 строк · 12.1 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.2/library/email.util.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 18.1.9. [`email.utils`](https://python-all.ru/3.2/library/email.util.html#module-email.utils): Разные утилиты89Модуль [`email.utils`](https://python-all.ru/3.2/library/email.util.html#module-email.utils) предоставляет несколько полезных утилит:1011#### `email.utils.quote(str)`1213Возвращает новую строку, в которой обратная косая черта в *str* заменена двумя обратными косыми чертами, а двойные кавычки – на обратную косую черту с двойной кавычкой.1415#### `email.utils.unquote(str)`1617Возвращает новую строку, которая является *расквотированной* версией *str*. Если *str* начинается и заканчивается двойными кавычками, они удаляются. Аналогично, если *str* начинается и заканчивается угловыми скобками, они удаляются.1819#### `email.utils.parseaddr(address)`2021Разбирает адрес – который должен быть значением какого-либо поля, содержащего адрес, такого как *To* или *Cc* – на составляющие части: *realname* и *адрес электронной почты*. Возвращает кортеж с этой информацией, если только разбор не завершится ошибкой; в этом случае возвращается кортеж из двух элементов `('', '')`.2223#### `email.utils.formataddr(pair)`2425Обратная функция к [`parseaddr()`](https://python-all.ru/3.2/library/email.util.html#email.utils.parseaddr); принимает кортеж из двух элементов вида `(realname, email_address)` и возвращает строковое значение, подходящее для заголовка *To* или *Cc*. Если первый элемент *pair* равен false, то возвращается второй элемент без изменений.2627#### `email.utils.getaddresses(fieldvalues)`2829Этот метод возвращает список кортежей из двух элементов в том же формате, что и `parseaddr()`. *fieldvalues* – последовательность значений полей заголовка, как может быть возвращена методом `Message.get_all()`. Вот простой пример получения всех получателей сообщения:3031```python32from email.utils import getaddresses3334tos = msg.get_all('to', [])35ccs = msg.get_all('cc', [])36resent_tos = msg.get_all('resent-to', [])37resent_ccs = msg.get_all('resent-cc', [])38all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)39```4041#### `email.utils.parsedate(date)`4243Пытается разобрать дату в соответствии с правилами [**RFC 2822**](https://python-all.ru/3.2/library/email.util.html). Однако некоторые почтовые программы не следуют этому формату, поэтому [`parsedate()`](https://python-all.ru/3.2/library/email.util.html#email.utils.parsedate) старается правильно угадать в таких случаях. *date* – строка, содержащая дату в формате [**RFC 2822**](https://python-all.ru/3.2/library/email.util.html), например `"Mon, 20 Nov 1995 19:12:08 -0500"`. Если разбор выполнен успешно, [`parsedate()`](https://python-all.ru/3.2/library/email.util.html#email.utils.parsedate) возвращает кортеж из 9 элементов, который можно напрямую передать [`time.mktime()`](https://python-all.ru/3.2/library/time.html#time.mktime); иначе возвращается `None`. Обратите внимание, что индексы 6, 7 и 8 результирующего кортежа непригодны для использования.4445#### `email.utils.parsedate_tz(date)`4647Выполняет ту же функцию, что и [`parsedate()`](https://python-all.ru/3.2/library/email.util.html#email.utils.parsedate), но возвращает либо `None`, либо кортеж из 10 элементов; первые 9 элементов образуют кортеж, который можно напрямую передать [`time.mktime()`](https://python-all.ru/3.2/library/time.html#time.mktime), а десятый – смещение часового пояса даты от UTC (официальный термин для среднего времени по Гринвичу) [\[1\]](https://python-all.ru/3.2/library/email.util.html#id2). Если входная строка не содержит часового пояса, последним элементом возвращаемого кортежа будет `None`. Обратите внимание, что индексы 6, 7 и 8 результирующего кортежа непригодны для использования.4849#### `email.utils.mktime_tz(tuple)`5051Преобразует 10-кортеж, возвращаемый [`parsedate_tz()`](https://python-all.ru/3.2/library/email.util.html#email.utils.parsedate_tz), в метку времени UTC. Если элемент часового пояса в кортеже равен `None`, предполагается местное время. Небольшой недостаток: [`mktime_tz()`](https://python-all.ru/3.2/library/email.util.html#email.utils.mktime_tz) интерпретирует первые 8 элементов *tuple* как местное время, а затем компенсирует разницу часовых поясов. Это может привести к небольшой ошибке при переходе на летнее время, но для обычного использования это несущественно.5253#### `email.utils.formatdate(timeval=None, localtime=False, usegmt=False)`5455Возвращает строку даты в соответствии с [**RFC 2822**](https://python-all.ru/3.2/library/email.util.html), например:5657```python58Fri, 09 Nov 2001 01:08:47 -000059```6061Необязательный параметр *timeval*, если указан, представляет собой время в виде числа с плавающей запятой, как принимается [`time.gmtime()`](https://python-all.ru/3.2/library/time.html#time.gmtime) и [`time.localtime()`](https://python-all.ru/3.2/library/time.html#time.localtime); в противном случае используется текущее время.6263Необязательный параметр *localtime* – флаг; если он равен `True`, то *timeval* интерпретируется и возвращается дата относительно местного часового пояса, а не UTC, с правильным учётом летнего времени. По умолчанию `False`, то есть используется UTC.6465Необязательный параметр *usegmt* – флаг; если он равен `True`, то выводится строка даты с часовым поясом в виде ASCII-строки `GMT`, а не числового `-0000`. Это необходимо для некоторых протоколов (например, HTTP). Применяется только когда *localtime* равно `False`. По умолчанию `False`.6667#### `email.utils.make_msgid(idstring=None, domain=None)`6869Возвращает строку, подходящую для [**RFC 2822**](https://python-all.ru/3.2/library/email.util.html)-совместимого *Message-ID* заголовка. Необязательный *idstring*, если задан, представляет собой строку, используемую для усиления уникальности идентификатора сообщения. Необязательный *domain*, если задан, указывает часть msgid после символа '@'. По умолчанию используется локальное имя хоста. Обычно нет необходимости переопределять это значение, но это может быть полезно в определенных случаях, например, при создании распределенной системы, которая использует единое доменное имя на нескольких хостах.7071Изменено в версии 3.2: добавлен ключевой аргумент domain7273#### `email.utils.decode_rfc2231(s)`7475Декодирует строку *s* в соответствии с [**RFC 2231**](https://python-all.ru/3.2/library/email.util.html).7677#### `email.utils.encode_rfc2231(s, charset=None, language=None)`7879Кодирует строку *s* в соответствии с [**RFC 2231**](https://python-all.ru/3.2/library/email.util.html). Необязательные параметры *charset* и *language*, если заданы, указывают имя кодировки и язык. Если ни один не задан, *s* возвращается как есть. Если *charset* задан, а *language* нет, строка кодируется с пустой строкой для *language*.8081#### `email.utils.collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')`8283When a header parameter is encoded in [**RFC 2231**](https://python-all.ru/3.2/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.2/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.2/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.2/library/email.util.html) header is not known by Python; it defaults to `'us-ascii'`.8485Для удобства, если *значение*, переданное в [`collapse_rfc2231_value()`](https://python-all.ru/3.2/library/email.util.html#email.utils.collapse_rfc2231_value), не является кортежем, оно должно быть строкой и возвращается без кавычек.8687#### `email.utils.decode_params(params)`8889Декодировать список параметров в соответствии с [**RFC 2231**](https://python-all.ru/3.2/library/email.util.html). *params* – это последовательность кортежей из двух элементов вида `(content-type, string-value)`.9091Сноски9293| [\[1\]](https://python-all.ru/3.2/library/email.util.html#id1) | Обратите внимание, что знак смещения часового пояса противоположен знаку переменной `time.timezone` для того же часового пояса; последняя переменная следует стандарту POSIX, в то время как данный модуль следует [**RFC 2822**](https://python-all.ru/3.2/library/email.util.html). |94| --- | --- |95