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

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

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

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

class email.generator.Generator(outfp[, mangle_from_[, maxheaderlen]])

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

Необязательный параметр 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.

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

flatten(msg[, unixfrom])

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

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

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

Введено в версии 2.2.2.

clone(fp)

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

Введено в версии 2.2.2.

write(s)

Записывает строку s в подлежащий файловый объект, то есть outfp, переданный в конструктор Generator. Это предоставляет минимально необходимый файлоподобный API для использования экземпляров Generator в расширенных операторах печати.

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

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

class email.generator.DecodedGenerator(outfp[, mangle_from_[, maxheaderlen[, fmt]]])

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

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

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

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

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

Введено в версии 2.2.2.

Примечания

1

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