email.generator
: Генерация MIME документов¶
Исходный код: Lib/email/generator.py
Одной из наиболее распространенных задач является создание плоской
(сериализованной) версии сообщения электронной почты, представленной структурой
объекта сообщения. Это необходимо для отправки сообщения через модуль smtplib.SMTP.sendmail()
или модуль nntplib
или печати сообщения на консоли. Взятие структуры объекта
сообщения и создание сериализованного представления является заданием классов
генератор.
Как и в случае модуля 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)¶ Объект возвращает a
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
и ПОЧЕМУ ПЛОХ ФОРМАТ ДЛИНЫ КОНТЕНТА).Если 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, и закодируйте RFC-недействительные байты не ASCII в заголовках, используя наборunknown-8bit
символ MIME, таким образом отдав им RFC-соответствующий.Если unixfrom является
True
, перед первым из заголовков используемый объекта корневого сообщения напечатайте разделитель заголовка конвертаmailbox
по формату почтового ящика Unix (см. раздел RFC 5322). Если корневой объект не имеет заголовка оболочки, создайте стандартный объект. Значение по умолчанию -False
. Обратите внимание, что для подразделов заголовок конверта никогда не печатается.Если linesep не является
None
, используйте его в качестве разделителя символ между всеми строками распрямленного сообщения. Если linesep -None
(дефолт), используйте значение, определенный в policy.
-
clone
(fp)¶ Возвращает an независимый клон этого
BytesGenerator
сущность с точно такими же параметрами и fp как и новый outfp.
-
write
(s)¶ Закодируйте s с помощью
ASCII
кодировка и обработчика ошибокsurrogateescape
и передайте его методу write outfp, переданному конструкторуBytesGenerator
.
-
В качестве удобства EmailMessage
предоставляет методы as_bytes()
и bytes(aMessage)
(a.k.a. __bytes__()
), которые упрощают генерацию
сериализованного двоичного представления объекта сообщения. Дополнительные сведения
см. в разделе email.message
.
Поскольку строки не может представлять двоичные данные, класс Generator
должен преобразовать любые двоичные данные в любом сообщении, это сглаживает к
ASCII совместимый формат, преобразовывая их в ASCII совместимый Content-Transfer_Encoding.
Используя терминологию электронной почты RFCs, вы можете думать об этом как о
преобразовании в последовательную форму Generator
к потоку I/O,
который не является «чистыми 8 битами». Другими словами, большинство приложений
хотят использовать BytesGenerator
, а не Generator
.
-
class
email.generator.
Generator
(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)¶ Объект возвращает a
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
, чтобы управлять формированием сообщений. Подробные сведения о том, какие элементы управленияemail.policy
, см. в разделе 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 в заголовках, используя наборunknown-8bit
символ MIME, таким образом отдав им RFC-соответствующий.Если unixfrom является
True
, перед первым из заголовков используемый объекта корневого сообщения напечатайте разделитель заголовка конвертаmailbox
по формату почтового ящика Unix (см. раздел RFC 5322). Если корневой объект не имеет заголовка оболочки, создайте стандартный объект. Значение по умолчанию -False
. Обратите внимание, что для подразделов заголовок конверта никогда не печатается.Если linesep не является
None
, используйте его в качестве разделителя символ между всеми строками распрямленного сообщения. Если linesep -None
(дефолт), используйте значение, определенный в policy.Изменено в версии 3.2: Добавлена поддержка тел сообщений re-кодировка
8bit
и аргумента linesep.
-
В качестве удобства EmailMessage
предоставляет методы as_string()
и str(aMessage)
(a.k.a. __str__()
), которые упрощают поколение
отформатированного представления строка объекта сообщения. Дополнительные сведения см. в
разделе email.message
.
Модуль email.generator
также предоставляет производный класс DecodedGenerator
, который
подобен базовому классу Generator
, за исключением того, что части, не
являющиесяtext, не сериализуются, а вместо этого представляются в
выходном потоке строка, полученным из шаблона, заполненного информацией о
детали.
-
class
email.generator.
Generator
(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None) Закон как
Generator
, за исключением того, что для любого подразделения сообщения прошел кGenerator.flatten()
, если подразделение имеет главный тип text, печатает расшифрованный полезный груз подразделения, и если главный тип не text, вместо того, чтобы печатать его заполняют строка fmt, используя информацию от части и печатают заполненное получающееся - в строка.Для заполнения fmt выполните
fmt % part_info
, гдеpart_info
- словарь, состоящий из следующих ключей и значения:type
– полный тип MIME части, не являющейсяtextmaintype
– основной тип MIME части, не являющейсяtextsubtype
– Под-MIME-тип части, не являющейсяtextfilename
– имя файла части, не являющейсяtextdescription
– описание, связанное с частью, не являющейсяtextencoding
– Передача контента кодировка не являющейсяtext частью
Если fmt имеет значение
None
, используйте следующую fmt: по умолчанию«[Non-text (%(type)s) part of message omitted, filename %(filename)s]»Необязательные _mangle_from_ и maxheaderlen соответствуют базовому классу
Generator
.
Сноски
[1] | Эта инструкция предполагает, что вы используете соответствующую настройку для
unixfrom , и что есть параметры настройки нет policy , призывающие к
автоматическим регуляторам (например, refold_source должен
быть none ,
который является не дефолт). Это также не на 100% верно, так как если
сообщение не соответствует стандартам RFC, иногда информация о точном исходном
тексте теряется во время восстановления ошибки парсинг. Цель состоит в том,
чтобы исправить эти последние краевые случаи, когда это возможно. |