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

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

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

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

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