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

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

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

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

Вот эти классы:

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 и по умолчанию равен octet-stream.

Необязательный _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

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

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

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

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

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

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

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