email — Пакет обработки электронной почты и MIME

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

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

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

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

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

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

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

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

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

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

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

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

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

См.также

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