email.utils.md

1> **Источник:** https://python-all.ru/3.9/library/email.utils.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`email.utils`](https://python-all.ru/3.9/library/email.utils.html#module-email.utils): Разные утилиты89**Исходный код:** [Lib/email/utils.py](https://python-all.ru/src/3.9/Lib/email/utils.py)1011---1213В модуле [`email.utils`](https://python-all.ru/3.9/library/email.utils.html#module-email.utils) содержатся несколько полезных утилит:1415#### `email.utils.localtime(dt=None)`1617Возвращает местное время как осведомлённый объект datetime. При вызове без аргументов возвращает текущее время. В противном случае аргумент *dt* должен быть экземпляром [`datetime`](https://python-all.ru/3.9/library/datetime.html#datetime.datetime), и он преобразуется в местный часовой пояс согласно системной базе данных часовых поясов. Если *dt* наивный (то есть `dt.tzinfo` равно `None`), считается, что он задан в местном времени. В этом случае положительное или нулевое значение *isdst* заставляет `localtime` изначально предполагать, что летнее время (например, Daylight Saving Time) действует или не действует (соответственно) для указанного времени. Отрицательное значение *isdst* заставляет `localtime` пытаться определить, действует ли летнее время для указанного времени.1819Новое в версии 3.3.2021#### `email.utils.make_msgid(idstring=None, domain=None)`2223Возвращает строку, подходящую для [**RFC 2822**](https://python-all.ru/3.9/library/email.utils.html)-совместимого *Message-ID* заголовка. Необязательный *idstring*, если задан, представляет собой строку, используемую для усиления уникальности идентификатора сообщения. Необязательный *domain*, если задан, указывает часть msgid после символа '@'. По умолчанию используется локальное имя хоста. Обычно нет необходимости переопределять это значение, но это может быть полезно в определенных случаях, например, при создании распределенной системы, которая использует единое доменное имя на нескольких хостах.2425Изменено в версии 3.2: Добавлен параметр *domain*.2627Остальные функции являются частью устаревшего (`Compat32`) API электронной почты. Нет необходимости использовать их напрямую с новым API, так как синтаксический анализ и форматирование, которые они предоставляют, выполняются автоматически механизмом разбора заголовков нового API.2829#### `email.utils.quote(str)`3031Возвращает новую строку, в которой обратная косая черта в *str* заменена двумя обратными косыми чертами, а двойные кавычки – на обратную косую черту с двойной кавычкой.3233#### `email.utils.unquote(str)`3435Возвращает новую строку, которая является *расквотированной* версией *str*. Если *str* начинается и заканчивается двойными кавычками, они удаляются. Аналогично, если *str* начинается и заканчивается угловыми скобками, они удаляются.3637#### `email.utils.parseaddr(address, *, strict=True)`3839Разбирает адрес – который должен быть значением какого-либо поля, содержащего адрес, такого как *To* или *Cc* – на составляющие части: *realname* и *адрес электронной почты*. Возвращает кортеж с этой информацией, если только разбор не завершится ошибкой; в этом случае возвращается кортеж из двух элементов `('', '')`.4041Если *strict* имеет значение true, используется строгий анализатор, который отклоняет некорректные входные данные.4243Изменено в версии 3.9.20: Добавлен необязательный параметр *strict* и по умолчанию отклоняются некорректные входные данные.4445#### `email.utils.formataddr(pair, charset='utf-8')`4647Обратная функция к [`parseaddr()`](https://python-all.ru/3.9/library/email.utils.html#email.utils.parseaddr), она принимает кортеж из двух элементов вида `(realname, email_address)` и возвращает строковое значение, подходящее для заголовка *To* или *Cc*. Если первый элемент *pair* равен false, то второй элемент возвращается без изменений.4849Необязательный *charset* – это набор символов, который будет использоваться в [**RFC 2047**](https://python-all.ru/3.9/library/email.utils.html) кодировке `realname`, если `realname` содержит не-ASCII символы. Может быть экземпляром [`str`](https://python-all.ru/3.9/library/stdtypes.html#str) или [`Charset`](https://python-all.ru/3.9/library/email.charset.html#email.charset.Charset). По умолчанию равен `utf-8`.5051Изменено в версии 3.3: Добавлена опция *charset*.5253#### `email.utils.getaddresses(fieldvalues, *, strict=True)`5455Этот метод возвращает список кортежей из двух элементов вида, возвращаемого `parseaddr()`. *fieldvalues* – это последовательность значений полей заголовка, которые могут быть возвращены [`Message.get_all`](https://python-all.ru/3.9/library/email.compat32-message.html#email.message.Message.get_all).5657Если *strict* имеет значение true, используется строгий анализатор, который отклоняет некорректные входные данные.5859Вот простой пример, который получает всех получателей сообщения:6061```python62from email.utils import getaddresses6364tos = msg.get_all('to', [])65ccs = msg.get_all('cc', [])66resent_tos = msg.get_all('resent-to', [])67resent_ccs = msg.get_all('resent-cc', [])68all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)69```7071Изменено в версии 3.9.20: Добавлен необязательный параметр *strict* и по умолчанию отклоняются некорректные входные данные.7273#### `email.utils.parsedate(date)`7475Пытается разобрать дату в соответствии с правилами [**RFC 2822**](https://python-all.ru/3.9/library/email.utils.html). Однако некоторые почтовые программы не следуют этому формату, поэтому [`parsedate()`](https://python-all.ru/3.9/library/email.utils.html#email.utils.parsedate) пытается правильно угадать дату в таких случаях. *date* – это строка, содержащая дату в формате [**RFC 2822**](https://python-all.ru/3.9/library/email.utils.html), например, `"Mon, 20 Nov 1995 19:12:08 -0500"`. Если разбор даты успешен, [`parsedate()`](https://python-all.ru/3.9/library/email.utils.html#email.utils.parsedate) возвращает кортеж из 9 элементов, который можно напрямую передать в [`time.mktime()`](https://python-all.ru/3.9/library/time.html#time.mktime); в противном случае возвращается `None`. Обратите внимание, что индексы 6, 7 и 8 кортежа результата не пригодны для использования.7677#### `email.utils.parsedate_tz(date)`7879Выполняет ту же функцию, что и [`parsedate()`](https://python-all.ru/3.9/library/email.utils.html#email.utils.parsedate), но возвращает либо `None`, либо кортеж из 10 элементов; первые 9 элементов составляют кортеж, который можно напрямую передать в [`time.mktime()`](https://python-all.ru/3.9/library/time.html#time.mktime), а десятый – это смещение часового пояса даты от UTC (официальный термин для среднего времени по Гринвичу) [1](https://python-all.ru/3.9/library/email.utils.html#id2). Если входная строка не содержит часового пояса, последним элементом возвращаемого кортежа является `0`, что представляет UTC. Обратите внимание, что индексы 6, 7 и 8 кортежа результата не пригодны для использования.8081#### `email.utils.parsedate_to_datetime(date)`8283Обратная операция к [`format_datetime()`](https://python-all.ru/3.9/library/email.utils.html#email.utils.format_datetime). Выполняет ту же функцию, что и [`parsedate()`](https://python-all.ru/3.9/library/email.utils.html#email.utils.parsedate), но в случае успеха возвращает [`datetime`](https://python-all.ru/3.9/library/datetime.html#datetime.datetime). Если входная дата имеет часовой пояс `-0000`, то `datetime` будет наивным `datetime`, и если дата соответствует RFC, она будет представлять время в UTC, но без указания исходного часового пояса сообщения, из которого получена дата. Если входная дата имеет любое другое допустимое смещение часового пояса, то `datetime` будет осведомлённым `datetime` с соответствующим [`timezone`](https://python-all.ru/3.9/library/datetime.html#datetime.timezone) [`tzinfo`](https://python-all.ru/3.9/library/datetime.html#datetime.tzinfo).8485Новое в версии 3.3.8687#### `email.utils.mktime_tz(tuple)`8889Преобразует 10-элементный кортеж, возвращаемый функцией [`parsedate_tz()`](https://python-all.ru/3.9/library/email.utils.html#email.utils.parsedate_tz), в метку времени UTC (секунды с начала эпохи). Если элемент часового пояса в кортеже равен `None`, предполагается местное время.9091#### `email.utils.formatdate(timeval=None, localtime=False, usegmt=False)`9293Возвращает строку даты в соответствии с [**RFC 2822**](https://python-all.ru/3.9/library/email.utils.html), например:9495```python96Fri, 09 Nov 2001 01:08:47 -000097```9899Необязательный *timeval*, если задан, представляет собой вещественное значение времени, принимаемое [`time.gmtime()`](https://python-all.ru/3.9/library/time.html#time.gmtime) и [`time.localtime()`](https://python-all.ru/3.9/library/time.html#time.localtime); в противном случае используется текущее время.100101Необязательный флаг *localtime*: если `True`, интерпретирует *timeval* и возвращает дату относительно местного часового пояса вместо UTC, с учётом перехода на летнее время. По умолчанию `False`, то есть используется UTC.102103Необязательный флаг *usegmt*: если `True`, выводит строку даты с часовым поясом в виде ASCII-строки `GMT`, а не числового `-0000`. Это необходимо для некоторых протоколов (например, HTTP). Применяется только когда *localtime* равен `False`. По умолчанию `False`.104105#### `email.utils.format_datetime(dt, usegmt=False)`106107Как и `formatdate`, но ввод – это экземпляр [`datetime`](https://python-all.ru/3.9/library/datetime.html#module-datetime). Если это наивный datetime, считается, что это «UTC без информации об исходном часовом поясе», и для часового пояса используется стандартное `-0000`. Если это осознанный `datetime`, используется числовое смещение часового пояса. Если это осознанный часовой пояс с нулевым смещением, то *usegmt* может быть установлен в `True`, и в этом случае вместо числового смещения часового пояса используется строка `GMT`. Это даёт способ генерировать соответствующие стандартам HTTP-заголовки даты.108109Новое в версии 3.3.110111#### `email.utils.decode_rfc2231(s)`112113Декодирует строку *s* в соответствии с [**RFC 2231**](https://python-all.ru/3.9/library/email.utils.html).114115#### `email.utils.encode_rfc2231(s, charset=None, language=None)`116117Кодирует строку *s* в соответствии с [**RFC 2231**](https://python-all.ru/3.9/library/email.utils.html). Необязательные параметры *charset* и *language*, если заданы, указывают имя кодировки и язык. Если ни один не задан, *s* возвращается как есть. Если *charset* задан, а *language* нет, строка кодируется с пустой строкой для *language*.118119#### `email.utils.collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')`120121Когда параметр заголовка закодирован в формате [**RFC 2231**](https://python-all.ru/3.9/library/email.utils.html), [`Message.get_param`](https://python-all.ru/3.9/library/email.compat32-message.html#email.message.Message.get_param) может вернуть 3-элементный кортеж, содержащий кодировку, язык и значение. [`collapse_rfc2231_value()`](https://python-all.ru/3.9/library/email.utils.html#email.utils.collapse_rfc2231_value) преобразует это в строку Unicode. Необязательный параметр *errors* передаётся в аргумент *errors* метода [`str`](https://python-all.ru/3.9/library/stdtypes.html#str) [`encode()`](https://python-all.ru/3.9/library/stdtypes.html#str.encode); по умолчанию `'replace'`. Необязательный *fallback\_charset* указывает кодировку, используемую, если кодировка из [**RFC 2231**](https://python-all.ru/3.9/library/email.utils.html) неизвестна Python; по умолчанию `'us-ascii'`.122123Для удобства, если *value*, переданное в [`collapse_rfc2231_value()`](https://python-all.ru/3.9/library/email.utils.html#email.utils.collapse_rfc2231_value), не является кортежем, оно должно быть строкой и возвращается без кавычек.124125#### `email.utils.decode_params(params)`126127Декодирует список параметров в соответствии с [**RFC 2231**](https://python-all.ru/3.9/library/email.utils.html). *params* – это последовательность 2-элементных кортежей, содержащих элементы вида `(content-type, string-value)`.128129Сноски130131**[1](https://python-all.ru/3.9/library/email.utils.html#id1)**132133Обратите внимание, что знак смещения часового пояса противоположен знаку переменной `time.timezone` для того же часового пояса; последняя переменная следует стандарту POSIX, тогда как этот модуль следует [**RFC 2822**](https://python-all.ru/3.9/library/email.utils.html).134