`email.md`

148 строк · 29.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/2.7/library/email.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 18.1. [`email`](https://python-all.ru/2.7/library/email.html#module-email) – Пакет для работы с электронной почтой и MIME89Новое в версии 2.2.1011Пакет [`email`](https://python-all.ru/2.7/library/email.html#module-email) – это библиотека для управления сообщениями электронной почты, включая MIME и другие документы сообщений на основе [**RFC 2822**](https://python-all.ru/2.7/library/email.html). Он включает большую часть функциональности нескольких более старых стандартных модулей, таких как [`rfc822`](https://python-all.ru/2.7/library/rfc822.html#module-rfc822), [`mimetools`](https://python-all.ru/2.7/library/mimetools.html#module-mimetools), [`multifile`](https://python-all.ru/2.7/library/multifile.html#module-multifile), и других нестандартных пакетов, например `mimecntl`. Он специально *не* предназначен для отправки сообщений электронной почты на SMTP ([**RFC 2821**](https://python-all.ru/2.7/library/email.html)), NNTP или другие серверы; это функции таких модулей, как [`smtplib`](https://python-all.ru/2.7/library/smtplib.html#module-smtplib) и [`nntplib`](https://python-all.ru/2.7/library/nntplib.html#module-nntplib). Пакет [`email`](https://python-all.ru/2.7/library/email.html#module-email) стремится быть максимально совместимым с RFC, поддерживая, помимо [**RFC 2822**](https://python-all.ru/2.7/library/email.html), такие связанные с MIME RFC, как [**RFC 2045**](https://python-all.ru/2.7/library/email.html), [**RFC 2046**](https://python-all.ru/2.7/library/email.html), [**RFC 2047**](https://python-all.ru/2.7/library/email.html), и [**RFC 2231**](https://python-all.ru/2.7/library/email.html).1213Основная отличительная особенность пакета [`email`](https://python-all.ru/2.7/library/email.html#module-email) заключается в том, что он разделяет анализ и создание сообщений электронной почты и внутреннее *объектной модели* представление электронной почты. Приложения, использующие пакет [`email`](https://python-all.ru/2.7/library/email.html#module-email), работают в основном с объектами; можно добавлять подобъекты в сообщения, удалять подобъекты из сообщений, полностью перестраивать содержимое и т.д. Существуют отдельные анализатор и генератор, которые выполняют преобразование из плоского текста в объектную модель, а затем обратно в плоский текст. Также есть удобные подклассы для некоторых распространенных типов MIME-объектов и несколько вспомогательных утилит, помогающих в таких типовых задачах, как извлечение и анализ значений полей сообщений, создание совместимых с RFC дат и т.д.1415В следующих разделах описывается функциональность пакета [`email`](https://python-all.ru/2.7/library/email.html#module-email). Порядок изложения соответствует типовой последовательности действий в приложениях: сообщение электронной почты читается как плоский текст из файла или другого источника, текст анализируется для создания объектной структуры сообщения, эта структура изменяется, и, наконец, дерево объектов преобразуется обратно в плоский текст.1617Вполне возможно создать объектную структуру с нуля – т.е. полностью с самого начала. После этого можно выполнить те же шаги, что описаны выше.1819Также включены подробные спецификации всех классов и модулей, предоставляемых пакетом [`email`](https://python-all.ru/2.7/library/email.html#module-email), классов исключений, которые могут встретиться при использовании пакета [`email`](https://python-all.ru/2.7/library/email.html#module-email), некоторые вспомогательные утилиты и несколько примеров. Для пользователей старого пакета `mimelib` или предыдущих версий пакета [`email`](https://python-all.ru/2.7/library/email.html#module-email) приведен раздел о различиях и переносе.2021Содержание документации пакета [`email`](https://python-all.ru/2.7/library/email.html#module-email):2223- [18.1.1. `email.message`: Представление сообщения электронной почты](https://python-all.ru/2.7/library/email.message.html)24- [18.1.2. `email.parser`: Разбор сообщений электронной почты](https://python-all.ru/2.7/library/email.parser.html)2526  - [18.1.2.1. API FeedParser](https://python-all.ru/2.7/library/email.parser.html#feedparser-api)27  - [18.1.2.2. API класса Parser](https://python-all.ru/2.7/library/email.parser.html#parser-class-api)28  - [18.1.2.3. Дополнительные замечания](https://python-all.ru/2.7/library/email.parser.html#additional-notes)29- [18.1.3. `email.generator`: Генерация MIME-документов](https://python-all.ru/2.7/library/email.generator.html)30- [18.1.4. `email.mime`: Создание объектов email и MIME с нуля](https://python-all.ru/2.7/library/email.mime.html)31- [18.1.5. `email.header`: Интернационализированные заголовки](https://python-all.ru/2.7/library/email.header.html)32- [18.1.6. `email.charset`: Представление наборов символов](https://python-all.ru/2.7/library/email.charset.html)33- [18.1.7. `email.encoders`: Кодировщики](https://python-all.ru/2.7/library/email.encoders.html)34- [18.1.8. `email.errors`: Классы исключений и дефектов](https://python-all.ru/2.7/library/email.errors.html)35- [18.1.9. `email.utils`: Прочие утилиты](https://python-all.ru/2.7/library/email.utils.html)36- [18.1.10. `email.iterators`: Итераторы](https://python-all.ru/2.7/library/email.iterators.html)37- [18.1.11. `email`: Примеры](https://python-all.ru/2.7/library/email-examples.html)3839> **См. также**40>41> **Модуль [`smtplib`](https://python-all.ru/2.7/library/smtplib.html#module-smtplib)**42>43> Клиент протокола SMTP44>45> **Модуль [`nntplib`](https://python-all.ru/2.7/library/nntplib.html#module-nntplib)**46>47> Клиент протокола NNTP4849## 18.1.12. История пакета5051Эта таблица описывает историю выпусков пакета email, соответствующую версии Python, с которой был выпущен пакет. Для целей данного документа: когда вы видите примечание об изменении или добавлении версий, оно относится к версии Python, в которой было сделано изменение, *не* к версии пакета email. Эта таблица также описывает совместимость с Python каждой версии пакета.5253| Версия email | Распространяется с | Совместима с |54| --- | --- | --- |55| `1.x` | Python 2.2.0 – Python 2.2.1 | *больше не поддерживается* |56| `2.5` | Python 2.2.2+ и Python 2.3 | Python 2.1 – 2.5 |57| `3.0` | Python 2.4 | Python 2.3–2.5 |58| `4.0` | Python 2.5 | Python 2.3–2.5 |5960Вот основные различия между [`email`](https://python-all.ru/2.7/library/email.html#module-email) версии 4 и версии 3:6162- Все модули переименованы в соответствии со стандартами [**PEP 8**](https://python-all.ru/2.7/library/email.html). Например, модуль версии 3 `email.Message` был переименован в [`email.message`](https://python-all.ru/2.7/library/email.message.html#module-email.message) в версии 4.63- Был добавлен новый подпакет [`email.mime`](https://python-all.ru/2.7/library/email.mime.html#module-email.mime), а все модули версии 3 `email.MIME*` были переименованы и размещены в подпакете [`email.mime`](https://python-all.ru/2.7/library/email.mime.html#module-email.mime). Например, модуль версии 3 `email.MIMEText` был переименован в `email.mime.text`.6465  *Обратите внимание, что имена версии 3 будут продолжать работать до Python 2.6*.66- Был добавлен модуль `email.mime.application`, который содержит класс [`MIMEApplication`](https://python-all.ru/2.7/library/email.mime.html#email.mime.application.MIMEApplication).67- Методы, объявленные устаревшими в версии 3, были удалены. К ним относятся `Generator.__call__()`, `Message.get_type()`, `Message.get_main_type()`, `Message.get_subtype()`.68- Были добавлены исправления для поддержки [**RFC 2231**](https://python-all.ru/2.7/library/email.html), которые могут изменить типы возвращаемых значений для [`Message.get_param`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.get_param) и связанных функций. При некоторых обстоятельствах значения, которые раньше возвращали кортеж из 3 элементов, теперь возвращают простые строки (в частности, если все сегменты расширенных параметров не закодированы, не ожидается обозначения языка и кодировки, поэтому тип возвращаемого значения теперь – простая строка). Кроме того, %-декодирование раньше применялось как к закодированным, так и к незакодированным сегментам; теперь это декодирование выполняется только для закодированных сегментов.6970Вот основные различия между [`email`](https://python-all.ru/2.7/library/email.html#module-email) версии 3 и версии 2:7172- Был введён класс [`FeedParser`](https://python-all.ru/2.7/library/email.parser.html#email.parser.FeedParser), а класс [`Parser`](https://python-all.ru/2.7/library/email.parser.html#email.parser.Parser) был реализован на основе [`FeedParser`](https://python-all.ru/2.7/library/email.parser.html#email.parser.FeedParser). Поэтому весь разбор выполняется нестрого, и разборщик будет стараться никогда не вызывать исключение. Проблемы, обнаруженные при разборе сообщений, сохраняются в атрибуте *defect* сообщения.73- Все аспекты API, которые в версии 2 вызывали [`DeprecationWarning`](https://python-all.ru/2.7/library/exceptions.html#exceptions.DeprecationWarning), были удалены. К ним относятся аргумент *\_encoder* конструктора [`MIMEText`](https://python-all.ru/2.7/library/email.mime.html#email.mime.text.MIMEText), метод `Message.add_payload()`, функция `Utils.dump_address_pair()`, а также функции `Utils.decode()` и `Utils.encode()`.74- Новые [`DeprecationWarning`](https://python-all.ru/2.7/library/exceptions.html#exceptions.DeprecationWarning) были добавлены в: `Generator.__call__()`, `Message.get_type()`, `Message.get_main_type()`, `Message.get_subtype()`, и аргумент *strict* класса [`Parser`](https://python-all.ru/2.7/library/email.parser.html#email.parser.Parser). Ожидается, что они будут удалены в будущих версиях.75- Удалена поддержка версий Python ниже 2.3.7677Вот различия между [`email`](https://python-all.ru/2.7/library/email.html#module-email) версии 2 и версии 1:7879- Были добавлены модули `email.Header` и `email.Charset`.80- Формат pickle для экземпляров [`Message`](https://python-all.ru/2.7/library/email.message.html#email.message.Message) изменился. Поскольку он никогда не был (и до сих пор не является) формально определён, это не считается нарушением обратной совместимости. Однако если ваше приложение сериализует и десериализует экземпляры [`Message`](https://python-all.ru/2.7/library/email.message.html#email.message.Message), учтите, что в [`email`](https://python-all.ru/2.7/library/email.html#module-email) версии 2 экземпляры [`Message`](https://python-all.ru/2.7/library/email.message.html#email.message.Message) теперь имеют частные переменные *\_charset* и *\_default\_type*.81- Несколько методов класса [`Message`](https://python-all.ru/2.7/library/email.message.html#email.message.Message) были объявлены устаревшими или их сигнатуры изменились. Также было добавлено много новых методов. Подробнее см. документацию класса [`Message`](https://python-all.ru/2.7/library/email.message.html#email.message.Message). Изменения должны быть полностью обратно совместимы.82- Структура объекта изменилась в случае типов содержимого *message/rfc822*. В версии 1 [`email`](https://python-all.ru/2.7/library/email.html#module-email) такой тип представлялся скалярной полезной нагрузкой, т.е. у сообщения-контейнера [`is_multipart()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.is_multipart) возвращало false, [`get_payload()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.get_payload) был не списком, а единственным экземпляром [`Message`](https://python-all.ru/2.7/library/email.message.html#email.message.Message).8384  Эта структура была несовместима с остальной частью пакета, поэтому представление объекта для типов содержимого *message/rfc822* было изменено. В версии 2 [`email`](https://python-all.ru/2.7/library/email.html#module-email) контейнер *возвращает* `True` из [`is_multipart()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.is_multipart), и [`get_payload()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.get_payload) возвращает список, содержащий один элемент [`Message`](https://python-all.ru/2.7/library/email.message.html#email.message.Message).8586  Обратите внимание, что здесь обратная совместимость не могла быть полностью сохранена. Однако, если вы уже тестируете возвращаемый тип [`get_payload()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.get_payload), всё должно быть в порядке. Просто нужно убедиться, что ваш код не вызывает [`set_payload()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.set_payload) с экземпляром [`Message`](https://python-all.ru/2.7/library/email.message.html#email.message.Message) для контейнера с типом содержимого *message/rfc822*.87- Был добавлен аргумент *strict* конструктора [`Parser`](https://python-all.ru/2.7/library/email.parser.html#email.parser.Parser), а его методы [`parse()`](https://python-all.ru/2.7/library/email.parser.html#email.parser.Parser.parse) и [`parsestr()`](https://python-all.ru/2.7/library/email.parser.html#email.parser.Parser.parsestr) получили аргумент *headersonly*. Флаг *strict* также был добавлен к функциям [`email.message_from_file()`](https://python-all.ru/2.7/library/email.parser.html#email.message_from_file) и [`email.message_from_string()`](https://python-all.ru/2.7/library/email.parser.html#email.message_from_string).88- `Generator.__call__()` устарел; используйте [`Generator.flatten`](https://python-all.ru/2.7/library/email.generator.html#email.generator.Generator.flatten) вместо него. Класс [`Generator`](https://python-all.ru/2.7/library/email.generator.html#email.generator.Generator) также получил метод [`clone()`](https://python-all.ru/2.7/library/email.generator.html#email.generator.Generator.clone).89- Был добавлен класс [`DecodedGenerator`](https://python-all.ru/2.7/library/email.generator.html#email.generator.DecodedGenerator) в модуле [`email.generator`](https://python-all.ru/2.7/library/email.generator.html#module-email.generator).90- Были добавлены промежуточные базовые классы [`MIMENonMultipart`](https://python-all.ru/2.7/library/email.mime.html#email.mime.nonmultipart.MIMENonMultipart) и [`MIMEMultipart`](https://python-all.ru/2.7/library/email.mime.html#email.mime.multipart.MIMEMultipart), и они вставлены в иерархию классов для большинства других производных MIME-классов.91- Аргумент *\_encoder* конструктора [`MIMEText`](https://python-all.ru/2.7/library/email.mime.html#email.mime.text.MIMEText) объявлен устаревшим. Кодирование теперь происходит неявно на основе аргумента *\_charset*.92- Следующие функции в модуле `email.Utils` объявлены устаревшими: `dump_address_pairs()`, `decode()` и `encode()`. В модуль были добавлены следующие функции: `make_msgid()`, `decode_rfc2231()`, `encode_rfc2231()` и `decode_params()`.93- Была добавлена непубличная функция `email.Iterators._structure()`.9495## 18.1.13. Отличия от `mimelib`9697Пакет [`email`](https://python-all.ru/2.7/library/email.html#module-email) изначально был прототипом отдельной библиотеки под названием [mimelib](https://python-all.ru/2.7/library/email.html). Были внесены изменения, чтобы имена методов стали более согласованными, а некоторые методы или модули были добавлены или удалены. Семантика некоторых методов также изменилась. По большей части любая функциональность, доступная в `mimelib`, по-прежнему доступна в пакете [`email`](https://python-all.ru/2.7/library/email.html#module-email), хотя часто по-другому. Обратная совместимость между пакетами `mimelib` и [`email`](https://python-all.ru/2.7/library/email.html#module-email) не была приоритетом.9899Ниже приводится краткое описание различий между пакетами `mimelib` и [`email`](https://python-all.ru/2.7/library/email.html#module-email), а также подсказки по переносу приложений.100101Разумеется, самое заметное различие между двумя пакетами заключается в том, что имя пакета было изменено на [`email`](https://python-all.ru/2.7/library/email.html#module-email). Кроме того, в пакете верхнего уровня имеются следующие различия:102103- `messageFromString()` переименован в [`message_from_string()`](https://python-all.ru/2.7/library/email.parser.html#email.message_from_string).104- `messageFromFile()` переименован в [`message_from_file()`](https://python-all.ru/2.7/library/email.parser.html#email.message_from_file).105106Класс [`Message`](https://python-all.ru/2.7/library/email.message.html#email.message.Message) имеет следующие отличия:107108- Метод `asString()` был переименован в [`as_string()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.as_string).109- Метод `ismultipart()` был переименован в [`is_multipart()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.is_multipart).110- Метод [`get_payload()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.get_payload) обзавёлся необязательным аргументом *decode*.111- Метод `getall()` был переименован в [`get_all()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.get_all).112- Метод `addheader()` был переименован в [`add_header()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.add_header).113- Метод `gettype()` был переименован в `get_type()`.114- Метод `getmaintype()` был переименован в `get_main_type()`.115- Метод `getsubtype()` был переименован в `get_subtype()`.116- Метод `getparams()` был переименован в [`get_params()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.get_params). Кроме того, тогда как `getparams()` возвращал список строк, [`get_params()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.get_params) возвращает список кортежей из двух элементов, представляющих собой пары ключ/значение параметров, разделённые по знаку `'='`.117- Метод `getparam()` был переименован в [`get_param()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.get_param).118- Метод `getcharsets()` был переименован в [`get_charsets()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.get_charsets).119- Метод `getfilename()` был переименован в [`get_filename()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.get_filename).120- Метод `getboundary()` был переименован в [`get_boundary()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.get_boundary).121- Метод `setboundary()` был переименован в [`set_boundary()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.set_boundary).122- Метод `getdecodedpayload()` был удалён. Чтобы получить аналогичную функциональность, передайте значение 1 флагу *decode* метода [`get_payload()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.get_payload).123- Метод `getpayloadastext()` был удалён. Аналогичная функциональность поддерживается классом [`DecodedGenerator`](https://python-all.ru/2.7/library/email.generator.html#email.generator.DecodedGenerator) в модуле [`email.generator`](https://python-all.ru/2.7/library/email.generator.html#module-email.generator).124- Метод `getbodyastext()` был удалён. Аналогичную функциональность можно получить, создав итератор с помощью [`typed_subpart_iterator()`](https://python-all.ru/2.7/library/email.iterators.html#email.iterators.typed_subpart_iterator) в модуле [`email.iterators`](https://python-all.ru/2.7/library/email.iterators.html#module-email.iterators).125126Класс [`Parser`](https://python-all.ru/2.7/library/email.parser.html#email.parser.Parser) не имеет отличий в своём публичном интерфейсе. Однако он обладает дополнительной логикой для распознавания сообщений типа *message/delivery-status*, которые он представляет как экземпляр [`Message`](https://python-all.ru/2.7/library/email.message.html#email.message.Message), содержащий отдельные подчасти [`Message`](https://python-all.ru/2.7/library/email.message.html#email.message.Message) для каждого блока заголовков в уведомлении о статусе доставки [1](https://python-all.ru/2.7/library/email.html#id2).127128Класс [`Generator`](https://python-all.ru/2.7/library/email.generator.html#email.generator.Generator) не имеет отличий в своём публичном интерфейсе. Однако в модуле [`email.generator`](https://python-all.ru/2.7/library/email.generator.html#module-email.generator) появился новый класс [`DecodedGenerator`](https://python-all.ru/2.7/library/email.generator.html#email.generator.DecodedGenerator), который предоставляет большую часть функциональности, ранее доступной в методе `Message.getpayloadastext()`.129130Были изменены следующие модули и классы:131132- Аргументы конструктора класса [`MIMEBase`](https://python-all.ru/2.7/library/email.mime.html#email.mime.base.MIMEBase) *\_major* и *\_minor* были изменены на *\_maintype* и *\_subtype* соответственно.133- Класс/модуль `Image` был переименован в `MIMEImage`. Аргумент *\_minor* был переименован в *\_subtype*.134- Класс/модуль `Text` был переименован в `MIMEText`. Аргумент *\_minor* был переименован в *\_subtype*.135- Класс/модуль `MessageRFC822` был переименован в `MIMEMessage`. Обратите внимание, что в более ранней версии `mimelib` этот класс/модуль назывался `RFC822`, но это имя конфликтовало с модулем стандартной библиотеки Python [`rfc822`](https://python-all.ru/2.7/library/rfc822.html#module-rfc822) в некоторых файловых системах, не различающих регистр.136137  Кроме того, класс [`MIMEMessage`](https://python-all.ru/2.7/library/email.mime.html#email.mime.message.MIMEMessage) теперь представляет любой вид MIME-сообщения с основным типом *message*. Он принимает необязательный аргумент *\_subtype*, который используется для задания подтипа MIME. *\_subtype* по умолчанию равен *rfc822*.138139Пакет `mimelib` предоставлял некоторые вспомогательные функции в своих модулях `address` и `date`. Все эти функции были перемещены в модуль [`email.utils`](https://python-all.ru/2.7/library/email.utils.html#module-email.utils).140141Класс/модуль `MsgReader` был удалён. Его функциональность наиболее полно поддерживается функцией [`body_line_iterator()`](https://python-all.ru/2.7/library/email.iterators.html#email.iterators.body_line_iterator) в модуле [`email.iterators`](https://python-all.ru/2.7/library/email.iterators.html#module-email.iterators).142143Сноски144145**[1](https://python-all.ru/2.7/library/email.html#id1)**146147Уведомления о статусе доставки (DSN) определены в [**RFC 1894**](https://python-all.ru/2.7/library/email.html).148