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

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

Этот модуль является частью устаревшего API электронной почты (Compat32). В новом 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 — строка-разделитель частей составного сообщения. Если задано 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; по умолчанию он равен octet-stream.

Необязательный параметр _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 содержит байты исходных аудиоданных. Если эти данные можно декодировать как au, wav, aiff или aifc, подтип будет автоматически добавлен в заголовок 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 содержит байты исходных данных изображения. Если тип этих данных можно определить (проверяются jpeg, png, gif, tiff, rgb, pbm, pgm, ppm, rast, xbm, bmp, webp и exr), подтип будет автоматически добавлен в заголовок 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, доступный только по ключевому слову.