email — Пакет обработки электронных писем и MIME

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

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

Основной отличительной чертой пакета email является разделение парсинга и генерации электронных писем от внутреннего представления модели объектов электронного письма. Приложения, использующие пакет email, в основном работают с объектами; вы можете добавлять подобъекты к сообщениям, удалять подобъекты из сообщений, полностью перестраивать содержимое и т. д. Существует отдельный парсер и отдельный генератор, обрабатывающие преобразование из простого текста в модель объекта и обратно. Также доступны удобные подклассы для некоторых распространённых типов MIME-объектов и несколько вспомогательных утилит, которые помогают при выполнении таких задач, как извлечение и парсинг значений полей сообщений, создание RFC-совместимых дат и т. д.

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

Совершенно возможно создать структуру объекта с нуля — то есть полностью с нуля. Затем можно выполнить аналогичный порядок действий, как описано выше.

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

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

• 19.1.1. email.message: Представление электронного письма
• 19.1.2. email.parser: Парсинг электронных писем
  • 19.1.2.1. API FeedParser
  • 19.1.2.2. API класса Parser
  • 19.1.2.3. Дополнительные заметки
• 19.1.3. email.generator: Генерация MIME-документов
• 19.1.4. email.policy: Объекты политик
• 19.1.5. email.headerregistry: Пользовательские объекты заголовков
• 19.1.6. email.contentmanager: Управление содержимым MIME
  • 19.1.6.1. Экземпляры менеджеров содержимого
• 19.1.7. email.mime: Создание электронных писем и MIME-объектов с нуля
• 19.1.8. email.header: Локализованные заголовки
• 19.1.9. email.charset: Представление кодировок символов
• 19.1.10. email.encoders: Кодировщики
• 19.1.11. email.errors: Классы исключений и дефектов
• 19.1.12. email.utils: Разные вспомогательные утилиты
• 19.1.13. email.iterators: Итераторы
• 19.1.14. email: Примеры
  • 19.1.14.1. Примеры, использующие предварительный API

15. История пакета

В этой таблице представлена история выпусков пакета email, соответствующая версии Python, с которой он был выпущен. Для целей этого документа, при упоминании изменений или добавленных версий, речь идет о версии Python, а не версии пакета email. Эта таблица также описывает совместимость каждой версии пакета с Python.

После версии 5.1 (Python 3.2) пакет email больше не имеет версии, отдельной от версии Python. (Подробные сведения об изменениях см. в документах Что нового в Python для соответствующих версий Python.)

Вот основные различия между версией email 5.1 и 5.0:

• Теперь снова можно парсить сообщения, содержащие не-ASCII байты, и воспроизводить такие сообщения, если данные, содержащие не-ASCII байты, не были изменены.
• Новые функции message_from_bytes() и message_from_binary_file(), а также новые классы BytesFeedParser и BytesParser позволяют парсить данные двоичных сообщений в объекты модели.
• При вводе байтов в модель, get_payload() по умолчанию декодирует тело сообщения, у которого Content-Transfer-Encoding равен 8bit, используя кодировку символов, указанную в заголовках MIME, и возвращает полученную строку.
• При вводе байтов в модель, Generator будет преобразовывать тела сообщений, у которых Content-Transfer-Encoding равен 8bit, в 7bit Content-Transfer-Encoding.
• Новый класс BytesGenerator генерирует байты в качестве выходных данных, сохраняя любые неизменённые данные не-ASCII, которые присутствовали в входных данных, использованных для построения модели, включая тела сообщений с Content-Transfer-Encoding равным 8bit.

Ниже приведены основные отличия между email версией 5.0 и версией 4:

• Все операции выполняются со строками Unicode. Входные текстовые данные должны быть строками, текстовые выходные данные — строками. Выходные данные ограничены набором ASCII-символов и могут быть закодированы в ASCII для передачи. Входные данные также ограничены ASCII; это признанное ограничение email 5.0, что означает, что он может использоваться только для разбора электронных писем, которые являются 7bit-чистыми.

Ниже приведены основные отличия между email версией 4 и версией 3:

