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

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

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

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

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

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

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

Возвращает объект 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 и WHY THE CONTENT-LENGTH FORMAT IS BAD).

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

Если указан параметр policy, то для управления генерацией сообщений используется эта политика. Если policy равен None (по умолчанию), то используется политика, связанная с объектом Message или EmailMessage, переданным в flatten. Подробности о том, что контролирует параметр policy, см. в email.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, и не-ASCII байты, некорректные в RFC, в заголовках кодируются с помощью набора символов MIME unknown-8bit, таким образом делая их совместимыми с RFC.

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

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

clone(fp)

Возвращает независимую копию экземпляра BytesGenerator с теми же настройками параметров, где fp — новый outfp.

write(s)

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

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

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

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

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

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

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

Если указан параметр policy, используйте его для управления генерацией сообщения. Если policy равен None (по умолчанию), используйте политику, связанную с объектом Message или EmailMessage, переданным flatten, для управления генерацией сообщения. Подробности о том, что контролирует policy, см. в email.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. То есть преобразуйте части с Content-Transfer-Encoding, не являющимся ASCII (Content-Transfer-Encoding: 8bit), в совместимый с ASCII Content-Transfer-Encoding и закодируйте несоответствующие RFC байты, не являющиеся ASCII, в заголовках, используя наборы символов MIME unknown-8bit, тем самым сделав их совместимыми с RFC.

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

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

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

clone(fp)

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

write(s)

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

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

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

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

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

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

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

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

“[Нетекстовая часть (%(type)s) сообщения опущена, имя файла %(filename)s]”

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

Примечания

1

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