19.1.3. `email.generator`: Generating MIME documents¶

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

Как и в случае с модулем email.parser, вы не ограничены функциональностью встроенного генератора; можно написать свой с нуля. Однако встроенный генератор умеет генерировать большинство email-сообщений в соответствии со стандартами, корректно обрабатывает MIME и не-MIME сообщения и спроектирован так, что преобразование из плоского текста в структуру сообщения через класс Parser и обратно в плоский текст идемпотентно (вход идентичен выходу) [1]. С другой стороны, использование Generator на 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 через policy.

Поскольку строки не могут представлять не-ASCII байты, если политика, действующая при вызове flatten, имеет cte_type, установленный в ⟦/8bit, то Generator будет работать так, как если бы он был установлен в 7bit. Это означает, что сообщения, разобранные с помощью Bytes parser и имеющие 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. Этого достаточно, чтобы экземпляры 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(), который принимает двоичные данные.

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

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

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

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

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

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

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

clone(fp)¶: Возвращает независимую копию этого экземпляра BytesGenerator с теми же самыми параметрами.

write(s)¶: Write the string s to the underlying file object. s is encoded using the ASCII codec and written to the write method of the outfp outfp passed to the BytesGenerator‘s constructor. This provides just enough file-like API for BytesGenerator instances to be used in the print() function.

Новое в версии 3.2.

The email.generator module also provides a derived class, called DecodedGenerator which is like the Generator base class, except that non-text parts are substituted with a format string representing the part.

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

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

Если подчасть не является основным типом text, необязательный параметр fmt – это форматная строка, используемая вместо содержимого сообщения. fmt разворачивается с использованием следующих ключевых слов в формате %(keyword)s:

type – Full MIME type of the non-text part
maintype – Main MIME type of the non-text part
subtype – Sub-MIME type of the non-text part
filename – Filename of the non-text part
description – Description associated with the non-text part
encoding – Content transfer encoding of the non-text part

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

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

Сноски

[1] Это утверждение предполагает, что используется подходящая настройка для аргумента unixfrom и что установлено maxheaderlen=0 (что сохранит исходные длины строк). Кроме того, это не совсем верно, поскольку во многих случаях последовательности пробелов в заголовках схлопываются в одиночные пробелы. Последнее является ошибкой, которая в конечном итоге будет исправлена.

19.1.3. email.generator: Generating MIME documents¶

19.1.3. `email.generator`: Generating MIME documents¶