• Все модули были переименованы в соответствии со стандартами PEP 8. Например, модуль версии 3 email.Message был переименован в email.message в версии 4.

• Был добавлен новый подпакет email.mime, и все модули версии 3 email.MIME* были переименованы и размещены в подпакете email.mime. Например, модуль версии 3 email.MIMEText был переименован в email.mime.text.

  Обратите внимание, что имена версии 3 будут продолжать работать до Python 2.6.

• Был добавлен модуль email.mime.application, который содержит класс MIMEApplication.
• Методы, которые были устаревшими в версии 3, были удалены. К ним относятся Generator.__call__(), Message.get_type(), Message.get_main_type(), Message.get_subtype().
• Были добавлены исправления для поддержки RFC 2231, которые могут изменить некоторые типы возвращаемых значений для Message.get_param и аналогичных функций. В некоторых случаях значения, которые раньше возвращали кортеж из 3 элементов, теперь возвращают простые строки (конкретно, если все расширенные сегменты параметров были не закодированы, не ожидается обозначения языка и кодировки, поэтому тип возвращаемого значения теперь является простой строкой). Кроме того, декодирование с помощью %-символа раньше выполнялось как для закодированных, так и для незакодированных сегментов; теперь это декодирование выполняется только для закодированных сегментов.

Ниже приведены основные отличия между email версией 3 и версией 2:

• Был представлен класс FeedParser, и класс Parser был реализован на основе FeedParser. Таким образом, весь процесс парсинга является нестрогим, и парсер постарается никогда не генерировать исключение. Проблемы, обнаруженные во время парсинга сообщений, хранятся в атрибуте defect сообщения.
• Все аспекты API, которые в версии 2 вызывали DeprecationWarning, были удалены. К ним относятся аргумент _encoder конструктору MIMEText, метод Message.add_payload(), функция Utils.dump_address_pair(), и функции Utils.decode() и Utils.encode().
• Были добавлены новые DeprecationWarning для: Generator.__call__(), Message.get_type(), Message.get_main_type(), Message.get_subtype(), и аргумента strict класса Parser. Ожидается, что они будут удалены в будущих версиях.
• Поддержка версий Python, более ранних чем 2.3, была удалена.

Ниже приведены отличия между email версией 2 и версией 1:

• Были добавлены модули email.Header и email.Charset.
• Изменился формат сохранения в формате pickle для экземпляров Message. Поскольку он никогда (и по-прежнему не) был формально определён, это не считается нарушением обратной совместимости. Однако, если ваше приложение сохраняет и восстанавливает экземпляры Message, имейте в виду, что в версии email 2, экземпляры Message теперь имеют закрытые переменные _charset и _default_type.
• Некоторые методы в классе Message были устаревшими или изменены их сигнатуры. Кроме того, было добавлено много новых методов. Подробности см. в документации для класса Message. Изменения должны быть полностью обратной совместимы.

• Структура объекта изменилась в случае с типами контента message/rfc822. В версии email 1 такой тип представлялся скалярной полезной нагрузкой, т.е. сообщение-контейнер возвращал is_multipart() со значением false, get_payload() не был объектом списка, а единственным экземпляром Message.

  Эта структура не соответствовала остальной части пакета, поэтому представление объекта для типов контента message/rfc822 было изменено. В версии email 2 контейнер действительно возвращает True из is_multipart(), а get_payload() возвращает список, содержащий один элемент Message.

  Обратите внимание, что это один из случаев, когда полная обратная совместимость не была сохранена. Однако, если вы уже тестируете возвращаемый тип get_payload(), всё должно быть в порядке. Вам просто нужно убедиться, что ваш код не выполняет set_payload() с экземпляром Message для контейнера с типом контента message/rfc822.

• Аргумент strict конструктора Parser был добавлен, а методы parse() и parsestr() получили аргумент headersonly. Флаг strict также был добавлен к функциям email.message_from_file() и email.message_from_string().
• Generator.__call__() устарело; используйте Generator.flatten вместо этого. Класс Generator также получил метод clone().
• Класс DecodedGenerator был добавлен в модуль email.generator.
• Были добавлены промежуточные базовые классы MIMENonMultipart и MIMEMultipart, которые были включены в иерархию классов для большинства других производных классов, связанных с MIME.
• Аргумент _encoder конструктора MIMEText устарел. Кодирование теперь происходит неявно на основе аргумента _charset.
• Следующие функции в модуле email.Utils устарели: dump_address_pairs(), decode(), и encode(). Были добавлены следующие функции в модуль: make_msgid(), decode_rfc2231(), encode_rfc2231(), и decode_params().
• Была добавлена непубличная функция email.Iterators._structure().

