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

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

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

Как и в случае с модулем email.parser, вы не ограничены функциональностью входящего в комплект генератора; вы могли бы написать его с нуля самостоятельно. Однако встроенный генератор знает, как генерировать большинство сообщений электронной почты в соответствии со стандартами, должен отлично обрабатывать сообщения электронной почты в формате 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(), в file-like object`*outfp*. *outfp* должен поддерживать метод ``write`, который принимает двоичные данные.

Если необязательный параметр mangle_from_ равен True, поместите символ > перед любой строкой в тексте, которая начинается с точной строки "From ", то есть From, за которой следует пробел в начале начало строки. mangle_from_ по умолчанию используется значение параметра mangle_from_ для политики (которое равно True для политики compat32 и False для всех остальных). mangle_from_ предназначен для использования, когда сообщения хранятся в формате Unix mbox (см. mailbox и WHY THE CONTENT-LENGTH FORMAT IS BAD).

Если значение maxheaderlen не равно None, переформатируйте все строки заголовка, которые длиннее, чем maxheaderlen, или если 0, не переформатируйте заголовки. Если значение manheaderlen равно None (по умолчанию), перенесите заголовки и другие строки сообщений в соответствии с настройками policy.

Если указана политика, используйте эту политику для управления генерацией сообщений. Если значение policy равно None (по умолчанию), используйте политику, связанную с объектом Message или EmailMessage, переданным в flatten, для управления созданием сообщения. Смотрите email.policy для получения подробной информации о том, что контролирует политика.

Добавлено в версии 3.2.

Изменено в версии 3.3: Добавлено ключевое слово policy.

Изменено в версии 3.6: Поведение параметров mangle_from_ и maxheaderlen по умолчанию заключается в соблюдении политики.

flatten(msg, unixfrom=False, linesep=None)¶

Распечатайте текстовое представление структуры объекта message с корнем в 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) перед первым из RFC 5322 заголовков корневого объекта сообщения. Если у корневого объекта нет заголовка конверта, создайте стандартный. Значение по умолчанию - False. Обратите внимание, что для подразделов заголовок конверта никогда не печатается.

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

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. Используя терминологию предложений по электронной почте, вы можете рассматривать это как Generator сериализацию в поток ввода-вывода, который не является «8-разрядным чистым». Другими словами, большинство приложений захотят использовать BytesGenerator, а не Generator.

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

Поскольку строки не могут представлять двоичные данные, класс Generator должен преобразовать любые двоичные данные в любом сообщении, которое он сглаживает, в формат, совместимый с ASCII, путем преобразования их в формат, совместимый с ASCII flatten(). Используя терминологию предложений по электронной почте, вы можете рассматривать это как write() сериализацию в поток ввода-вывода, который не является «8-разрядным чистым». Другими словами, большинство приложений захотят использовать file-like object, а не write.

Если необязательный параметр mangle_from_ равен True, поместите символ > перед любой строкой в тексте, которая начинается с точной строки "From ", то есть From, за которой следует пробел в начале начало строки. mangle_from_ по умолчанию используется значение параметра mangle_from_ для политики (которое равно True для политики compat32 и False для всех остальных). mangle_from_ предназначен для использования, когда сообщения хранятся в формате Unix mbox (см. mailbox и WHY THE CONTENT-LENGTH FORMAT IS BAD).

Если значение maxheaderlen не равно None, переформатируйте все строки заголовка, которые длиннее, чем maxheaderlen, или если 0, не переформатируйте заголовки. Если значение manheaderlen равно None (по умолчанию), перенесите заголовки и другие строки сообщений в соответствии с настройками policy.

Если указана политика, используйте эту политику для управления генерацией сообщений. Если значение policy равно None (по умолчанию), используйте политику, связанную с объектом Message или EmailMessage, переданным в flatten, для управления созданием сообщения. Смотрите email.policy для получения подробной информации о том, что контролирует политика.

Изменено в версии 3.3: Добавлено ключевое слово policy.

Изменено в версии 3.6: Поведение параметров mangle_from_ и maxheaderlen по умолчанию заключается в соблюдении политики.

flatten(msg, unixfrom=False, linesep=None)¶

Распечатайте текстовое представление структуры объекта message с корнем в 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, выведите разделитель заголовка конверта, используемый в формате почтовых ящиков Unix (см. mailbox) перед первым из RFC 5322 заголовков корневого объекта сообщения. Если у корневого объекта нет заголовка конверта, создайте стандартный. Значение по умолчанию - False. Обратите внимание, что для подразделов заголовок конверта никогда не печатается.

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

Изменено в версии 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, за исключением того, что части, отличные от :mimetype: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-тип части, отличной от :mimetype:text

• maintype – Основной MIME-тип части, отличной от :mimetype:text

• subtype – Подтип части, отличной от :mimetype:text

• filename – Имя файла части, отличной от :mimetype:text

• description – Описание, связанное с частью, отличной от :mimetype:text

• encoding – Кодирование для передачи содержимого части, отличной от :mimetype:text

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

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

Необязательные области _mangle_from_ и maxheaderlen с базовым классом Generator.

Сноски