email.generator: Создание MIME-документов

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

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

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

Класс Generator можно использовать для преобразования сообщения в текстовое (а не бинарное) сериализованное представление. Однако, поскольку Unicode не может напрямую представлять бинарные данные, сообщение неизбежно преобразуется в представление, содержащее только символы ASCII, с помощью стандартных методов кодирования Content Transfer Encoding, определённых в RFC для передачи сообщений электронной почты по каналам, не являющимся «8-битно чистыми».

Для обеспечения воспроизводимой обработки сообщений с подписью SMIME Generator отключает сворачивание заголовков для частей сообщения типа multipart/signed и всех вложенных частей.

class email.generator.BytesGenerator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Возвращает объект BytesGenerator, который записывает в файлоподобный объект outfp любое сообщение, переданное методу flatten(), или любой текст, закодированный с помощью surrogateescape и переданный методу write(). Объект 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, не переносите заголовки повторно. Если 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, перед первым заголовком RFC 5322 корневого объекта сообщения выводится разделитель заголовка конверта, используемый форматом почтовых ящиков Unix (см. mailbox). Если у корневого объекта нет заголовка конверта, создаётся стандартный заголовок. Значение по умолчанию — 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, который записывает в файлоподобный объект outfp любое сообщение, переданное методу flatten(), или любой текст, переданный методу write(). Объект 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, не переносите заголовки повторно. Если 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, а недопустимые по RFC не-ASCII байты в заголовках кодируются с использованием набора символов MIME unknown-8bit, что приводит их в соответствие с RFC.

Если unixfrom равно True, перед первым заголовком RFC 5322 корневого объекта сообщения выводится разделитель заголовка конверта, используемый форматом почтовых ящиков Unix (см. mailbox). Если у корневого объекта нет заголовка конверта, создаётся стандартный заголовок. Значение по умолчанию — False. Обратите внимание, что для вложенных частей заголовок конверта никогда не выводится.

Если linesep не равно None, оно используется как разделитель между всеми строками свёрнутого сообщения. Если linesep равно None (значение по умолчанию), используется значение, заданное в policy.

Изменено в версии 3.2: Добавлена поддержка повторного кодирования тел сообщений 8bit и аргумента linesep.

clone(fp)

Возвращает независимую копию этого экземпляра Generator с точно такими же параметрами и с fp, используемым в качестве нового outfp.

write(s)

Записывает s с помощью метода write объекта outfp, переданного конструктору Generator. Это предоставляет экземплярам Generator минимально необходимый файловый API для использования в функции 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 части, не являющейся text
• maintype — основной тип MIME части, не являющейся text
• subtype — подтип MIME части, не являющейся text
• filename — имя файла части, не являющейся text
• description — описание, связанное с частью, не являющейся text
• encoding — кодировка передачи содержимого части, не являющейся text

Если fmt равно None, используется следующий шаблон fmt по умолчанию:

«[Часть сообщения не текстового типа (%(type)s) пропущена, имя файла %(filename)s]»

Необязательные параметры _mangle_from_ и maxheaderlen используются так же, как и в базовом классе Generator.

Сноски