Документация Python неофициальный перевод

email: создание MIME-документовemail: Generating MIME documents

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

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

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

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

Конструктор класса 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 пробелов), заголовок будет разбит в соответствии с классом email.header.Header. Установите значение 0, чтобы отключить перенос заголовков. По умолчанию используется 78, как рекомендовано (но не обязательно) в RFC 2822.

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

flatten(msg[, unixfrom])

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

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

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

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

Для удобства обратитесь к методам 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 – 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]