email — Пакет для обработки электронной почты и MIME

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

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

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

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

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

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

• 18.1.1. email.message: Представление сообщения электронной почты
• 18.1.2. email.parser: Парсинг сообщений электронной почты
  • 18.1.2.1. API FeedParser
  • 18.1.2.2. API класса Parser
  • 18.1.2.3. Дополнительные заметки
• 18.1.3. email.generator: Генерация MIME-документов
• 18.1.4. email.mime: Создание объектов электронной почты и MIME с нуля
• 18.1.5. email.header: Международные заголовки
• 18.1.6. email.charset: Представление кодировок символов
• 18.1.7. email.encoders: Кодировщики
• 18.1.8. email.errors: Классы исключений и дефектов
• 18.1.9. email.utils: Разные утилиты
• 18.1.10. email.iterators: Итераторы
• 18.1.11. email: Примеры

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

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

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

• Все модули были переименованы в соответствии со стандартами 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, которые вызывали DeprecationWarning в версии 2, были удалены. К ним относятся аргумент _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().

13. Отличия от 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() возвращает список пар 2-кортежей, фактически пар ключ/значение параметров, разделенных символом '='.
• Метод 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.

Примечания

1

Уведомления о состоянии доставки (DSN) определены в RFC 1894.