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

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

Пакет email — это библиотека для работы с электронными сообщениями. Она специально не предназначена для отправки электронных сообщений на серверы SMTP (RFC 2821), NNTP или другие серверы; такие функции предоставляют модули, например smtplib. Пакет email стремится максимально соответствовать RFC, поддерживая RFC 5322 и RFC 6532, а также такие RFC, относящиеся к MIME, как 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, описанных в предыдущих разделах.

Вышесказанное относится к современному (поддерживающему Unicode) API пакета email. В оставшихся разделах, начиная с класса 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: Инструменты для создания, чтения и управления коллекциями сообщений на диске с использованием различных стандартных форматов.