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

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

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

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

Класс Generator может использоваться для преобразования сообщения в текстовое (в отличие от двоичного) сериализованное представление, но поскольку Unicode не может напрямую представлять двоичные данные, сообщение необходимо преобразовать в нечто, содержащее только символы ASCII, используя стандартные методы кодирования содержимого электронной почты RFC для кодирования сообщений электронной почты для передачи по каналам, которые не являются «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_ политики (которое равно True для политики compat32 и False для всех остальных). mangle_from_ предназначен для использования, когда сообщения хранятся в формате Unix mbox (см. mailbox и WHY THE CONTENT-LENGTH FORMAT IS BAD).

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

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

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

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

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

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

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

Если опция policy cte_type имеет значение 8bit (по умолчанию), любые заголовки из исходного разобранного сообщения, которые не были изменены, копируются в вывод с любыми байтами с установленным старшим битом, как в оригинале, и сохраняется кодировка 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) перед первым из заголовков 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. Это предоставляет достаточно функционала типа «подобный файлу» для использования экземпляров 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(), если основным типом части является текст, выводится декодированная полезная нагрузка части, а если основным типом не является текст, вместо вывода части заполняется строка 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.

Примечания