`email.md`

145 строк · 23.1 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.0/library/email.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `email` – пакет для работы с электронной почтой и MIME89Пакет `email` – это библиотека для управления сообщениями электронной почты, включая MIME и другие документы на основе [**RFC 2822**](https://python-all.ru/3.0/library/email.html). Он *не* предназначен для отправки сообщений на SMTP ([**RFC 2821**](https://python-all.ru/3.0/library/email.html)), NNTP или другие серверы; эти функции выполняют модули вроде [`smtplib`](https://python-all.ru/3.0/library/smtplib.html#module-smtplib) и [`nntplib`](https://python-all.ru/3.0/library/nntplib.html#module-nntplib). Пакет `email` стремится быть максимально совместимым с RFC, поддерживая, помимо [**RFC 2822**](https://python-all.ru/3.0/library/email.html), такие связанные с MIME RFC, как [**RFC 2045**](https://python-all.ru/3.0/library/email.html), [**RFC 2046**](https://python-all.ru/3.0/library/email.html), [**RFC 2047**](https://python-all.ru/3.0/library/email.html) и [**RFC 2231**](https://python-all.ru/3.0/library/email.html).1011Главная отличительная особенность пакета `email` заключается в разделении синтаксического анализа и генерации сообщений электронной почты и внутреннего *представления в виде объектной модели*. Приложения, использующие пакет `email`, работают преимущественно с объектами; можно добавлять подобъекты в сообщения, удалять их, полностью перестраивать содержимое и т. д. Существуют отдельный синтаксический анализатор и отдельный генератор, которые выполняют преобразование из плоского текста в объектную модель и обратно. Также имеются удобные подклассы для некоторых распространённых типов MIME-объектов и несколько вспомогательных утилит для решения типовых задач, таких как извлечение и разбор значений полей сообщений, создание дат, соответствующих RFC, и т. д.1213В следующих разделах описывается функциональность пакета `email`. Порядок изложения соответствует типичному для приложений процессу: сообщение электронной почты читается как плоский текст из файла или другого источника, текст разбирается для создания объектной структуры сообщения, эта структура изменяется, и наконец, дерево объектов преобразуется обратно в плоский текст.1415Вполне возможно создать объектную структуру с нуля – т.е. полностью с самого начала. После этого можно выполнить те же шаги, что описаны выше.1617Также включены подробные спецификации всех классов и модулей, предоставляемых пакетом `email`, классы исключений, которые могут возникнуть при использовании пакета `email`, некоторые вспомогательные утилиты и несколько примеров. Для пользователей старого пакета `mimelib` или предыдущих версий пакета `email` предусмотрен раздел о различиях и переходе.1819Содержание документации пакета `email`:2021- [`email`: Представление email-сообщения](https://python-all.ru/3.0/library/email.message.html)22- [`email`: Разбор email-сообщений](https://python-all.ru/3.0/library/email.parser.html)2324  - [API FeedParser](https://python-all.ru/3.0/library/email.parser.html#feedparser-api)25  - [API класса Parser](https://python-all.ru/3.0/library/email.parser.html#parser-class-api)26  - [Дополнительные примечания](https://python-all.ru/3.0/library/email.parser.html#additional-notes)27- [`email`: Генерация MIME-документов](https://python-all.ru/3.0/library/email.generator.html)28- [`email`: Создание email- и MIME-объектов с нуля](https://python-all.ru/3.0/library/email.mime.html)29- [`email`: Интернационализированные заголовки](https://python-all.ru/3.0/library/email.header.html)30- [`email`: Представление кодировок](https://python-all.ru/3.0/library/email.charset.html)31- [`email`: Кодировщики](https://python-all.ru/3.0/library/email.encoders.html)32- [`email`: Классы исключений и дефектов](https://python-all.ru/3.0/library/email.errors.html)33- [`email`: Прочие утилиты](https://python-all.ru/3.0/library/email.util.html)34- [`email`: Итераторы](https://python-all.ru/3.0/library/email.iterators.html)35- [`email`: Примеры](https://python-all.ru/3.0/library/email-examples.html)3637> **См. также**38>39> **Модуль [`smtplib`](https://python-all.ru/3.0/library/smtplib.html#module-smtplib)**40>41> Клиент протокола SMTP42>43> **Модуль [`nntplib`](https://python-all.ru/3.0/library/nntplib.html#module-nntplib)**44>45> Клиент протокола NNTP4647## История пакета4849Эта таблица описывает историю выпусков пакета email, соответствующую версии Python, с которой был выпущен пакет. Для целей данного документа: когда вы видите примечание об изменении или добавлении версий, оно относится к версии Python, в которой было сделано изменение, *не* к версии пакета email. Эта таблица также описывает совместимость с Python каждой версии пакета.5051| Версия email | Распространяется с | Совместима с |52| --- | --- | --- |53| `1.x` | Python 2.2.0 – Python 2.2.1 | *больше не поддерживается* |54| `2.5` | Python 2.2.2+ и Python 2.3 | Python 2.1 – 2.5 |55| `3.0` | Python 2.4 | Python 2.3–2.5 |56| `4.0` | Python 2.5 | Python 2.3–2.5 |5758Вот основные различия между версией 4 и версией 3 `email`:5960- Все модули были переименованы в соответствии со стандартами [**PEP 8**](https://python-all.ru/3.0/library/email.html). Например, модуль версии 3 `email.Message` был переименован в [`email.message`](https://python-all.ru/3.0/library/email.message.html#module-email.message) в версии 4.61- Был добавлен новый подпакет [`email.mime`](https://python-all.ru/3.0/library/email.mime.html#module-email.mime), и все модули `email.MIME*` версии 3 были переименованы и перемещены в подпакет [`email.mime`](https://python-all.ru/3.0/library/email.mime.html#module-email.mime). Например, модуль версии 3 `email.MIMEText` был переименован в `email.mime.text`.6263  *Обратите внимание, что имена версии 3 будут продолжать работать до Python 2.6*.64- Был добавлен модуль `email.mime.application`, содержащий класс `MIMEApplication`.65- Методы, которые были помечены как устаревшие в версии 3, были удалены. К ним относятся `Generator.__call__()`, `Message.get_type()`, `Message.get_main_type()`, `Message.get_subtype()`.66- Были добавлены исправления для поддержки [**RFC 2231**](https://python-all.ru/3.0/library/email.html), которые могут изменить некоторые типы возвращаемых значений для `Message.get_param()` и подобных методов. При некоторых обстоятельствах значения, которые раньше возвращали кортеж из 3 элементов, теперь возвращают простые строки (в частности, если все расширенные сегменты параметров были незакодированы, не ожидается указание языка и кодировки, поэтому тип возвращаемого значения теперь – простая строка). Кроме того, %-декодирование раньше применялось как к закодированным, так и к незакодированным сегментам; теперь это декодирование выполняется только для закодированных сегментов.6768Вот основные различия между версией 3 и версией 2 `email`:6970- Был введен класс `FeedParser`, а класс `Parser` был реализован на основе `FeedParser`. Поэтому весь разбор теперь нестрогий, и при разборе будут приложены все усилия, чтобы никогда не вызывать исключение. Проблемы, найденные при разборе сообщений, сохраняются в атрибуте сообщения *defect*.71- Все аспекты API, которые вызывали [`DeprecationWarning`](https://python-all.ru/3.0/library/exceptions.html#exceptions.DeprecationWarning) в версии 2, были удалены. К ним относятся аргумент *\_encoder* конструктора `MIMEText`, метод `Message.add_payload()`, функция `Utils.dump_address_pair()`, а также функции `Utils.decode()` и `Utils.encode()`.72- Новые [`DeprecationWarning`](https://python-all.ru/3.0/library/exceptions.html#exceptions.DeprecationWarning) были добавлены для: `Generator.__call__()`, `Message.get_type()`, `Message.get_main_type()`, `Message.get_subtype()`, и аргумента *strict* класса `Parser`. Ожидается, что они будут удалены в будущих версиях.73- Удалена поддержка версий Python ниже 2.3.7475Вот различия между версией 2 и версией 1 `email`:7677- Были добавлены модули `email.Header` и `email.Charset`.78- Формат pickle для экземпляров `Message` изменился. Поскольку он никогда не был формально определён (и до сих пор не определён), это не считается нарушением обратной совместимости. Однако если ваше приложение сериализует и десериализует экземпляры `Message` с помощью pickle, имейте в виду, что в `email` версии 2 у экземпляров `Message` появились приватные переменные *\_charset* и *\_default\_type*.79- Несколько методов в классе `Message` устарели, или их сигнатуры изменились. Кроме того, добавлено много новых методов. Подробности см. в документации класса `Message`. Изменения должны быть полностью обратно совместимы.80- Структура объекта изменилась для типов содержимого *message/rfc822*. В `email` версии 1 такие типы представлялись скалярной полезной нагрузкой, то есть метод `is_multipart()` контейнерного сообщения возвращал false, `get_payload()` был не списком, а одиночным экземпляром `Message`.8182  Такая структура была несовместима с остальной частью пакета, поэтому объектное представление для типов содержимого *message/rfc822* было изменено. В `email` версии 2 контейнер *возвращает* `True` из `is_multipart()`, а `get_payload()` возвращает список, содержащий один элемент `Message`.8384  Обратите внимание, что это один из случаев, когда обратная совместимость не могла быть полностью сохранена. Однако, если вы уже проверяете тип возвращаемого значения `get_payload()`, у вас не должно возникнуть проблем. Просто убедитесь, что ваш код не вызывает `set_payload()` с экземпляром `Message` на контейнере с типом содержимого *message/rfc822*.85- У конструктора `Parser` был добавлен аргумент *strict*, а его методы `parse()` и `parsestr()` получили аргумент *headersonly*. Флаг *strict* также был добавлен к функциям [`email.message_from_file()`](https://python-all.ru/3.0/library/email.parser.html#email.message_from_file) и [`email.message_from_string()`](https://python-all.ru/3.0/library/email.parser.html#email.message_from_string).86- `Generator.__call__()` устарел; вместо него используйте `Generator.flatten()`. Класс `Generator` также получил метод `clone()`.87- Класс `DecodedGenerator` в модуле `email.Generator` был добавлен.88- Промежуточные базовые классы `MIMENonMultipart` и `MIMEMultipart` были добавлены и вставлены в иерархию классов для большинства других производных классов, связанных с MIME.89- Аргумент *\_encoder* конструктора `MIMEText` устарел. Кодирование теперь происходит неявно на основе аргумента *\_charset*.90- Следующие функции в модуле `email.Utils` объявлены устаревшими: `dump_address_pairs()`, `decode()` и `encode()`. В модуль добавлены следующие функции: `make_msgid()`, `decode_rfc2231()`, `encode_rfc2231()` и `decode_params()`.91- Была добавлена непубличная функция `email.Iterators._structure()`.9293## Отличия от `mimelib`9495Пакет `email` изначально был прототипом отдельной библиотеки [mimelib](https://python-all.ru/3.0/library/email.html). Были внесены изменения для большей согласованности имён методов, некоторые методы или модули были добавлены или удалены. Семантика некоторых методов также изменилась. По большей части любая функциональность, доступная в `mimelib`, всё ещё доступна в пакете `email`, хотя часто иначе. Обратная совместимость между пакетом `mimelib` и `email` не была приоритетом.9697Вот краткое описание различий между пакетами `mimelib` и `email`, а также советы по переносу приложений.9899Разумеется, самое заметное различие между двумя пакетами – это изменение имени пакета на `email`. Кроме того, у пакета верхнего уровня есть следующие отличия:100101- `messageFromString()` переименован в [`message_from_string()`](https://python-all.ru/3.0/library/email.parser.html#email.message_from_string).102- `messageFromFile()` переименован в [`message_from_file()`](https://python-all.ru/3.0/library/email.parser.html#email.message_from_file).103104Класс `Message` имеет следующие отличия:105106- Метод `asString()` был переименован в `as_string()`.107- Метод `ismultipart()` был переименован в `is_multipart()`.108- Метод `get_payload()` получил необязательный аргумент *decode*.109- Метод `getall()` был переименован в `get_all()`.110- Метод `addheader()` был переименован в `add_header()`.111- Метод `gettype()` был переименован в `get_type()`.112- Метод `getmaintype()` был переименован в `get_main_type()`.113- Метод `getsubtype()` был переименован в `get_subtype()`.114- Метод `getparams()` был переименован в `get_params()`. Кроме того, если `getparams()` возвращал список строк, то `get_params()` возвращает список кортежей из двух элементов – по сути пары ключ/значение параметров, разделённых знаком `'='`.115- Метод `getparam()` был переименован в `get_param()`.116- Метод `getcharsets()` был переименован в `get_charsets()`.117- Метод `getfilename()` был переименован в `get_filename()`.118- Метод `getboundary()` был переименован в `get_boundary()`.119- Метод `setboundary()` был переименован в `set_boundary()`.120- Метод `getdecodedpayload()` был удалён. Чтобы получить аналогичную функциональность, передайте значение 1 флагу *decode* метода get\_payload().121- Метод `getpayloadastext()` был удалён. Аналогичная функциональность поддерживается классом `DecodedGenerator` в модуле [`email.generator`](https://python-all.ru/3.0/library/email.generator.html#module-email.generator).122- Метод `getbodyastext()` был удалён. Аналогичную функциональность можно получить, создав итератор с помощью `typed_subpart_iterator()` в модуле [`email.iterators`](https://python-all.ru/3.0/library/email.iterators.html#module-email.iterators).123124Класс `Parser` не имеет отличий в своём публичном интерфейсе. Однако он обладает дополнительными интеллектуальными возможностями для распознавания сообщений типа *message/delivery-status*, которые представляются в виде экземпляра `Message`, содержащего отдельные подчасти `Message` для каждого блока заголовков в уведомлении о состоянии доставки [\[1\]](https://python-all.ru/3.0/library/email.html#id2).125126Класс `Generator` не имеет отличий в своём публичном интерфейсе. Однако в модуле [`email.generator`](https://python-all.ru/3.0/library/email.generator.html#module-email.generator) появился новый класс `DecodedGenerator`, который предоставляет большую часть функциональности, ранее доступной в методе `Message.getpayloadastext()`.127128Были изменены следующие модули и классы:129130- Аргументы конструктора класса `MIMEBase` – *\_major* и *\_minor* – были изменены на *\_maintype* и *\_subtype* соответственно.131- Класс/модуль `Image` был переименован в `MIMEImage`. Аргумент *\_minor* был переименован в *\_subtype*.132- Класс/модуль `Text` был переименован в `MIMEText`. Аргумент *\_minor* был переименован в *\_subtype*.133- Класс/модуль `MessageRFC822` был переименован в `MIMEMessage`. Обратите внимание, что более ранняя версия `mimelib` называла этот класс/модуль `RFC822`, но это вызывало конфликт с модулем стандартной библиотеки Python `rfc822` на некоторых файловых системах, нечувствительных к регистру.134135  Кроме того, класс `MIMEMessage` теперь представляет любой вид MIME-сообщения с основным типом *message*. Он принимает необязательный аргумент *\_subtype*, который используется для установки MIME-подтипа. По умолчанию *\_subtype* равен *rfc822*.136137`mimelib` предоставлял некоторые вспомогательные функции в своих модулях `address` и `date`. Все эти функции были перемещены в модуль [`email.utils`](https://python-all.ru/3.0/library/email.util.html#module-email.utils).138139The `MsgReader` class/module has been removed. Its functionality is most closely supported in the `body_line_iterator()` function in the [`email.iterators`](https://python-all.ru/3.0/library/email.iterators.html#module-email.iterators) module.140141Сноски142143| [\[1\]](https://python-all.ru/3.0/library/email.html#id1) | Уведомления о статусе доставки (DSN) определены в [**RFC 1894**](https://python-all.ru/3.0/library/email.html). |144| --- | --- |145