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, не переформатировать заголовки. Если 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 и закодировать не-ASCII байты в заголовках, не соответствующие RFC, с помощью набора символов MIME unknown-8bit, тем самым сделав их совместимыми с RFC.

Если unixfrom равно True, вывести разделитель заголовка конверта, используемый в формате unix mailbox (см. mailbox) перед первым из заголовков RFC 5322 корневого объекта сообщения. Если у корневого объекта нет заголовка конверта, создать стандартный. По умолчанию значение равно 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, то иногда информация о точном исходном тексте теряется во время восстановления ошибок парсинга. Цель состоит в том, чтобы исправить эти крайние случаи, когда это возможно.