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-сервера (в основном полезен для тестирования)