email.mime: Создание объектов электронной почты и MIME с нуля

Обычно вы получаете структуру объекта сообщения, передавая файл или текст в анализатор, который анализирует текст и возвращает корневой объект сообщения. Однако вы также можете построить полную структуру сообщения с нуля или даже отдельные объекты 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.

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

class email.mime.multipart.MIMEMultipart([_subtype[, boundary[, _subparts[, _params]]]])

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

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

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

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

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

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

class email.mime.application.MIMEApplication(_data[, _subtype[, _encoder[, **_params]]])

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

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

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

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

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

class email.mime.audio.MIMEAudio(_audiodata[, _subtype[, _encoder[, **_params]]])

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

Класс MIMEAudio, являющийся подклассом MIMENonMultipart, используется для создания объектов сообщений 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[, _encoder[, **_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])

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

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

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

class email.mime.text.MIMEText(_text[, _subtype[, _charset]])

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

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

Изменено в версии 2.4: Предыдущий устаревший аргумент _encoding был удалён. Кодирование Content Transfer Encoding теперь происходит неявно на основе аргумента _charset.

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