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-битными».

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