16. Отличия от mimelib

Пакет email изначально был разработан как отдельная библиотека под названием mimelib. Были внесены изменения, чтобы имена методов были более согласованными, а некоторые методы или модули были добавлены или удалены. Семантика некоторых методов также изменилась. В основном, любая функциональность, доступная в mimelib, по-прежнему доступна в пакете email, хотя и зачастую другим способом. Обратная совместимость между пакетом mimelib и пакетом email не являлась приоритетом.

Ниже приводится краткое описание различий между пакетами mimelib и email, а также рекомендации по переносу ваших приложений.

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

• messageFromString() был переименован в message_from_string().
• messageFromFile() был переименован в message_from_file().

Класс Message имеет следующие различия:

• Метод asString() был переименован в as_string().
• Метод ismultipart() был переименован в is_multipart().
• Метод get_payload() получил необязательный аргумент decode.
• Метод getall() был переименован в get_all().
• Метод addheader() был переименован в add_header().
• Метод gettype() был переименован в get_type().
• Метод getmaintype() был переименован в get_main_type().
• Метод getsubtype() был переименован в get_subtype().
• Метод getparams() был переименован в get_params(). Также, в то время как getparams() возвращал список строк, get_params() возвращает список пар кортежей, эффективно представляя пары ключ/значение параметров, разделенные знаком '='.
• Метод getparam() был переименован в get_param().
• Метод getcharsets() был переименован в get_charsets().
• Метод getfilename() был переименован в get_filename().
• Метод getboundary() был переименован в get_boundary().
• Метод setboundary() был переименован в set_boundary().
• Метод getdecodedpayload() был удалён. Для получения аналогичной функциональности передайте значение 1 флагу decode метода get_payload().
• Метод getpayloadastext() был удалён. Аналогичная функциональность поддерживается классом DecodedGenerator в модуле email.generator.
• Метод getbodyastext() был удалён. Вы можете получить аналогичную функциональность, создав итератор с помощью typed_subpart_iterator() в модуле email.iterators.

Класс Parser не имеет различий в своём общедоступном интерфейсе. Он обладает дополнительными возможностями распознавания сообщений типа message/delivery-status, которые он представляет как экземпляр Message, содержащий отдельные Message подчасти для каждого блока заголовков в уведомлении о статусе доставки [1].

Класс Generator не имеет различий в своём общедоступном интерфейсе. В модуле email.generator есть новый класс, называемый DecodedGenerator, который предоставляет большую часть функциональности, ранее доступной в методе Message.getpayloadastext().

Следующие модули и классы были изменены:

• Аргументы конструктора класса MIMEBase _major и _minor были изменены на _maintype и _subtype соответственно.
• Класс/модуль Image был переименован в MIMEImage. Аргумент _minor был переименован в _subtype.
• Класс/модуль Text был переименован в MIMEText. Аргумент _minor был переименован в _subtype.

• Класс/модуль MessageRFC822 был переименован в MIMEMessage. Обратите внимание, что более ранняя версия mimelib называла этот класс/модуль RFC822, но это вызывало конфликт с модулем стандартной библиотеки Python rfc822 на некоторых файловых системах, не учитывающих регистр.

  Также, класс MIMEMessage теперь представляет любой тип MIME сообщения с основным типом message. Он принимает необязательный аргумент _subtype, который используется для задания MIME подтипа. _subtype по умолчанию равен rfc822.

Модуль mimelib предоставил некоторые утилитарные функции в своих модулях address и date. Все эти функции были перемещены в модуль email.utils.

Класс/модуль MsgReader был удалён. Его функциональность наиболее полно поддерживается функцией body_line_iterator() в модуле email.iterators.

Примечания