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 по причинам обратной совместимости.

Изменено в версии 3.6: Документация переорганизована и переписана, чтобы продвигать новый API EmailMessage/EmailPolicy.

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

API устаревшего типа:

См. также

Module smtplib: SMTP (Простой протокол передачи почты) клиент
Module poplib: POP (Почтовый протокол) клиент
Module imaplib: IMAP (Протокол доступа к почтовым сообщениям Интернет) клиент
Module nntplib: NNTP (Протокол передачи новостей сети) клиент
Module mailbox: Инструменты для создания, чтения и управления коллекциями сообщений на диске, используя различные стандартные форматы.
Module smtpd: Фреймворк SMTP-сервера (в первую очередь полезен для тестирования)