email.generator: Генерация MIME-документов

Исходный код: Lib/email/generator.py

Одной из наиболее распространённых задач является генерация плоской (сериализованной) версии сообщения электронной почты, представленного структурой объекта сообщения. Вам потребуется это сделать, если вы хотите отправить своё сообщение через smtplib.SMTP.sendmail() или модуль nntplib, или распечатать сообщение в консоли. Преобразование объекта сообщения в сериализованное представление выполняют классы-генераторы.

Как и с модулем email.parser, вы не ограничены функциональностью встроенного генератора; вы можете написать свой собственный. Однако встроенный генератор умеет генерировать большинство сообщений электронной почты в соответствии со стандартами, обрабатывает сообщения MIME и не-MIME без проблем, и разработан таким образом, что операции побайтового парсинга и генерации являются обратными, при условии, что используется тот же не преобразующий policy для обоих. То есть, разбор сериализованного байтового потока с помощью класса BytesParser и последующее воссоздание сериализованного байтового потока с помощью BytesGenerator должно дать результат, идентичный входному 1. (С другой стороны, использование генератора с объектом EmailMessage, созданным программно, может привести к изменениям в объекте EmailMessage, поскольку по умолчанию будут заполнены значения.)

Класс Generator может использоваться для преобразования сообщения в текстовое (в отличие от бинарного) сериализованное представление, но поскольку Unicode не может напрямую представлять двоичные данные, сообщение по необходимости преобразуется в формат, содержащий только символы ASCII, используя стандартные методы кодирования содержания email RFC для кодирования сообщений электронной почты для передачи по каналам, которые не являются «8-битными».

Для обеспечения воспроизводимой обработки подписанных SMIME сообщений Generator отключает укладку заголовков для частей сообщения типа multipart/signed и всех подчастей.

class email.generator.BytesGenerator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Возвращает объект BytesGenerator, который будет записывать любое предоставленное сообщение в метод flatten(), или любой закодированный surrogateescape текст, предоставленный методу write(), в объект типа «подобный файлу» outfp. outfp должен поддерживать метод write, принимающий двоичные данные.

Если необязательный параметр mangle_from_ равен True, перед любой строкой в теле, начинающейся с точной строки "From ", будет вставлен символ >, то есть From за которым следует пробел в начале строки. Параметр mangle_from_ по умолчанию принимает значение настройки mangle_from_ политики policy (которое равно True для политики compat32 и False для всех остальных). Параметр mangle_from_ предназначен для использования, когда сообщения хранятся в формате Unix mbox (см. mailbox и ПОЧЕМУ ФОРМАТ CONTENT-LENGTH ПЛОХИЙ).

Если maxheaderlen не равно None, переупаковываются все строки заголовков, длина которых превышает maxheaderlen, или, если 0, переупаковка заголовков не выполняется. Если maxheaderlen равно None (значение по умолчанию), заголовки и другие строки сообщения форматируются в соответствии с настройками политики policy.

Если указана policy, используется эта политика для управления генерацией сообщения. Если policy равно None (значение по умолчанию), используется политика, связанная с объектом Message или EmailMessage, переданным методу flatten, для управления генерацией сообщения. Подробности о том, что контролирует policy, см. в email.policy.

New in version 3.2.

Changed in version 3.3: Добавлен ключевой параметр policy.

Changed in version 3.6: Поведение параметров mangle_from_ и maxheaderlen по умолчанию соответствует политике.

flatten(msg, unixfrom=False, linesep=None)

Распечатывает текстовое представление структуры объекта сообщения, укоренённого в msg, в выходной файл, указанный при создании экземпляра BytesGenerator.

Если опция policy cte_type равна 8bit (значение по умолчанию), копируются любые заголовки из исходного обработанного сообщения, которые не были изменены, в выходной поток с воспроизведением любых байтов с установленным старшим битом, как в оригинале, и сохраняется кодировка перевода содержимого не-ASCII Content-Transfer-Encoding любых частей тела, которые их содержат. Если cte_type равно 7bit, байты со старшим битом преобразуются в соответствии с потребностями, используя совместимую с ASCII кодировку Content-Transfer-Encoding. То есть, части с не-ASCII Content-Transfer-Encoding (Content-Transfer-Encoding: 8bit) преобразуются в совместимую с ASCII Content-Transfer-Encoding, а не-ASCII байты в заголовках, которые не соответствуют RFC, кодируются с помощью набора символов MIME unknown-8bit, делая их RFC-совместимыми.

Если unixfrom равно True, перед первой из строк заголовков RFC 5322 корневого объекта сообщения печатается разделитель заголовка конверта, используемый в формате Unix mailbox (см. mailbox). Если у корневого объекта нет заголовка конверта, создаётся стандартный. По умолчанию значение равно False. Обратите внимание, что для подчастей заголовок конверта никогда не печатается.

Если linesep не равно None, оно используется в качестве разделителя между всеми строками сглаженного сообщения. Если linesep равно None (значение по умолчанию), используется значение, заданное в policy.

clone(fp)

Возвращает независимую копию этого экземпляра BytesGenerator с теми же настройками параметров, с fp в качестве нового outfp.

write(s)

Кодирует s с помощью кодека ASCII и обработчика ошибок surrogateescape, и передает его методу write объекта outfp, переданного в конструктор BytesGenerator.

Для удобства, EmailMessage предоставляет методы as_bytes() и bytes(aMessage) (также известный как __bytes__()), которые упрощают генерацию сериализованного двоичного представления объекта сообщения. Более подробную информацию см. в email.message.

