19.1.6. email.contentmanager: Управление MIME-содержимым¶email.contentmanager: Managing MIME Content

Модуль message предоставляет класс, который может представлять произвольное email-сообщение. Эта базовая модель сообщения имеет полезный и гибкий API, но предоставляет только низкоуровневый API для взаимодействия с общими частями сообщения (заголовки, общие параметры заголовков и полезная нагрузка, которая может быть списком подчастей). Данный модуль предоставляет классы и инструменты, которые обеспечивают улучшенный и расширяемый API для работы с различными конкретными типами содержимого, включая возможность извлекать содержимое сообщения в виде специализированного объекта, а не простого объекта bytes. Модуль автоматически обрабатывает указанные в RFC детали MIME (обязательные заголовки и параметры и т.д.) для определённых распространённых типов содержимого, а поддержка дополнительных типов может быть добавлена приложением с помощью механизмов расширения.

Этот модуль определяет одноимённые классы «Content Manager». Базовый класс ContentManager определяет API для регистрации функций управления содержимым, которые извлекают данные из объектов Message или вставляют данные и заголовки в объекты Message, предоставляя тем самым способ преобразования между объектами Message, содержащими данные, и другими представлениями этих данных (типы данных Python, специализированные объекты Python, внешние файлы и т.д.). Модуль также определяет один конкретный менеджер содержимого: raw_data_manager преобразует между типами MIME-содержимого и данными str или bytes. Он также предоставляет удобный API для управления параметрами MIME при вставке содержимого в объекты Message. Он также обрабатывает вставку и извлечение объектов Message при работе с типом содержимого message/rfc822.

Ещё одна часть улучшенного интерфейса – подклассы Message, предоставляющие новые удобные функции API, включая удобные методы для вызова Content Managers, производных от этого модуля.

class email.message.EmailMessage(policy=default)¶

Если указан policy (он должен быть экземпляром класса policy), используйте заданные им правила для обновления и сериализации представления сообщения. Если policy не задан, используется политика default, которая следует правилам RFC для email, за исключением окончаний строк (вместо предписанного RFC \r\n используются стандартные для Python окончания строк \n). Дополнительную информацию см. в документации policy.

Этот класс является подклассом Message. Он добавляет следующие методы:

is_attachment()¶

Возвращает True, если присутствует заголовок Content-Disposition и его значение (без учёта регистра) равно attachment, иначе False.

Изменено в версии 3.4.2: is_attachment теперь является методом, а не свойством, для согласованности с is_multipart().

get_body(preferencelist=('related', 'html', 'plain'))¶

Возвращает MIME-часть, которая наилучшим образом подходит на роль «тела» сообщения.

preferencelist должен быть последовательностью строк из набора related, html и plain, и указывает порядок предпочтения типа содержимого возвращаемой части.

Начинает поиск подходящих кандидатов с объекта, на котором вызывается метод get_body.

Если related не включён в preferencelist, то рассматривать корневую часть (или подчасть корневой части) любого встреченного related как кандидата, если (под)часть соответствует предпочтению.

При обнаружении multipart/related проверьте параметр start, и если найдена часть с соответствующим Content-ID, при поиске подходящих кандидатов рассматривайте только её. В противном случае рассматривайте только первую (корневую по умолчанию) часть multipart/related.

Если часть имеет заголовок Content-Disposition, считайте её подходящим кандидатом, только если значение заголовка равно inline.

Если ни один из кандидатов не соответствует ни одному из предпочтений в preferneclist, возвращается None.

Примечания: (1) Для большинства приложений единственными комбинациями preferencelist, которые действительно имеют смысл, являются ('plain',), ('html', 'plain') и значение по умолчанию ('related', 'html', 'plain'). (2) Поскольку поиск начинается с объекта, на котором вызывается get_body, вызов get_body на multipart/related вернёт сам объект, если только preferencelist не имеет нестандартного значения. (3) Сообщения (или части сообщений), не указывающие Content-Type или имеющие недопустимый заголовок Content-Type, будут обрабатываться как тип text/plain, что иногда может привести к неожиданным результатам get_body.

iter_attachments()¶

Возвращает итератор по всем частям сообщения, которые не являются подходящими «теловыми» частями. То есть пропускает первое вхождение каждого из text/plain, text/html, multipart/related или multipart/alternative (если только они явно не помечены как вложения через Content-Disposition: attachment) и возвращает все остальные части. При применении непосредственно к multipart/related возвращает итератор по всем связанным частям, кроме корневой части (т.е. части, на которую указывает параметр start, или первой части, если параметр start отсутствует, или параметр start не соответствует Content-ID ни одной из частей). При применении непосредственно к multipart/alternative или не-multipart возвращает пустой итератор.

iter_parts()¶

Возвращает итератор по всем непосредственным подчастям сообщения, который будет пуст для не-multipart. (См. также walk().)

get_content(*args, content_manager=None, **kw)¶

Вызывает метод get_content объекта content_manager, передавая self в качестве объекта сообщения, а также любые другие аргументы или ключевые слова в качестве дополнительных аргументов. Если content_manager не указан, используется content_manager, заданный текущим policy.

set_content(*args, content_manager=None, **kw)¶

Вызывает метод set_content объекта content_manager, передавая self в качестве объекта сообщения, а также любые другие аргументы или ключевые слова в качестве дополнительных аргументов. Если content_manager не указан, используется content_manager, заданный текущим policy.

make_related(boundary=None)¶

