19.1. email – Пакет для работы с электронной почтой и MIME¶email – An email and MIME handling package

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

Пакет email – это библиотека для управления сообщениями электронной почты. Он специально не предназначен для отправки сообщений на SMTP (RFC 2821), NNTP или другие серверы; это задачи таких модулей, как smtplib и nntplib. Пакет email стремится быть максимально совместимым с RFC, поддерживая RFC 5233 и RFC 6532, а также такие связанные с MIME RFC, как RFC 2045, RFC 2046, RFC 2047, RFC 2183, и RFC 2231.

Общую структуру пакета email можно разделить на три основных компонента и четвёртый компонент, управляющий поведением остальных.

Центральным компонентом пакета является «объектная модель», представляющая email-сообщения. Приложение взаимодействует с пакетом в основном через интерфейс объектной модели, определённый в подмодуле message. Приложение может использовать этот API для получения информации о существующем письме, создания нового письма, а также для добавления или удаления подкомпонентов письма, которые сами используют тот же интерфейс объектной модели. То есть, следуя природе email-сообщений и их MIME-подкомпонентов, объектная модель email представляет собой древовидную структуру объектов, каждый из которых предоставляет API EmailMessage.

Двумя другими основными компонентами пакета являются parser и generator. Парсер берёт сериализованную версию email-сообщения (поток байтов) и преобразует её в дерево объектов EmailMessage. Генератор, наоборот, берёт EmailMessage и превращает его обратно в сериализованный поток байтов. (Парсер и генератор также работают с потоками текстовых символов, но такой подход не рекомендуется, поскольку слишком легко получить сообщения, которые окажутся недействительными в том или ином отношении.)

Управляющий компонент – это модуль policy. Каждый EmailMessage, каждый generator и каждый parser имеет связанный с ним объект policy, который управляет его поведением. Обычно приложению нужно указать политику только при создании EmailMessage – либо напрямую создавая экземпляр EmailMessage для нового письма, либо разбирая входной поток с помощью parser. Однако политику можно изменить и при сериализации сообщения с помощью generator. Это позволяет, например, разобрать типовое email-сообщение с диска, но сериализовать его с использованием стандартных настроек SMTP при отправке на почтовый сервер.

Пакет email делает всё возможное, чтобы скрыть от приложения детали различных управляющих RFC. По идее приложение должно воспринимать email-сообщение как структурированное дерево текста Unicode и бинарных вложений, не беспокоясь о том, как они представляются при сериализации. Однако на практике часто необходимо знать хотя бы некоторые правила, регулирующие MIME-сообщения и их структуру, в частности названия и суть MIME-«типов содержимого» и то, как они идентифицируют многочастные документы. По большей части эти знания требуются только для более сложных приложений, и даже тогда речь идёт лишь о высокоуровневой структуре, а не о деталях представления. Поскольку MIME-типы содержимого широко используются в современном интернет-программном обеспечении (не только в email), для многих программистов это будет знакомое понятие.

В следующих разделах описывается функциональность пакета email. Мы начнём с объектной модели message, которая является основным интерфейсом для приложения, а затем рассмотрим компоненты parser и generator. После этого мы расскажем об управляющих элементах policy, что завершит рассмотрение основных компонентов библиотеки.

Следующие три раздела охватывают исключения, которые может вызывать пакет, и дефекты (несоответствие RFC), которые может обнаружить parser. Затем мы рассмотрим подкомпоненты headerregistry и contentmanager, которые предоставляют инструменты для более детальной работы с заголовками и полезной нагрузкой соответственно. Оба этих компонента содержат функции, важные для потребления и создания нетривиальных сообщений, а также описывают свои API расширяемости, которые будут интересны продвинутым приложениям.

После этого приводится набор примеров использования основных частей API, рассмотренных в предыдущих разделах.

Вышеописанное представляет современный (дружественный к Unicode) API пакета email. Оставшиеся разделы, начиная с класса Message, охватывают устаревший API compat32, который гораздо более напрямую работает с деталями представления email-сообщений. API compat32 не скрывает от приложения детали RFC, но для приложений, которым нужно работать на этом уровне, он может быть полезным инструментом. Эта документация также актуальна для приложений, всё ещё использующих API compat32 по причинам обратной совместимости.

Содержание документации пакета email:

Устаревший API: