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

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

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

Вот основные различия между 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. В версии 1 email такой тип представлялся скалярной полезной нагрузкой, т.е. у сообщения-контейнера is_multipart() возвращало false, get_payload() был не списком, а единственным экземпляром Message.

  Эта структура была несовместима с остальной частью пакета, поэтому представление объекта для типов содержимого message/rfc822 было изменено. В версии 2 email контейнер возвращает 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().

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.

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

Сноски

1

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