19.1.10. email.mime: Создание email и MIME объектов с нуля¶email.mime: Creating email and MIME objects from scratch

Исходный код: Lib/email/mime/

Этот модуль является частью устаревшего (Compat32) email API. Его функциональность частично заменена contentmanager в новом API, но в некоторых приложениях эти классы могут по-прежнему быть полезными, даже в неустаревшем коде.

Обычно структура объекта сообщения получается передачей файла или текста парсеру, который разбирает текст и возвращает корневой объект сообщения. Однако можно также построить полную структуру сообщения с нуля или даже отдельные Message объекты вручную. Более того, можно взять существующую структуру и добавить новые Message объекты, перемещать их и т.д. Это делает очень удобным интерфейс для разделения и обработки MIME сообщений.

Можно создать новую структуру объекта, создавая экземпляры Message , добавляя вложения и все соответствующие заголовки вручную. Однако для MIME-сообщений пакет email предоставляет несколько удобных подклассов, которые упрощают задачу.

Вот классы:

class email.mime.base.MIMEBase(_maintype, _subtype, *, policy=compat32, **_params)¶

Модуль: email.mime.base

Это базовый класс для всех MIME-специфических подклассов Message. Обычно не создаются экземпляры непосредственно MIMEBase, хотя это возможно. MIMEBase предоставляется в первую очередь как удобный базовый класс для более специализированных подклассов, работающих с MIME.

_maintype – это основной тип Content-Type (например, text или image), а _subtype – это подтип Content-Type (например, plain или gif). _params – это словарь ключей/значений параметров, который передаётся напрямую в Message.add_header.

Если указан policy (по умолчанию используется политика compat32), он будет передан в Message.

Класс MIMEBase всегда добавляет заголовок Content-Type (на основе _maintype, _subtype и _params) и заголовок MIME-Version (всегда установлен в 1.0).

Изменено в версии 3.6: Добавлен параметр policy, передаваемый только по ключу.

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, *, policy=compat32, **_params)¶

Модуль: email.mime.multipart

Подкласс MIMEBase, это промежуточный базовый класс для MIME-сообщений, которые являются multipart. Необязательный параметр _subtype по умолчанию равен mixed, но может использоваться для указания подтипа сообщения. Заголовок Content-Type со значением multipart/_subtype будет добавлен к объекту сообщения. Также будет добавлен заголовок MIME-Version.

Необязательный параметр boundary – строка границы для multipart. Если None (по умолчанию), граница вычисляется при необходимости (например, при сериализации сообщения).

_subparts – последовательность начальных подчастей для полезной нагрузки. Эта последовательность должна быть преобразуема в список. Новые подчасти всегда можно присоединить к сообщению с помощью метода Message.attach.

Необязательный аргумент policy по умолчанию равен compat32.

Дополнительные параметры для заголовка Content-Type берутся из именованных аргументов или передаются в аргумент _params, который является словарём именованных аргументов.

Изменено в версии 3.6: Добавлен параметр policy, передаваемый только по ключу.

class email.mime.application.MIMEApplication(_data, _subtype='octet-stream', _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)¶

Модуль: email.mime.application

Подкласс MIMENonMultipart. Класс MIMEApplication используется для представления объектов MIME-сообщений с основным типом application. _data – строка, содержащая необработанные байтовые данные. Необязательный параметр _subtype задаёт подтип MIME; по умолчанию поток октетов.

Необязательный параметр _encoder – это вызываемый объект (т.е. функция), который выполняет фактическое кодирование данных для передачи. Этот вызываемый объект принимает один аргумент – экземпляр MIMEApplication. Он должен использовать get_payload() и set_payload() для преобразования полезной нагрузки в закодированную форму. Также он должен при необходимости добавить заголовок Content-Transfer-Encoding или другие заголовки к объекту сообщения. Кодирование по умолчанию – base64. Список встроенных кодировщиков приведён в модуле email.encoders.

Необязательный аргумент policy по умолчанию равен compat32.

_params передаются напрямую конструктору базового класса.

Изменено в версии 3.6: Добавлен параметр policy, передаваемый только по ключу.

class email.mime.audio.MIMEAudio(_audiodata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_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.

Необязательный аргумент policy по умолчанию равен compat32.

_params передаются напрямую конструктору базового класса.

Изменено в версии 3.6: Добавлен параметр policy, передаваемый только по ключу.

class email.mime.image.MIMEImage(_imagedata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_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.

Необязательный аргумент policy по умолчанию равен compat32.

_params передаются напрямую конструктору MIMEBase.

Изменено в версии 3.6: Добавлен параметр policy, передаваемый только по ключу.

class email.mime.message.MIMEMessage(_msg, _subtype='rfc822', *, policy=compat32)¶

Модуль: email.mime.message

Подкласс MIMENonMultipart, класс MIMEMessage используется для создания MIME-объектов основного типа message. _msg используется в качестве полезной нагрузки и должен быть экземпляром класса Message (или его подкласса), в противном случае возбуждается исключение TypeError.

Необязательный _subtype задаёт подтип сообщения; по умолчанию rfc822.

Необязательный аргумент policy по умолчанию равен compat32.

Изменено в версии 3.6: Добавлен параметр policy, передаваемый только по ключу.

class email.mime.text.MIMEText(_text, _subtype='plain', _charset=None, *, policy=compat32)¶

Модуль: email.mime.text

Подкласс MIMENonMultipart, класс MIMEText используется для создания MIME-объектов основного типа text. _text – строка для полезной нагрузки. _subtype – подтип, по умолчанию plain. _charset – набор символов текста; передаётся в качестве аргумента конструктору MIMENonMultipart; по умолчанию us-ascii, если строка содержит только кодовые точки ascii, и utf-8 в противном случае. Параметр _charset принимает как строку, так и экземпляр Charset.

Если аргумент _charset явно не установлен в None, созданный объект MIMEText будет иметь заголовки Content-Type с параметром charset и Content-Transfer-Encoding. Это означает, что последующий вызов set_payload не приведёт к кодированию полезной нагрузки, даже если в команду set_payload передан набор символов. Чтобы «сбросить» это поведение, можно удалить заголовок Content-Transfer-Encoding, после чего вызов set_payload автоматически закодирует новую полезную нагрузку (и добавит новый заголовок Content-Transfer-Encoding).

Необязательный аргумент policy по умолчанию равен compat32.

Изменено в версии 3.5: _charset также принимает экземпляры Charset.

Изменено в версии 3.6: Добавлен параметр policy, передаваемый только по ключу.