18.1.4. email.mime: создание объектов email и MIME с нуля¶email.mime: Creating email and MIME objects from scratch
Обычно структура объекта сообщения получается путём передачи файла или текста парсеру, который разбирает текст и возвращает корневой объект сообщения. Однако можно также собрать полную структуру сообщения с нуля или даже вручную создать отдельные объекты Message. Фактически можно взять существующую структуру и добавить новые объекты Message, перемещать их и так далее. Это даёт очень удобный интерфейс для нарезки MIME-сообщений.
Можно создать новую структуру объектов, создав экземпляры Message, вручную добавив вложения и все необходимые заголовки. Однако для MIME-сообщений пакет email предоставляет несколько удобных подклассов, упрощающих задачу.
Вот классы:
- class email.mime.base.MIMEBase(_maintype, _subtype, **_params)¶
Модуль: email.mime.base
Это базовый класс для всех MIME-специфичных подклассов Message. Обычно не создают экземпляры непосредственно MIMEBase, хотя это возможно. MIMEBase предоставляется в первую очередь как удобный базовый класс для более специализированных MIME-подклассов.
_maintype – это основной тип Content-Type (например, text или image), а _subtype – это подтип Content-Type (например, plain или gif). _params – это словарь параметров «ключ/значение», который передаётся напрямую Message.add_header().
Класс MIMEBase всегда добавляет заголовок Content-Type (на основе _maintype, _subtype и _params), а также заголовок MIME-Version (всегда установлен в 1.0).
- class email.mime.nonmultipart.MIMENonMultipart¶
Модуль: email.mime.nonmultipart
Подкласс MIMEBase, это промежуточный базовый класс для MIME-сообщений, не являющихся multipart. Основное назначение этого класса – предотвратить использование метода attach(), который имеет смысл только для multipart-сообщений. Если attach() вызывается, возникает исключение MultipartConversionError.
- class email.mime.multipart.MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, **_params)¶
Модуль: email.mime.multipart
Подкласс MIMEBase, этот класс является промежуточным базовым классом для MIME-сообщений, которые являются multipart. Необязательный параметр _subtype по умолчанию равен mixed, но может использоваться для указания подтипа сообщения. В объект сообщения будет добавлен заголовок Content-Type со значением multipart/_subtype. Также будет добавлен заголовок MIME-Version.
Необязательный параметр boundary – это строка границы multipart. Если None (по умолчанию), граница вычисляется при необходимости (например, при сериализации сообщения).
_subparts – это последовательность начальных подчастей для содержимого. Она должна преобразовываться в список. Новые подчасти можно присоединить к сообщению с помощью метода Message.attach().
Дополнительные параметры для заголовка Content-Type берутся из именованных аргументов или передаются в аргумент _params, который является словарём именованных аргументов.
- class email.mime.application.MIMEApplication(_data, _subtype='octet-stream', _encoder=email.encoders.encode_base64, **_params)¶
Модуль: email.mime.application
Подкласс MIMENonMultipart, класс MIMEApplication используется для представления объектов MIME-сообщений основного типа application. _data – это строка, содержащая необработанные байтовые данные. Необязательный параметр _subtype задаёт подтип MIME и по умолчанию равен поток октетов.
Необязательный параметр _encoder – это вызываемый объект (т.е. функция), который выполняет непосредственное кодирование данных для передачи. Этот вызываемый объект принимает один аргумент – экземпляр MIMEApplication. Он должен использовать get_payload() и set_payload() для изменения содержимого в закодированную форму. Также он должен при необходимости добавить заголовок Content-Transfer-Encoding или другие заголовки к объекту сообщения. Кодировка по умолчанию – base64. Список встроенных кодировщиков см. в модуле email.encoders.
_params передаются напрямую конструктору базового класса.
- class email.mime.audio.MIMEAudio(_audiodata, _subtype=None, _encoder=email.encoders.encode_base64, **_params)¶
Модуль: email.mime.audio
Подкласс MIMENonMultipart, класс MIMEAudio используется для создания объектов MIME-сообщений основного типа audio. _audiodata – это строка, содержащая необработанные аудиоданные. Если эти данные могут быть декодированы стандартным модулем Python sndhdr, то подтип будет автоматически включён в заголовок Content-Type. В противном случае можно явно указать подтип аудио через аргумент _subtype. Если второстепенный тип не удалось угадать, а _subtype не был указан, то возникает исключение TypeError.
Необязательный параметр _encoder – это вызываемый объект (т.е. функция), который выполняет непосредственное кодирование аудиоданных для передачи. Этот вызываемый объект принимает один аргумент – экземпляр MIMEAudio. Он должен использовать get_payload() и set_payload() для изменения содержимого в закодированную форму. Также он должен при необходимости добавить заголовок Content-Transfer-Encoding или другие заголовки к объекту сообщения. Кодировка по умолчанию – base64. Список встроенных кодировщиков см. в модуле email.encoders.
_params передаются напрямую конструктору базового класса.
- class email.mime.image.MIMEImage(_imagedata, _subtype=None, _encoder=email.encoders.encode_base64, **_params)¶
Модуль: email.mime.image
Подкласс MIMENonMultipart, класс MIMEImage используется для создания объектов MIME-сообщений основного типа image. _imagedata – это строка, содержащая необработанные данные изображения. Если эти данные могут быть декодированы стандартным модулем Python imghdr, то подтип будет автоматически включён в заголовок Content-Type. В противном случае можно явно указать подтип изображения через аргумент _subtype. Если второстепенный тип не удалось угадать, а _subtype не был указан, то возникает исключение TypeError.
Необязательный параметр _encoder – это вызываемый объект (т.е. функция), который выполняет непосредственное кодирование данных изображения для передачи. Этот вызываемый объект принимает один аргумент – экземпляр MIMEImage. Он должен использовать get_payload() и set_payload() для изменения содержимого в закодированную форму. Также он должен при необходимости добавить заголовок Content-Transfer-Encoding или другие заголовки к объекту сообщения. Кодировка по умолчанию – base64. Список встроенных кодировщиков см. в модуле email.encoders.
_params передаются напрямую конструктору MIMEBase.
- class email.mime.message.MIMEMessage(_msg, _subtype='rfc822')¶
Модуль: email.mime.message
Класс MIMEMessage – подкласс MIMENonMultipart, предназначен для создания MIME-объектов основного типа message. Параметр _msg используется в качестве полезной нагрузки и должен быть экземпляром класса Message (или его подкласса), иначе возбуждается исключение TypeError.
Необязательный _subtype задаёт подтип сообщения; по умолчанию rfc822.
- class email.mime.text.MIMEText(_text, _subtype='plain', _charset='us-ascii')¶
Модуль: email.mime.text
Подкласс MIMENonMultipart, класс MIMEText используется для создания MIME-объектов основного типа text. _text – это строка, содержащая данные (payload). _subtype – это подтип, по умолчанию plain. _charset – это кодировка текста, которая передаётся в качестве аргумента конструктору MIMENonMultipart; по умолчанию us-ascii.
Если аргумент _charset явно не установлен в None, создаваемый объект MIMEText будет иметь как заголовок Content-Type с параметром charset, так и заголовок Content-Transfer-Endcoding. Это означает, что последующий вызов set_payload не приведёт к кодированию полезной нагрузки, даже если кодировка передана в команде set_payload. Можно «сбросить» это поведение, удалив заголовок Content-Transfer-Encoding; после этого вызов set_payload автоматически закодирует новую полезную нагрузку (и добавит новый заголовок Content-Transfer-Encoding).