email.generator: Генерация документов MIME

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

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

Как и в модуле 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, не переформатировать заголовки. Если manheaderlen равно None (значение по умолчанию), переформатировать заголовки и другие строки сообщения в соответствии с параметрами политики policy.

Если указана policy, использовать эту политику для управления генерацией сообщений. Если policy равна None (значение по умолчанию), использовать политику, связанную с объектом Message или EmailMessage, переданным в flatten, для управления генерацией сообщения. Смотрите email.policy для получения подробной информации о том, за что отвечает 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, и закодировать не-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. Это обеспечивает достаточно файлоподобный API для использования экземпляров 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 % 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.

Примечания