Преобразует не-multipart сообщение в сообщение multipart/related, перемещая все существующие заголовки Content- и полезную нагрузку в (новую) первую часть multipart. Если указан boundary, используйте его как строку границы в multipart, в противном случае оставьте границу, чтобы она была создана автоматически, когда потребуется (например, при сериализации сообщения).

make_alternative(boundary=None)¶

Преобразует не-multipart или multipart/related в multipart/alternative, перенося все существующие заголовки Content- и полезную нагрузку в (новую) первую часть multipart. Если указан boundary, использовать его как строку границы в multipart, в противном случае оставить границу для автоматического создания, когда она понадобится (например, при сериализации сообщения).

make_mixed(boundary=None)¶

Преобразует не-multipart, multipart/related или multipart-alternative в multipart/mixed, перенося все существующие заголовки Content- и полезную нагрузку в (новую) первую часть multipart. Если указан boundary, использовать его как строку границы в multipart, в противном случае оставить границу для автоматического создания, когда она понадобится (например, при сериализации сообщения).

add_related(*args, content_manager=None, **kw)¶

Если сообщение является multipart/related, создаёт новый объект сообщения, передаёт все аргументы его методу set_content() и присоединяет его к multipart. Если сообщение является не-multipart, вызывает make_related() и затем действует как описано выше. Если сообщение относится к любому другому типу multipart, возбуждает TypeError. Если content_manager не указан, используется content_manager, заданный текущей политикой. Если добавленная часть не имеет заголовка Content-Disposition, добавляется заголовок со значением inline.

add_alternative(*args, content_manager=None, **kw)¶

Если сообщение является multipart/alternative, создаёт новый объект сообщения, передаёт все аргументы его методу set_content() и присоединяет его к multipart. Если сообщение является не-multipart или multipart/related, вызывает make_alternative() и затем действует как описано выше. Если сообщение относится к любому другому типу multipart, возбуждает TypeError. Если content_manager не указан, используется content_manager, заданный текущей политикой.

add_attachment(*args, content_manager=None, **kw)¶

Если сообщение является multipart/mixed, создаёт новый объект сообщения, передаёт все аргументы его методу set_content() и присоединяет его к multipart. Если сообщение является не-multipart, multipart/related или multipart/alternative, вызывает make_mixed() и затем действует как описано выше. Если content_manager не указан, используется content_manager, заданный текущей политикой. Если добавленная часть не имеет заголовка Content-Disposition, добавляет заголовок со значением attachment. Этот метод можно использовать как для явных вложений (Content-Disposition: attachment), так и для inline вложений (Content-Disposition: inline), передавая соответствующие параметры в content_manager.

clear()¶

Удаляет полезную нагрузку и все заголовки.

clear_content()¶

Удаляет полезную нагрузку и все заголовки Content-, оставляя все остальные заголовки нетронутыми и в их исходном порядке.

class email.message.MIMEPart(policy=default)¶

Этот класс представляет подчасть MIME-сообщения. Он идентичен EmailMessage, за исключением того, что заголовки MIME-Version не добавляются при вызове set_content(), поскольку подчасти не нуждаются в собственных заголовках MIME-Version.

class email.contentmanager.ContentManager¶

Базовый класс для менеджеров содержимого. Предоставляет стандартные механизмы реестра для регистрации преобразователей между MIME-содержимым и другими представлениями, а также диспетчерские методы get_content и set_content.

get_content(msg, *args, **kw)¶

Ищет функцию-обработчик на основе mimetype сообщения msg (см. следующий абзац), вызывает её, передавая все аргументы, и возвращает результат вызова. Ожидается, что обработчик извлечёт полезную нагрузку из msg и вернёт объект, кодирующий информацию об извлечённых данных.

Для поиска обработчика ищутся следующие ключи в реестре; поиск прекращается при первом найденном:

• строка, представляющая полный MIME-тип (maintype/subtype)
• строка, представляющая maintype
• пустая строка

Если ни один из этих ключей не даёт обработчика, возбуждает KeyError для полного MIME-типа.

set_content(msg, obj, *args, **kw)¶

Если maintype является multipart, возбуждает TypeError; в противном случае ищет функцию-обработчик на основе типа obj (см. следующий абзац), вызывает clear_content() на msg и вызывает функцию-обработчик, передавая все аргументы. Ожидается, что обработчик преобразует и сохранит obj в msg, возможно также внося другие изменения в msg, такие как добавление различных MIME-заголовков для кодирования информации, необходимой для интерпретации сохранённых данных.

Чтобы найти обработчик, необходимо получить тип obj (typ = type(obj)) и искать следующие ключи в реестре, останавливаясь на первом найденном:

• сам тип (typ)
• полное квалифицированное имя типа (typ.__module__ + '.' + typ.__qualname__).
• qualname типа (typ.__qualname__)
• имя типа (typ.__name__).

Если ни одно из вышеперечисленных не совпадает, повторить все проверки выше для каждого из типов в MRO (typ.__mro__). Наконец, если ни один другой ключ не даёт обработчика, проверить наличие обработчика для ключа None. Если обработчика для None нет, возбуждает KeyError для полного квалифицированного имени типа.

Также добавляет заголовок MIME-Version, если он отсутствует (см. также MIMEPart).

add_get_handler(key, handler)¶

Записывает функцию handler как обработчик для key. Возможные значения key см. в get_content().

add_set_handler(typekey, handler)¶

Записывает handler как функцию, которая будет вызываться, когда объект типа, соответствующего typekey, передаётся в set_content(). Возможные значения typekey см. в set_content().