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 и преобразует его обратно в сериализованный поток байтов. (Парсер и генератор также обрабатывают потоки символов текста, но это использование не рекомендуется, так как очень легко получить сообщения, которые недействительны по тем или иным причинам.)

Компонент управления — модуль 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-сервера (в основном полезен для тестирования)