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

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

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

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

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

Сноски