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

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

Одна из наиболее распространённых задач — сгенерировать текстовое представление сообщения электронной почты, представленного в виде структуры объекта сообщения. Вам потребуется сделать это, если вы хотите отправить своё сообщение через модуль smtplib или модуль nntplib, или вывести сообщение в консоль. Преобразование структуры объекта сообщения в текстовый документ выполняет класс Generator.

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

Выходной результат в формате bytes можно получить, используя класс BytesGenerator. Если структура объекта сообщения содержит байты, не являющиеся ASCII, метод flatten() этого генератора выведет исходные байты. Парсинг двоичного сообщения и последующее его сглаживание с помощью BytesGenerator должно быть идемпотентным для сообщений, соответствующих стандартам.

Вот публичные методы класса Generator, импортированные из модуля email.generator:

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

Конструктор класса Generator принимает в качестве аргумента объект, подобный файлу, называемый outfp. outfp должен поддерживать метод write() и быть пригоден в качестве выходного файла для функции print().

Необязательный параметр mangle_from_ — это флаг, который, когда True, добавляет символ > перед любой строкой в теле, которая начинается точно как From, т.е. From за которым следует пробел в начале строки. Это единственный гарантированно переносимый способ избежать того, чтобы такие строки принимались за разделитель заголовка конверта формата почтового ящика Unix (подробнее см. WHY THE CONTENT-LENGTH FORMAT IS BAD). mangle_from_ по умолчанию равен True, но вы можете установить его в False, если не работаете с файлами формата почтового ящика Unix.

Необязательный параметр maxheaderlen определяет максимальную длину не-продолжаемого заголовка. Если длина строки заголовка превышает maxheaderlen (в символах, с расширением табуляции до 8 пробелов), заголовок будет разделен, как определено в классе Header. Установка значения 0 отключает обрезку заголовков. По умолчанию значение равно 78, как рекомендуется (но не обязательно) **RFC 2822**.

Параметр policy указывает объект policy, который управляет множеством аспектов работы генератора. Если параметр policy не указан, используется policy, прикреплённый к объекту сообщения, переданному в flatten.

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

Другие публичные методы Generator:

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

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

Необязательный параметр unixfrom — это флаг, который принудительно выводит разделитель заголовка конверта перед первым заголовком **RFC 2822** корневого объекта сообщения. Если у корневого объекта нет заголовка конверта, он создается стандартный. По умолчанию это False для предотвращения вывода разделителя конверта.

Обратите внимание, что для подчастей заголовок конверта никогда не выводится.

Необязательный параметр linesep задаёт разделитель строк, используемый для завершения строк в выводе. Если он указан, он переопределяет значение, заданное в msg или Generator's policy.

Поскольку строки не могут представлять байты, не являющиеся ASCII, если политика, применённая при выполнении flatten, имеет cte_type установленное в 8bit, Generator будет работать как если бы оно было установлено в 7bit. Это означает, что сообщения, проанализированные с помощью двоичного парсера, имеющие Content-Transfer-Encoding равный 8bit, будут преобразованы в использование кодировки 7bit Content-Transfer-Encoding. Байты, не являющиеся ASCII, в заголовках будут закодированы в соответствии с **RFC 2047** с кодировкой unknown-8bit.

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

clone(fp)

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

write(s)

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

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

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

Конструктор класса BytesGenerator принимает двоичный объект-подобный файлу, называемый outfp, в качестве аргумента. outfp должен поддерживать метод write(), который принимает двоичные данные.

Необязательный параметр mangle_from_, когда True, помещает символ > перед любой строкой в теле, которая начинается точно так же, как From, то есть From за которым следует пробел в начале строки. Это единственный гарантированно переносимый способ избежать того, чтобы такие строки ошибочно принимались за разделитель заголовков конверта формата почтового ящика Unix (см. ПОЧЕМУ НЕОБХОДИМО ИЗБЕГАТЬ ФОРМАТА CONTENT-LENGTH для получения подробной информации). Параметр mangle_from_ по умолчанию True, но вы можете установить его в False , если вы не работаете с файлами формата почтового ящика Unix.

Необязательный параметр maxheaderlen задаёт максимальную длину для заголовка без продолжения. Когда строка заголовка длиннее, чем maxheaderlen (в символах, с табуляциями, преобразованными в 8 пробелов), заголовок будет разделен так, как определено в классе Header. Установите значение в ноль, чтобы отключить обрезку заголовков. По умолчанию используется значение 78, как рекомендуется (но не обязательно) в RFC 2822.

Ключевое слово policy указывает объект policy, который управляет несколькими аспектами работы генератора. Если policy не указан, используется policy, прикреплённый к объекту сообщения, переданному методу flatten.

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

Другие публичные методы класса BytesGenerator:

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

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

Сообщения, обработанные с помощью парсера Bytes, имеющие Content-Transfer-Encoding 8bit, будут восстановлены как 8bit, если они не были изменены.

Необязательный параметр unixfrom — флаг, который принудительно выводит разделитель заголовков конверта перед первым заголовком RFC 2822 корневого объекта сообщения. Если корневой объект не имеет заголовков конверта, создаётся стандартный. По умолчанию он установлен в False для запрета вывода разделителя конверта.

Обратите внимание, что для подчастей заголовки конверта никогда не выводятся.

Необязательный параметр linesep задаёт разделитель строк, используемый для завершения строк в выводе. Если указан, он переопределяет значение, заданное в Generator или msg’s policy.

clone(fp)

Возвращает независимую копию экземпляра BytesGenerator с теми же опциями.

write(s)

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

Добавлен в версии 3.2.

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

class email.generator.DecodedGenerator(outfp, mangle_from_=True, maxheaderlen=78, fmt=None)

Этот класс, производный от Generator, проходит по всем подчастям сообщения. Если подчасть является части типа текст, то он выводит декодированную полезную нагрузку подчасти. Необязательные параметры _mangle_from_ и maxheaderlen такие же, как в базовом классе Generator.

Если подчасть не является части типа текст, необязательный параметр fmt — это строка формата, которая используется вместо полезной нагрузки сообщения. fmt расширяется с использованием следующих ключевых слов:

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

Значение по умолчанию для fmt — None, что означает

[Non-text (%(type)s) part of message omitted, filename %(filename)s]

Примечания