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

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

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

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

Класс Generator можно использовать для преобразования сообщения в текстовое (а не двоичное) сериализованное представление. Но поскольку Юникод не может напрямую представлять двоичные данные, сообщение неизбежно преобразуется в формат, содержащий только символы ASCII, с использованием стандартных методов кодирования передачи содержимого, описанных в 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.

Сноски