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

Этот модуль является частью устаревшего (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 — это строка, содержащая необработанные аудиоданные. Если эти данные могут быть декодированы стандартным модулем 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.