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.

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

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

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

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

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

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

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

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

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

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

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