email — Пакет для обработки почтовых сообщений и MIME

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

Пакет email представляет собой библиотеку для управления почтовыми сообщениями. Он не предназначен для отправки почтовых сообщений по протоколам SMTP (RFC 2821), NNTP или другим серверам; эти функции реализованы в модулях, таких как smtplib и nntplib. Пакет email стремится к максимальной совместимости с RFC, поддерживая RFC 5322 и 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 и преобразует его обратно в сериализованный поток байтов. (Парсер и генератор также обрабатывают потоки символов текста, но этот способ использования не рекомендуется, так как очень легко получить сообщения, не соответствующие требованиям RFC.)

Компонент управления — модуль 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, описанных в предыдущих разделах.

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

Изменено в версии 3.6: Документация переорганизована и переписана для продвижения нового API EmailMessage/EmailPolicy.

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

API устаревшего формата:

См. также

Module smtplib: Клиент протокола SMTP (Simple Mail Transport Protocol)
Module poplib: Клиент протокола POP (Post Office Protocol)
Module imaplib: Клиент протокола IMAP (Internet Message Access Protocol)
Module nntplib: Клиент протокола NNTP (Net News Transport Protocol)
Module mailbox: Инструменты для создания, чтения и управления коллекциями сообщений на диске с использованием различных стандартных форматов.
Module smtpd: Фреймворк сервера SMTP (в основном полезен для тестирования)