> **Источник:** https://python-all.ru/3.3/library/email.util.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# 19.1.11. [`email.utils`](https://python-all.ru/3.3/library/email.util.html#module-email.utils): Разные утилиты

Модуль [`email.utils`](https://python-all.ru/3.3/library/email.util.html#module-email.utils) предоставляет несколько полезных утилит:

#### `email.utils.quote(str)`

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

#### `email.utils.unquote(str)`

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

#### `email.utils.parseaddr(address)`

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

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

Обратная функция к [`parseaddr()`](https://python-all.ru/3.3/library/email.util.html#email.utils.parseaddr); принимает кортеж из двух элементов вида `(realname, email_address)` и возвращает строковое значение, подходящее для заголовка *To* или *Cc*. Если первый элемент *pair* равен false, то возвращается второй элемент без изменений.

Необязательный параметр *charset* – это кодировка, которая будет использоваться в [**RFC 2047**](https://python-all.ru/3.3/library/email.util.html) кодировании `realname`, если `realname` содержит символы не ASCII. Может быть экземпляром [`str`](https://python-all.ru/3.3/library/stdtypes.html#str) или [`Charset`](https://python-all.ru/3.3/library/email.charset.html#email.charset.Charset). По умолчанию `utf-8`.

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

#### `email.utils.getaddresses(fieldvalues)`

Этот метод возвращает список кортежей из двух элементов в том же формате, что и `parseaddr()`. *fieldvalues* – это последовательность значений полей заголовка, как может быть возвращено методом [`Message.get_all`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.get_all). Вот простой пример, который получает всех получателей сообщения:

```python
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**](https://python-all.ru/3.3/library/email.util.html). Однако некоторые почтовые программы не следуют этому формату, поэтому [`parsedate()`](https://python-all.ru/3.3/library/email.util.html#email.utils.parsedate) старается правильно угадать в таких случаях. *date* – строка, содержащая дату в формате [**RFC 2822**](https://python-all.ru/3.3/library/email.util.html), например `"Mon, 20 Nov 1995 19:12:08 -0500"`. Если разбор выполнен успешно, [`parsedate()`](https://python-all.ru/3.3/library/email.util.html#email.utils.parsedate) возвращает кортеж из 9 элементов, который можно напрямую передать [`time.mktime()`](https://python-all.ru/3.3/library/time.html#time.mktime); иначе возвращается `None`. Обратите внимание, что индексы 6, 7 и 8 результирующего кортежа непригодны для использования.

#### `email.utils.parsedate_tz(date)`

Выполняет ту же функцию, что и [`parsedate()`](https://python-all.ru/3.3/library/email.util.html#email.utils.parsedate), но возвращает либо `None`, либо кортеж из 10 элементов; первые 9 элементов образуют кортеж, который можно напрямую передать [`time.mktime()`](https://python-all.ru/3.3/library/time.html#time.mktime), а десятый – смещение часового пояса даты от UTC (официальный термин для среднего времени по Гринвичу) [\[1\]](https://python-all.ru/3.3/library/email.util.html#id2). Если входная строка не содержит часового пояса, последним элементом возвращаемого кортежа будет `None`. Обратите внимание, что индексы 6, 7 и 8 результирующего кортежа непригодны для использования.

#### `email.utils.parsedate_to_datetime(date)`

Обратная функция к [`format_datetime()`](https://python-all.ru/3.3/library/email.util.html#email.utils.format_datetime). Выполняет ту же функцию, что и [`parsedate()`](https://python-all.ru/3.3/library/email.util.html#email.utils.parsedate), но в случае успеха возвращает [`datetime`](https://python-all.ru/3.3/library/datetime.html#datetime.datetime). Если входная дата имеет часовой пояс `-0000`, `datetime` будет наивным `datetime`, и если дата соответствует RFC, она будет представлять время в UTC, но без указания фактического исходного часового пояса сообщения, из которого взята дата. Если входная дата имеет любое другое допустимое смещение часового пояса, `datetime` будет осознанным (aware) `datetime` с соответствующим [`timezone`](https://python-all.ru/3.3/library/datetime.html#datetime.timezone) [`tzinfo`](https://python-all.ru/3.3/library/datetime.html#datetime.tzinfo).

Новое в версии 3.3.

#### `email.utils.mktime_tz(tuple)`

Преобразует 10-кортеж, возвращаемый [`parsedate_tz()`](https://python-all.ru/3.3/library/email.util.html#email.utils.parsedate_tz), в метку времени UTC. Если элемент часового пояса в кортеже равен `None`, предполагается местное время. Небольшой недостаток: [`mktime_tz()`](https://python-all.ru/3.3/library/email.util.html#email.utils.mktime_tz) интерпретирует первые 8 элементов *tuple* как местное время, а затем компенсирует разницу часовых поясов. Это может привести к небольшой ошибке при переходе на летнее время, но для обычного использования это несущественно.

#### `email.utils.formatdate(timeval=None, localtime=False, usegmt=False)`

Возвращает строку даты в соответствии с [**RFC 2822**](https://python-all.ru/3.3/library/email.util.html), например:

```python
Fri, 09 Nov 2001 01:08:47 -0000
```

Необязательный параметр *timeval*, если указан, представляет собой время в виде числа с плавающей запятой, как принимается [`time.gmtime()`](https://python-all.ru/3.3/library/time.html#time.gmtime) и [`time.localtime()`](https://python-all.ru/3.3/library/time.html#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`](https://python-all.ru/3.3/library/datetime.html#module-datetime). Если это наивный datetime, он считается «UTC без информации об исходном часовом поясе», и для часового пояса используется обычное `-0000`. Если это осознанный `datetime`, то используется числовое смещение часового пояса. Если это осознанный часовой пояс с нулевым смещением, то *usegmt* может быть установлен в `True`, и тогда вместо числового смещения используется строка `GMT`. Это позволяет создавать соответствующие стандартам HTTP-заголовки даты.

Новое в версии 3.3.

#### `email.utils.localtime(dt=None)`

Возвращает местное время в виде осознанного объекта datetime. Если вызвана без аргументов, возвращает текущее время. В противном случае аргумент *dt* должен быть экземпляром [`datetime`](https://python-all.ru/3.3/library/datetime.html#datetime.datetime), и он преобразуется в местный часовой пояс в соответствии с системной базой данных часовых поясов. Если *dt* наивный (то есть `dt.tzinfo` равен `None`), считается, что он уже в местном времени. В этом случае положительное или нулевое значение *isdst* заставляет `localtime` изначально предполагать, что летнее время (например, переход на летнее время) действует или не действует (соответственно) для указанного времени. Отрицательное значение *isdst* заставляет `localtime` пытаться определить, действует ли летнее время для указанного времени.

Новое в версии 3.3.

#### `email.utils.make_msgid(idstring=None, domain=None)`

Возвращает строку, подходящую для [**RFC 2822**](https://python-all.ru/3.3/library/email.util.html)-совместимого *Message-ID* заголовка. Необязательный *idstring*, если задан, представляет собой строку, используемую для усиления уникальности идентификатора сообщения. Необязательный *domain*, если задан, указывает часть msgid после символа '@'. По умолчанию используется локальное имя хоста. Обычно нет необходимости переопределять это значение, но это может быть полезно в определенных случаях, например, при создании распределенной системы, которая использует единое доменное имя на нескольких хостах.

Изменено в версии 3.2: Добавлен параметр *domain*.

#### `email.utils.decode_rfc2231(s)`

Декодирует строку *s* в соответствии с [**RFC 2231**](https://python-all.ru/3.3/library/email.util.html).

#### `email.utils.encode_rfc2231(s, charset=None, language=None)`

Кодирует строку *s* в соответствии с [**RFC 2231**](https://python-all.ru/3.3/library/email.util.html). Необязательные параметры *charset* и *language*, если заданы, указывают имя кодировки и язык. Если ни один не задан, *s* возвращается как есть. Если *charset* задан, а *language* нет, строка кодируется с пустой строкой для *language*.

#### `email.utils.collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')`

Когда параметр заголовка закодирован в формате [**RFC 2231**](https://python-all.ru/3.3/library/email.util.html), [`Message.get_param`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.get_param) может вернуть кортеж из трёх элементов, содержащий кодировку, язык и значение. [`collapse_rfc2231_value()`](https://python-all.ru/3.3/library/email.util.html#email.utils.collapse_rfc2231_value) преобразует его в строку Unicode. Необязательный параметр *errors* передаётся в аргумент *errors* метода [`str`](https://python-all.ru/3.3/library/stdtypes.html#str). [`encode()`](https://python-all.ru/3.3/library/stdtypes.html#str.encode); по умолчанию `'replace'`. Необязательный *fallback\_charset* задаёт кодировку, которая будет использоваться, если кодировка из заголовка [**RFC 2231**](https://python-all.ru/3.3/library/email.util.html) неизвестна Python; по умолчанию `'us-ascii'`.

Для удобства, если *значение*, переданное в [`collapse_rfc2231_value()`](https://python-all.ru/3.3/library/email.util.html#email.utils.collapse_rfc2231_value), не является кортежем, оно должно быть строкой и возвращается без кавычек.

#### `email.utils.decode_params(params)`

Декодировать список параметров в соответствии с [**RFC 2231**](https://python-all.ru/3.3/library/email.util.html). *params* – это последовательность кортежей из двух элементов вида `(content-type, string-value)`.

Сноски

| [\[1\]](https://python-all.ru/3.3/library/email.util.html#id1) | Обратите внимание, что знак смещения часового пояса противоположен знаку переменной `time.timezone` для того же часового пояса; последняя переменная следует стандарту POSIX, в то время как данный модуль следует [**RFC 2822**](https://python-all.ru/3.3/library/email.util.html). |
| --- | --- |