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

18.1.12. История пакета¶Package History

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

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

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

• Был добавлен новый подпакет email.mime, и все модули email.MIME* версии 3 были переименованы и перемещены в подпакет 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 элементов, теперь возвращают простые строки (в частности, если все расширенные сегменты параметров были незакодированы, не ожидается указание языка и кодировки, поэтому тип возвращаемого значения теперь – простая строка). Кроме того, %-декодирование раньше применялось как к закодированным, так и к незакодированным сегментам; теперь это декодирование выполняется только для закодированных сегментов.

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

• Был введен класс 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.

Вот различия между версией 2 и версией 1 email:

• Были добавлены модули email.Header и email.Charset.

• Формат pickle для экземпляров Message изменился. Поскольку он никогда не был формально определён (и до сих пор не определён), это не считается нарушением обратной совместимости. Однако если ваше приложение сериализует и десериализует экземпляры Message с помощью pickle, имейте в виду, что в 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.

• У конструктора Parser был добавлен аргумент strict, а его методы 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().

18.1.13. Отличия от mimelib¶Differences from 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.

The MsgReader class/module has been removed. Its functionality is most closely supported in the body_line_iterator() function in the email.iterators module.

Сноски