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

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

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

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

Центральным компонентом пакета является «объектная модель», представляющая сообщения электронной почты. Приложение взаимодействует с пакетом в основном через интерфейс объектной модели, определенный в подмодуле 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, который имеет дело с гораздо более непосредственными деталями представления почтовых сообщений. API compat32 не скрывает детали RFC от приложения, но для приложений, которым необходимо работать на этом уровне, они могут быть полезными инструментами. Эта документация также актуальна для приложений, которые все еще используют API compat32 по причинам обратной совместимости.

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

Наследие API: