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

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

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

Again, as with the email.parser module, you aren’t limited to the functionality of the bundled generator; you could write one from scratch yourself. However the bundled generator knows how to generate most email in a standards-compliant way, should handle MIME and non-MIME email messages just fine, and is designed so that the transformation from flat text, to a message structure via the Parser class, and back to flat text, is idempotent (the input is identical to the output). On the other hand, using the Generator on a Message constructed by program may result in changes to the Message object as defaults are filled in.

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

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

Конструктор класса 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.

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

flatten(msg, unixfrom=False)

Выводит текстовое представление структуры объекта сообщения, начиная с 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.

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.

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]