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

Источник: Lib/email/__init__.py

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

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

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

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

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

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

Унаследованный API:

См.также

Модуль smtplib

Клиент SMTP (простой почтовый транспортный протокол)

Модуль poplib

Клиент POP (Post Office Protocol)

Модуль imaplib

Клиент IMAP (Internet Message Access Protocol)

Модуль mailbox

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