`email.md`

87 строк · 15.4 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.8/library/email.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`email`](https://python-all.ru/3.8/library/email.html#module-email) – пакет для обработки email и MIME89**Исходный код:** [Lib/email/\_\_init\_\_.py](https://python-all.ru/src/3.8/Lib/email/__init__.py)1011---1213Пакет [`email`](https://python-all.ru/3.8/library/email.html#module-email) представляет собой библиотеку для управления сообщениями электронной почты. Он специально *не* предназначен для отправки электронных писем на SMTP-серверы ([**RFC 2821**](https://python-all.ru/3.8/library/email.html)), NNTP или другие серверы; эти задачи выполняют такие модули, как [`smtplib`](https://python-all.ru/3.8/library/smtplib.html#module-smtplib) и [`nntplib`](https://python-all.ru/3.8/library/nntplib.html#module-nntplib). Пакет [`email`](https://python-all.ru/3.8/library/email.html#module-email) стремится быть максимально совместимым с RFC, поддерживая [**RFC 5322**](https://python-all.ru/3.8/library/email.html) и [**RFC 6532**](https://python-all.ru/3.8/library/email.html), а также такие связанные с MIME стандарты RFC, как [**RFC 2045**](https://python-all.ru/3.8/library/email.html), [**RFC 2046**](https://python-all.ru/3.8/library/email.html), [**RFC 2047**](https://python-all.ru/3.8/library/email.html), [**RFC 2183**](https://python-all.ru/3.8/library/email.html), и [**RFC 2231**](https://python-all.ru/3.8/library/email.html).1415Общую структуру пакета email можно разделить на три основных компонента и четвёртый компонент, управляющий поведением остальных.1617Центральным компонентом пакета является «объектная модель», представляющая email-сообщения. Приложение взаимодействует с пакетом в основном через интерфейс объектной модели, определённый в подмодуле [`message`](https://python-all.ru/3.8/library/email.message.html#module-email.message). Приложение может использовать этот API для получения информации о существующем письме, создания нового письма, а также для добавления или удаления подкомпонентов письма, которые сами используют тот же интерфейс объектной модели. То есть, следуя природе email-сообщений и их MIME-подкомпонентов, объектная модель email представляет собой древовидную структуру объектов, каждый из которых предоставляет API [`EmailMessage`](https://python-all.ru/3.8/library/email.message.html#email.message.EmailMessage).1819Двумя другими основными компонентами пакета являются [`parser`](https://python-all.ru/3.8/library/email.parser.html#module-email.parser) и [`generator`](https://python-all.ru/3.8/library/email.generator.html#module-email.generator). Парсер берёт сериализованную версию email-сообщения (поток байтов) и преобразует её в дерево объектов [`EmailMessage`](https://python-all.ru/3.8/library/email.message.html#email.message.EmailMessage). Генератор, наоборот, берёт [`EmailMessage`](https://python-all.ru/3.8/library/email.message.html#email.message.EmailMessage) и превращает его обратно в сериализованный поток байтов. (Парсер и генератор также работают с потоками текстовых символов, но такой подход не рекомендуется, поскольку слишком легко получить сообщения, которые окажутся недействительными в том или ином отношении.)2021Управляющий компонент – это модуль [`policy`](https://python-all.ru/3.8/library/email.policy.html#module-email.policy). Каждый [`EmailMessage`](https://python-all.ru/3.8/library/email.message.html#email.message.EmailMessage), каждый [`generator`](https://python-all.ru/3.8/library/email.generator.html#module-email.generator) и каждый [`parser`](https://python-all.ru/3.8/library/email.parser.html#module-email.parser) имеет связанный с ним объект [`policy`](https://python-all.ru/3.8/library/email.policy.html#module-email.policy), который управляет его поведением. Обычно приложению нужно указать политику только при создании [`EmailMessage`](https://python-all.ru/3.8/library/email.message.html#email.message.EmailMessage) – либо напрямую создавая экземпляр [`EmailMessage`](https://python-all.ru/3.8/library/email.message.html#email.message.EmailMessage) для нового письма, либо разбирая входной поток с помощью [`parser`](https://python-all.ru/3.8/library/email.parser.html#module-email.parser). Однако политику можно изменить и при сериализации сообщения с помощью [`generator`](https://python-all.ru/3.8/library/email.generator.html#module-email.generator). Это позволяет, например, разобрать типовое email-сообщение с диска, но сериализовать его с использованием стандартных настроек SMTP при отправке на почтовый сервер.2223Пакет email делает всё возможное, чтобы скрыть от приложения детали различных управляющих RFC. По идее приложение должно воспринимать email-сообщение как структурированное дерево текста Unicode и бинарных вложений, не беспокоясь о том, как они представляются при сериализации. Однако на практике часто необходимо знать хотя бы некоторые правила, регулирующие MIME-сообщения и их структуру, в частности названия и суть MIME-«типов содержимого» и то, как они идентифицируют многочастные документы. По большей части эти знания требуются только для более сложных приложений, и даже тогда речь идёт лишь о высокоуровневой структуре, а не о деталях представления. Поскольку MIME-типы содержимого широко используются в современном интернет-программном обеспечении (не только в email), для многих программистов это будет знакомое понятие.2425В следующих разделах описывается функциональность пакета [`email`](https://python-all.ru/3.8/library/email.html#module-email). Мы начнём с объектной модели [`message`](https://python-all.ru/3.8/library/email.message.html#module-email.message), которая является основным интерфейсом для приложения, а затем рассмотрим компоненты [`parser`](https://python-all.ru/3.8/library/email.parser.html#module-email.parser) и [`generator`](https://python-all.ru/3.8/library/email.generator.html#module-email.generator). После этого мы расскажем об управляющих элементах [`policy`](https://python-all.ru/3.8/library/email.policy.html#module-email.policy), что завершит рассмотрение основных компонентов библиотеки.2627Следующие три раздела охватывают исключения, которые может вызывать пакет, и дефекты (несоответствие RFC), которые может обнаружить [`parser`](https://python-all.ru/3.8/library/email.parser.html#module-email.parser). Затем мы рассмотрим подкомпоненты [`headerregistry`](https://python-all.ru/3.8/library/email.headerregistry.html#module-email.headerregistry) и [`contentmanager`](https://python-all.ru/3.8/library/email.contentmanager.html#module-email.contentmanager), которые предоставляют инструменты для более детальной работы с заголовками и полезной нагрузкой соответственно. Оба этих компонента содержат функции, важные для потребления и создания нетривиальных сообщений, а также описывают свои API расширяемости, которые будут интересны продвинутым приложениям.2829После этого приводится набор примеров использования основных частей API, рассмотренных в предыдущих разделах.3031Вышеописанное представляет современный (дружественный к Unicode) API пакета email. Оставшиеся разделы, начиная с класса [`Message`](https://python-all.ru/3.8/library/email.compat32-message.html#email.message.Message), охватывают устаревший API [`compat32`](https://python-all.ru/3.8/library/email.policy.html#email.policy.compat32), который гораздо более напрямую работает с деталями представления email-сообщений. API [`compat32`](https://python-all.ru/3.8/library/email.policy.html#email.policy.compat32) *не* скрывает от приложения детали RFC, но для приложений, которым нужно работать на этом уровне, он может быть полезным инструментом. Эта документация также актуальна для приложений, всё ещё использующих API [`compat32`](https://python-all.ru/3.8/library/email.policy.html#email.policy.compat32) по причинам обратной совместимости.3233Изменено в версии 3.6: Документация переработана и переписана для продвижения нового API [`EmailMessage`](https://python-all.ru/3.8/library/email.message.html#email.message.EmailMessage)/[`EmailPolicy`](https://python-all.ru/3.8/library/email.policy.html#email.policy.EmailPolicy).3435Содержание документации пакета [`email`](https://python-all.ru/3.8/library/email.html#module-email):3637- [`email.message`: Представление email-сообщения](https://python-all.ru/3.8/library/email.message.html)38- [`email.parser`: Разбор email-сообщений](https://python-all.ru/3.8/library/email.parser.html)3940  - [API FeedParser](https://python-all.ru/3.8/library/email.parser.html#feedparser-api)41  - [API Parser](https://python-all.ru/3.8/library/email.parser.html#parser-api)42  - [Дополнительные примечания](https://python-all.ru/3.8/library/email.parser.html#additional-notes)43- [`email.generator`: Генерация MIME-документов](https://python-all.ru/3.8/library/email.generator.html)44- [`email.policy`: Объекты политик](https://python-all.ru/3.8/library/email.policy.html)45- [`email.errors`: Классы исключений и дефектов](https://python-all.ru/3.8/library/email.errors.html)46- [`email.headerregistry`: Пользовательские объекты заголовков](https://python-all.ru/3.8/library/email.headerregistry.html)47- [`email.contentmanager`: Управление MIME-содержимым](https://python-all.ru/3.8/library/email.contentmanager.html)4849  - [Экземпляры Content Manager](https://python-all.ru/3.8/library/email.contentmanager.html#content-manager-instances)50- [`email`: Примеры](https://python-all.ru/3.8/library/email.examples.html)5152Устаревший API:5354- [`email.message.Message`: Представление email-сообщения с использованием API `compat32`](https://python-all.ru/3.8/library/email.compat32-message.html)55- [`email.mime`: Создание email- и MIME-объектов с нуля](https://python-all.ru/3.8/library/email.mime.html)56- [`email.header`: Интернационализированные заголовки](https://python-all.ru/3.8/library/email.header.html)57- [`email.charset`: Представление наборов символов](https://python-all.ru/3.8/library/email.charset.html)58- [`email.encoders`: Кодировщики](https://python-all.ru/3.8/library/email.encoders.html)59- [`email.utils`: Разные утилиты](https://python-all.ru/3.8/library/email.utils.html)60- [`email.iterators`: Итераторы](https://python-all.ru/3.8/library/email.iterators.html)6162> **См. также**63>64> **Модуль [`smtplib`](https://python-all.ru/3.8/library/smtplib.html#module-smtplib)**65>66> Клиент SMTP (простой протокол передачи почты)67>68> **Модуль [`poplib`](https://python-all.ru/3.8/library/poplib.html#module-poplib)**69>70> Клиент POP (протокол почтового отделения)71>72> **Модуль [`imaplib`](https://python-all.ru/3.8/library/imaplib.html#module-imaplib)**73>74> Клиент IMAP (протокол доступа к интернет-сообщениям)75>76> **Модуль [`nntplib`](https://python-all.ru/3.8/library/nntplib.html#module-nntplib)**77>78> Клиент NNTP (транспортный протокол сетевых новостей)79>80> **Модуль [`mailbox`](https://python-all.ru/3.8/library/mailbox.html#module-mailbox)**81>82> Инструменты для создания, чтения и управления наборами сообщений на диске с использованием различных стандартных форматов.83>84> **Модуль [`smtpd`](https://python-all.ru/3.8/library/smtpd.html#module-smtpd)**85>86> Каркас SMTP-сервера (в первую очередь полезен для тестирования)87