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

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

Одной из наиболее распространенных задач является создание плоской (сериализованной) версии сообщения электронной почты, представленной структурой объекта сообщения. Это необходимо для отправки сообщения через модуль smtplib.SMTP.sendmail() или модуль nntplib или печати сообщения на консоли. Взятие структуры объекта сообщения и создание сериализованного представления является заданием классов генератор.

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

Класс Generator может быть используемый, чтобы сгладить сообщение в текст (в отличие от двоичного) сериализованного представления, но поскольку юникод не может представлять двоичные данные напрямую, сообщение по необходимости преобразуется в нечто, что содержит только символы ASCII, используя стандартные методы кодирования передачи содержимого электронной почты RFC для кодировка сообщений электронной почты для транспорта по каналам, которые не являются «8-битными чистыми».

Чтобы приспособить восстанавливаемую обработку SMIME-подписанных сообщений, Generator отключает заголовок, сворачивающийся для частей сообщения типа multipart/signed и всех подразделений.

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

Объект возвращает a BytesGenerator, который напишет любое сообщение, предоставленное методу flatten() или любой текст surrogateescape кодированный, предоставленный методу write(), файлоподобный объект outfp. outfp должен поддерживать метод write, который принимает двоичные данные.

Если дополнительный mangle_from_ - True, поместите > символ перед любой линией в теле, которое начинается с точного строка "From ", который является From, сопровождаемым космосом в начале линии. Дефолты mangle_from_ к значение настройки mangle_from_ policy (который является True для политики compat32 и False для всех других). mangle_from_ предназначен для использования при хранении сообщений в формате unix mbox (см. mailbox и ПОЧЕМУ ПЛОХ ФОРМАТ ДЛИНЫ КОНТЕНТА).

Если maxheaderlen не является None, повторно заполните все строки заголовка, длина которых превышает maxheaderlen, или если 0, не перерисовывайте заголовки. Если manheaderlen - None (дефолт), заголовки обертки и другие линии сообщения согласно параметрам настройки policy.

Если policy определен, используйте ту политику управлять поколением сообщения. Если policy имеет значение None (по умолчанию), используйте политику, связанную с объектом Message или EmailMessage, переданным flatten, чтобы управлять формированием сообщений. Подробные сведения о том, какие элементы управления email.policy, см. в разделе policy.

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

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

Изменено в версии 3.6: Поведение по умолчанию mangle_from_ и maxheaderlen параметры должны следовать политике.

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

Напечатайте текстовое представление структуры объекта сообщения с корнем msg в выходной файл, указанный при создании BytesGenerator сущность.

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

Если unixfrom является True, перед первым из заголовков используемый объекта корневого сообщения напечатайте разделитель заголовка конверта mailbox по формату почтового ящика Unix (см. раздел RFC 5322). Если корневой объект не имеет заголовка оболочки, создайте стандартный объект. Значение по умолчанию - False. Обратите внимание, что для подразделов заголовок конверта никогда не печатается.

Если linesep не является None, используйте его в качестве разделителя символ между всеми строками распрямленного сообщения. Если linesep - None (дефолт), используйте значение, определенный в policy.

clone(fp)

Возвращает an независимый клон этого BytesGenerator сущность с точно такими же параметрами и fp как и новый outfp.

write(s)

Закодируйте s с помощью ASCII кодировка и обработчика ошибок surrogateescape и передайте его методу write outfp, переданному конструктору BytesGenerator.

В качестве удобства EmailMessage предоставляет методы as_bytes() и bytes(aMessage) (a.k.a. __bytes__()), которые упрощают генерацию сериализованного двоичного представления объекта сообщения. Дополнительные сведения см. в разделе email.message.

Поскольку строки не может представлять двоичные данные, класс Generator должен преобразовать любые двоичные данные в любом сообщении, это сглаживает к ASCII совместимый формат, преобразовывая их в ASCII совместимый Content-Transfer_Encoding. Используя терминологию электронной почты RFCs, вы можете думать об этом как о преобразовании в последовательную форму Generator к потоку I/O, который не является «чистыми 8 битами». Другими словами, большинство приложений хотят использовать BytesGenerator, а не Generator.

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

