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.

Общую структуру пакета 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, описанных в предыдущих разделах.

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

Изменено в версии 3.6: Документация реорганизована и переписана, чтобы привлечь внимание к новому API EmailMessage/EmailPolicy.

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

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

См. также

Module smtplib: Клиент SMTP (Simple Mail Transport Protocol)
Module poplib: Клиент POP (Post Office Protocol)
Module imaplib: Клиент IMAP (Internet Message Access Protocol)
Module mailbox: Инструменты для создания, чтения и управления коллекциями сообщений на диске с использованием различных стандартных форматов.