email — Пакет для обработки электронных писем и MIME

Исходный код: Lib/email/__init__.py

Пакет email — это библиотека для управления сообщениями электронной почты. Он специально не предназначен для отправки электронных писем по протоколу SMTP (RFC 2821), NNTP или другим серверам; эти функции реализованы в модулях, таких как smtplib и nntplib. Пакет email старается быть максимально соответствующим RFC, поддерживая RFC 5233 и RFC 6532, а также такие RFC, относящиеся к MIME, как RFC 2045, RFC 2046, RFC 2047, RFC 2183 и RFC 2231.

Общая структура пакета email может быть разделена на три основных компонента, плюс четвёртый компонент, который контролирует поведение других компонентов.

Центральным компонентом пакета является «модель объектов», представляющая сообщения электронной почты. Приложение взаимодействует с пакетом в основном через интерфейс модели объекта, определённый в подмодуле message. Приложение может использовать этот API для получения информации об имеющемся письме, для создания нового письма или для добавления или удаления подкомпонентов письма, которые сами используют тот же интерфейс модели объекта. То есть, следуя природе сообщений электронной почты и их подкомпонентов MIME, модель объекта email представляет собой древовидную структуру объектов, все из которых предоставляют API EmailMessage.

Два других основных компонента пакета — parser и generator. Парсер принимает сериализованную версию сообщения электронной почты (поток байтов) и преобразует её в дерево объектов EmailMessage. Генератор принимает объект EmailMessage и преобразует его обратно в сериализованный поток байтов. (Парсер и генератор также обрабатывают потоки символов текста, но такое использование не рекомендуется, так как легко получить сообщения, которые недействительны по одному или нескольким причинам.)

Компонентом управления является модуль policy. Каждый объект EmailMessage, каждый generator и каждый parser имеет связанный объект policy, который управляет его поведением. Обычно приложению требуется указать политику только при создании объекта EmailMessage, либо путём прямого создания объекта EmailMessage для создания нового письма, либо путём парсинга входного потока с помощью parser. Но политику можно изменить при сериализации сообщения с помощью generator. Это позволяет, например, пропарсить общее сообщение электронной почты из файла, но сериализовать его с использованием стандартных настроек SMTP при отправке на почтовый сервер.

Пакет email делает всё возможное, чтобы скрыть детали различных правил RFC от приложения. По концепции приложение должно иметь возможность рассматривать сообщение электронной почты как структурированное дерево текстовых строк Unicode и бинарных вложений, не беспокоясь о том, как они представлены при сериализации. Однако на практике часто необходимо знать хотя бы некоторые правила, регулирующие сообщения MIME и их структуру, в частности, имена и характер MIME-«типов содержимого» и то, как они идентифицируют составные документы. В большинстве случаев эти знания потребуются только для более сложных приложений, и даже тогда – только об общей структуре, а не о деталях её представления. Поскольку MIME-типы содержимого широко используются в современном программном обеспечении интернета (а не только в электронной почте), это понятие будет знакомо многим программистам.

В следующих разделах описана функциональность пакета email. Мы начинаем с модели объектов message, которая является основным интерфейсом, используемым приложением, и переходим к компонентам parser и generator. Затем мы рассмотрим элементы управления policy, которые завершают рассмотрение основных компонентов библиотеки.

Следующие три раздела посвящены исключениям, которые может генерировать пакет, и дефектам (несоответствию RFC), которые может обнаружить parser. Затем мы рассмотрим подкомпоненты headerregistry и contentmanager, предоставляющие инструменты для более подробной обработки заголовков и полезных нагрузок соответственно. Оба компонента содержат функции, относящиеся к обработке нетривиальных сообщений, а также документируют их API расширяемости, что будет интересно для продвинутых приложений.

За ними следует набор примеров использования основных частей API, рассмотренных в предыдущих разделах.

Это представляет современный (совместимый с Unicode) API пакета email. Остальные разделы, начиная с класса Message, охватывают устаревший API compat32, который намного более тесно связан с деталями представления сообщений электронной почты. API compat32 не скрывает детали RFC от приложения, но для приложений, которые должны работать на этом уровне, они могут быть полезными инструментами. Данная документация также актуальна для приложений, которые по-прежнему используют API compat32 по соображениям обратной совместимости.

Содержание документации пакета email:

• 19.1.1. email.message: Представление электронного сообщения
• 19.1.2. email.parser: Парсинг электронных сообщений
  • 19.1.2.1. API FeedParser
  • 19.1.2.2. API Parser
  • 19.1.2.3. Дополнительные заметки
• 19.1.3. email.generator: Генерация документов MIME
• 19.1.4. email.policy: Объекты политики
• 19.1.5. email.errors: Классы исключений и дефектов
• 19.1.6. email.headerregistry: Пользовательские объекты заголовков
• 19.1.7. email.contentmanager: Управление содержимым MIME
  • 19.1.7.1. Экземпляры менеджера содержимого
• 19.1.8. email: Примеры

Устаревший API:

• 19.1.9. email.message.Message: Представление электронного сообщения с использованием API compat32
• 19.1.10. email.mime: Создание электронных писем и объектов MIME с нуля
• 19.1.11. email.header: Локализованные заголовки
• 19.1.12. email.charset: Представление наборов символов
• 19.1.13. email.encoders: Кодировщики
• 19.1.14. email.utils: Различные утилиты
• 19.1.15. email.iterators: Итераторы