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 расширения, что будет интересно для продвинутых приложений.

За ними следуют примеры использования основных частей 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: Инструменты для создания, чтения и управления коллекциями сообщений на диске с использованием различных стандартных форматов.
Module smtpd: Фреймворк SMTP-сервера (в основном полезен для тестирования)