Объект возвращает a Generator, который напишет любое сообщение, предоставленное методу flatten() или любой текст, предоставленный методу write(), файлоподобный объект outfp. outfp должен поддерживать метод write, который принимает строка данные.

Если дополнительный mangle_from_ - True, поместите > символ перед любой линией в теле, которое начинается с точного строка "From ", который является From, сопровождаемым космосом в начале линии. Дефолты mangle_from_ к значение настройки mangle_from_ policy (который является True для политики compat32 и False для всех других). mangle_from_ предназначен для использования при хранении сообщений в формате unix mbox (см. mailbox и WHY THE CONTENT-LENGTH FORMAT IS BAD).

Если maxheaderlen не является None, повторно заполните все строки заголовка, длина которых превышает maxheaderlen, или если 0, не перерисовывайте заголовки. Если manheaderlen - None (дефолт), заголовки обертки и другие линии сообщения согласно параметрам настройки policy.

Если policy определен, используйте ту политику управлять поколением сообщения. Если policy имеет значение None (по умолчанию), используйте политику, связанную с объектом Message или EmailMessage, переданным flatten, чтобы управлять формированием сообщений. Подробные сведения о том, какие элементы управления email.policy, см. в разделе policy.

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

Изменено в версии 3.6: Поведение по умолчанию mangle_from_ и maxheaderlen параметры должны следовать политике.

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

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

Если выбор policy, cte_type - 8bit, генерируют сообщение, как будто выбор был установлен в 7bit. (Это необходимо, поскольку строки не может представлять байты, не являющиеся байтами ASCII.) преобразуйте любые байты с высоким набором сверл, по мере необходимости используя совместимый с ASCII Content-Transfer-Encoding. Таким образом, преобразуйте, расстается с неASCII Content-Transfer-Encoding (Content-Transfer-Encoding: 8bit) к ASCII совместимый Content-Transfer-Encoding, и закодируйте RFC- недействительные байты неASCII в заголовках, используя набор unknown-8bit символ MIME, таким образом отдав им RFC-соответствующий.

Если unixfrom является True, перед первым из заголовков используемый объекта корневого сообщения напечатайте разделитель заголовка конверта mailbox по формату почтового ящика Unix (см. раздел RFC 5322). Если корневой объект не имеет заголовка оболочки, создайте стандартный объект. Значение по умолчанию - False. Обратите внимание, что для подразделов заголовок конверта никогда не печатается.

Если linesep не является None, используйте его в качестве разделителя символ между всеми строками распрямленного сообщения. Если linesep - None (дефолт), используйте значение, определенный в policy.

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

clone(fp)

Возвращает an независимый клон этого Generator сущность с точно такими же опциями, и fp как и новый outfp.

write(s)

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

В качестве удобства EmailMessage предоставляет методы as_string() и str(aMessage) (a.k.a. __str__()), которые упрощают поколение отформатированного представления строка объекта сообщения. Дополнительные сведения см. в разделе email.message.

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

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

Закон как Generator, за исключением того, что для любого подразделения сообщения прошел к Generator.flatten(), если подразделение имеет главный тип text, печатает расшифрованный полезный груз подразделения, и если главный тип не text, вместо того, чтобы печатать его заполняют строка fmt, используя информацию от части и печатают заполненное получающееся - в строка.

Для заполнения fmt выполните fmt % part_info, где part_info - словарь, состоящий из следующих ключей и значения:

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

Если fmt имеет значение None, используйте следующую fmt: по умолчанию

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

Необязательные _mangle_from_ и maxheaderlen соответствуют базовому классу Generator.

Сноски

[1]Эта инструкция предполагает, что вы используете соответствующую настройку для unixfrom, и что есть параметры настройки нет policy, призывающие к автоматическим регуляторам (например, refold_source должен быть none, который является не дефолт). Это также не на 100% верно, так как если сообщение не соответствует стандартам RFC, иногда информация о точном исходном тексте теряется во время восстановления ошибки парсинг. Цель состоит в том, чтобы исправить эти последние краевые случаи, когда это возможно.