Поскольку строки не могут представлять двоичные данные, класс Generator должен преобразовывать любые двоичные данные в любом сообщении, которое он сжимает, в совместимый с ASCII формат, преобразуя их в совместимый с ASCII Content-Transfer_Encoding. Используя терминологию RFC электронных писем, можно представить себе, что Generator сериализуется в поток ввода-вывода, который не является «чистым 8-битным». Другими словами, большинство приложений будут использовать BytesGenerator, а не Generator.

class email.generator.Generator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Возвращает объект Generator, который будет записывать любое сообщение, предоставленное методу flatten(), или любой текст, предоставленный методу write(), в объект типа «подобный файлу» outfp. outfp должен поддерживать метод write, принимающий строковые данные.

Если необязательный параметр mangle_from_ True, поместите символ > перед любой строкой в теле, которая начинается с точной строки "From ", что соответствует From и пробелу в начале строки. По умолчанию mangle_from_ принимает значение параметра mangle_from_ политики policy (которое равно True для политики compat32 и False для всех остальных). mangle_from_ предназначен для использования, когда сообщения хранятся в формате Unix mbox (см. mailbox и WHY THE CONTENT-LENGTH FORMAT IS BAD).

Если maxheaderlen не None, переформатируйте любые строки заголовков, длина которых превышает maxheaderlen, или если 0, не переформатируйте никакие заголовки. Если manheaderlen равно None (по умолчанию), заголовки и другие строки сообщения будут переформатированы в соответствии с настройками политики policy.

Если указана политика policy, используйте эту политику для управления генерацией сообщений. Если policy равна None (по умолчанию), используйте политику, связанную с объектом Message или EmailMessage, переданным в flatten, для управления генерацией сообщений. Подробнее о настройках policy см. email.policy.

Изменено в версии 3.3: Добавлен ключевой параметр policy.

Изменено в версии 3.6: Поведение по умолчанию параметров mangle_from_ и maxheaderlen теперь соответствует настройкам политики.

flatten(msg, unixfrom=False, linesep=None)

Выводит текстовое представление структуры объекта сообщения, укорененного в msg, в файл вывода, указанный при создании экземпляра Generator.

Если значение опции policy cte_type равно 8bit, генерирует сообщение так, как если бы опция была установлена в 7bit. (Это необходимо, поскольку строки не могут представлять не-ASCII байты.) Преобразует любые байты с установленным старшим битом при необходимости с помощью совместимого с ASCII Content-Transfer-Encoding. То есть преобразует части с не-ASCII Content-Transfer-Encoding (Content-Transfer-Encoding: 8bit) в совместимый с ASCII Content-Transfer-Encoding и кодирует не-ASCII байты, не соответствующие RFC, в заголовках с помощью набора символов MIME unknown-8bit для соответствия RFC.

Если unixfrom равно True, выводит разделитель заголовка конверта, используемый в формате почтовых ящиков Unix (см. mailbox) перед первым из заголовков RFC 5322 корневого объекта сообщения. Если у корневого объекта нет заголовка конверта, создается стандартный. По умолчанию False. Обратите внимание, что для подчастей заголовок конверта никогда не выводится.

Если linesep не None, использует его в качестве разделителя между всеми строками сжатого сообщения. Если linesep равно None (по умолчанию), использует значение, указанное в policy.

Изменено в версии 3.2: Добавлена поддержка повторной кодировки 8bit тел сообщений и аргумент linesep.

clone(fp)

Возвращает независимую копию экземпляра Generator с теми же параметрами и fp в качестве нового outfp.

write(s)

Записывает s в метод write объекта outfp, переданного в конструктор Generator. Это предоставляет достаточно функционала типа «подобный файлу» для использования экземпляров Generator в функции print().

Для удобства, EmailMessage предоставляет методы as_string() и str(aMessage) (также известный как __str__()), которые упрощают генерацию форматированного строкового представления объекта сообщения. Подробнее см. email.message.

Модуль email.generator также предоставляет производный класс DecodedGenerator, который похож на базовый класс Generator, за исключением того, что части, не являющиеся текстом, не сериализуются, а вместо этого представляются в потоке вывода строкой, полученной из шаблона, заполненного информацией о части.

class email.generator.DecodedGenerator(outfp, mangle_from_=None, maxheaderlen=None, fmt=None, *, policy=None)

Ведет себя как Generator, за исключением того, что для любой части сообщения, переданной методу Generator.flatten(), если основным типом части является текст, выводится декодированная полезная нагрузка части, а если основным типом не является текст, вместо вывода части заполняется строка fmt с информацией о части и выводится полученная заполненная строка.

Для заполнения fmt выполняется fmt % part_info, где part_info — словарь, состоящий из следующих ключей и значений:

• type — Полный MIME-тип части, не являющейся текстом
• maintype — Основной MIME-тип части, не являющейся текстом
• subtype — Подтип MIME части, не являющейся текстом
• filename — Имя файла части, не являющейся текстом
• description — Описание, связанное с частью, не являющейся текстом
• encoding — Кодировка перевода содержимого части, не являющейся текстом

Если fmt равно None, используется следующий fmt по умолчанию:

“[Часть сообщения, не являющаяся текстом (%(type)s), опущена, имя файла %(filename)s]”

Необязательные параметры _mangle_from_ и maxheaderlen такие же, как и для базового класса Generator.

Примечания

1

Это утверждение предполагает, что вы используете соответствующее значение для unixfrom, и что нет email.policy настроек, требующих автоматической корректировки (например, refold_source должно быть none, что не является значением по умолчанию). Также это не на 100% верно, поскольку, если сообщение не соответствует стандартам RFC, иногда информация о точном исходном тексте теряется во время восстановления от ошибок разбора. Цель состоит в том, чтобы по возможности устранить эти крайние случаи.