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 RFC для кодирования сообщений электронных писем для передачи по каналам, которые не являются «8-битовыми».

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 для управления генерацией сообщения. Подробности о том, что контролирует 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, выводит разделитель заголовка конверта, используемый в формате 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 и WHY THE CONTENT-LENGTH FORMAT IS BAD).

Если maxheaderlen не равно None, переформатировать любые строки заголовков, длина которых превышает maxheaderlen, или если 0, не переформатировать никакие заголовки. Если manheaderlen равно 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. То есть преобразуйте части с не-ASCII Content-Transfer-Encoding (Content-Transfer-Encoding: 8bit) в совместимый с ASCII Content-Transfer-Encoding и кодируйте не-ASCII байты в заголовках, не соответствующие RFC, с помощью набора символов MIME unknown-8bit , тем самым сделав их совместимыми с RFC.

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

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, то при восстановлении ошибок разбора иногда теряется информация о точном исходном тексте. Цель состоит в том, чтобы исправлять такие крайние случаи, когда это возможно.