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.

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

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