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

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

Эта таблица описывает историю выпусков пакета email, соответствующую версии Python, с которой был выпущен пакет. Для целей данного документа: когда вы видите примечание об изменении или добавлении версий, оно относится к версии Python, в которой было сделано изменение, не к версии пакета email. Эта таблица также описывает совместимость с 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, означающее, что его можно использовать только для разбора 7-битных чистых сообщений электронной почты.

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

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

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

• The FeedParser class was introduced, and the Parser class was implemented in terms of the FeedParser. All parsing therefore is non-strict, and parsing will make a best effort never to raise an exception. Problems found while parsing messages are stored in the message’s defect attribute.
• Все аспекты 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.

• В конструктор 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().

19.1.15. Отличия от 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.

Сноски