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_ политики 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 теперь соответствует политике policy.

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