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

18.1.12. История пакета¶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() и подобных методов. При некоторых обстоятельствах значения, которые раньше возвращали кортеж из 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. Изменения должны быть полностью обратно совместимы.

• The object structure has changed in the face of message/rfc822 content types. In email version 1, such a type would be represented by a scalar payload, i.e. the container message’s is_multipart() returned false, get_payload() was not a list object, but a single Message instance.

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

Сноски