email.mime: Creating email and MIME objects from scratch

Вихідний код: Lib/email/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.

Якщо вказано політику (за замовчуванням політика 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.

Необов’язковий межа — це обмежувальний рядок із кількох частин. Якщо 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

A subclass of MIMENonMultipart, the MIMEApplication class is used to represent MIME message objects of major type application. _data contains the bytes for the raw application data. Optional _subtype specifies the MIME subtype and defaults to 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

A subclass of MIMENonMultipart, the MIMEAudio class is used to create MIME message objects of major type audio. _audiodata contains the bytes for the raw audio data. If this data can be decoded as au, wav, aiff, or aifc, then the subtype will be automatically included in the Content-Type header. Otherwise you can explicitly specify the audio subtype via the _subtype argument. If the minor type could not be guessed and _subtype was not given, then TypeError is raised.

Необов’язковий _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

A subclass of MIMENonMultipart, the MIMEImage class is used to create MIME message objects of major type image. _imagedata contains the bytes for the raw image data. If this data type can be detected (jpeg, png, gif, tiff, rgb, pbm, pgm, ppm, rast, xbm, bmp, webp, and exr attempted), then the subtype will be automatically included in the Content-Type header. Otherwise you can explicitly specify the image subtype via the _subtype argument. If the minor type could not be guessed and _subtype was not given, then TypeError is raised.

Необов’язковий _encoder — це виклик (тобто функція), яка виконуватиме фактичне кодування даних зображення для транспортування. Цей виклик приймає один аргумент, який є екземпляром MIMEImage. Він має використовувати get_payload() і set_payload(), щоб змінити корисне навантаження на закодовану форму. Він також має додати будь-які Content-Transfer-Encoding або інші заголовки до об’єкта повідомлення за потреби. Стандартне кодування — base64. Перегляньте список вбудованих кодувальників у модулі email.encoders.

Додатковий аргумент policy за умовчанням має значення compat32.

_параметри передаються безпосередньо до конструктора 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 лише для ключового слова.