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.

Общую структуру пакета 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 (простой протокол передачи почты)
Module poplib: Клиент POP (протокол почтового отделения)
Module imaplib: Клиент IMAP (протокол доступа к интернет-сообщениям)
Module nntplib: Клиент NNTP (сетевой протокол передачи новостей)
Module mailbox: Инструменты для создания, чтения и управления коллекциями сообщений на диске с использованием различных стандартных форматов.