email.generator
: Генерация документов MIME¶
Источник: Lib/email/generator.py
Одна из самых распространенных задач - сгенерировать плоскую (сериализованную) версию почтового сообщения, представленную структурой объекта message. Это необходимо, если вы хотите отправить сообщение через smtplib.SMTP.sendmail()
или вывести его на консоль. Получение объектной структуры сообщения и создание сериализованного представления - это работа классов-генераторов.
Как и в случае с модулем email.parser
, вы не ограничены функциональностью поставляемого в комплекте генератора; вы можете написать его с нуля самостоятельно. Однако поставляемый в комплекте генератор знает, как генерировать большинство сообщений электронной почты в соответствии со стандартами, должен отлично работать с сообщениями MIME и не-MIME, и спроектирован таким образом, что операции разбора и генерации, ориентированные на байты, являются инверсными, предполагая, что для обеих операций используется один и тот же не преобразующий policy
. То есть разбор сериализованного потока байтов с помощью класса BytesParser
и последующая регенерация сериализованного потока байтов с помощью BytesGenerator
должны дать результат, идентичный входному [1]. (С другой стороны, использование генератора для EmailMessage
, созданного программой, может привести к изменениям в объекте EmailMessage
при заполнении значений по умолчанию).
Класс Generator
можно использовать для преобразования сообщения в текстовое (в отличие от двоичного) сериализованное представление, но поскольку Unicode не может представлять двоичные данные напрямую, сообщение необходимо преобразовать в нечто, содержащее только символы ASCII, используя стандартные методы кодирования электронной почты RFC Content Transfer Encoding для кодирования сообщений электронной почты для передачи по каналам, которые не являются «8-битными».
Для обеспечения воспроизводимой обработки сообщений с подписью SMIME Generator
отключает сворачивание заголовков для частей сообщения типа multipart/signed
и всех подчастей.
- class email.generator.BytesGenerator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)¶
Возвращает объект
BytesGenerator
, который запишет любое сообщение, переданное в методflatten()
, или любой суррогатно-кодированный текст, переданный в методwrite()
, в file-like object. 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 равно
None
(по умолчанию), для управления генерацией сообщений используется политика, связанная с объектомMessage
илиEmailMessage
, переданным вflatten
. Подробнее о том, чем управляет policy, см. в разделеemail.policy
.Added in version 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 байты в заголовках, используя набор символов MIMEunknown-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, путем преобразования их в Content-Transfer_Encoding, совместимый с ASCII. Используя терминологию почтовых RFC, вы можете представить это как сериализацию Generator
в поток ввода-вывода, который не является «8-битным». Другими словами, большинство приложений захотят использовать BytesGenerator
, а не Generator
.
- class email.generator.Generator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)¶
Возвращает объект
Generator
, который запишет любое сообщение, переданное в методflatten()
, или любой текст, переданный в методwrite()
, в file-like object. 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 равно
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 байты в заголовках с помощью набора символов MIMEunknown-8bit
, сделав их RFC-совместимыми.Если unixfrom равно
True
, выведите разделитель заголовков конвертов, используемый форматом почтовых ящиков Unix (см.mailbox
), перед первым из RFC 5322 заголовков корневого объекта сообщения. Если корневой объект не имеет заголовка конверта, выведите стандартный заголовок. По умолчанию используетсяFalse
. Обратите внимание, что для подчастей заголовок конверта никогда не печатается.Если linesep не
None
, используйте его в качестве символа-разделителя между всеми строками сплющенного сообщения. Если linesep имеет значениеNone
(по умолчанию), используйте значение, указанное в policy.Изменено в версии 3.2: Добавлена поддержка повторного кодирования тел сообщений
8bit
и аргумент linesep.
Для удобства в 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-тип части неtextmaintype
– Основной MIME-тип неtext частиsubtype
– Sub-MIME тип части non-textfilename
– Имя файла неtext частиdescription
– Описание, связанное с частью non-textencoding
– Кодировка передачи содержимого части неtext
Если значение fmt равно
None
, используйте следующее значение fmt по умолчанию:«[Нетекстовая (%(type)s) часть сообщения опущена, имя файла %(filename)s]».
Необязательные параметры _mangle_from_ и maxheaderlen - как у базового класса
Generator
.
Сноски