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

Исходный код: Lib/email/contentmanager.py

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

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

Другая часть расширенного интерфейса — подклассы Message, которые предоставляют новые удобные функции API, включая удобные методы для вызова менеджеров содержимого, полученных из этого модуля.

class email.message.EmailMessage(policy=default)

Если задан параметр policy (он должен быть экземпляром класса policy) используйте правила, которые он определяет, для обновления и сериализации представления сообщения. Если policy не задан, используйте политику default, которая следует правилам RFC для электронной почты, за исключением символов конца строки (вместо предписанных 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, рассматривайте корневую часть (или подчасть корневой части) любых связанных элементов в качестве кандидата, если (под)часть соответствует предпочтению.

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

Если у части есть заголовок Content-Disposition, учитывайте эту часть в качестве соответствующего кандидата только если значение заголовка равно inline.

Если ни один из кандидатов не соответствует ни одному из предпочтений в preferencelist, верните 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(), и attach() его в multipart. Если сообщение не является multipart, вызовите make_related(), а затем выполните действия, как описано выше. Если сообщение является другим типом multipart, вызовите TypeError. Если content_manager не указан, используйте content_manager, определённую текущей policy. Если добавленная часть не имеет заголовка Content-Disposition, добавьте его со значением inline.

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

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

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

Если сообщение является multipart/mixed, создайте новый объект сообщения, передайте все аргументы в его метод set_content(), и attach() его в multipart. Если сообщение не является multipart, multipart/related, или multipart/alternative, вызовите make_mixed(), а затем выполните действия, как описано выше. Если content_manager не указан, используйте content_manager, определённую текущей policy. Если добавленная часть не имеет заголовка 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().

1. Менеджеры контента

В настоящее время пакет email предоставляет только один конкретный менеджер контента, raw_data_manager, хотя в будущем могут быть добавлены и другие. raw_data_manager — это content_manager, предоставляемый EmailPolicy и его производными.

email.contentmanager.raw_data_manager

Этот менеджер контента предоставляет только минимальный интерфейс, помимо того, что предоставляется самим Message: он работает только с текстом, сырыми байтовыми строками и Message объектами. Тем не менее, он предоставляет значительные преимущества по сравнению с базовым API: get_content по текстовой части вернёт строку Unicode без необходимости ручного декодирования со стороны приложения, set_content предоставляет богатый набор опций для управления заголовками, добавляемыми к части, и управления кодировкой перевода содержимого, и он позволяет использовать различные add_ методы, тем самым упрощая создание составных сообщений.

email.contentmanager.get_content(msg, errors='replace')

Возвращает полезную нагрузку части в виде строки (для text частей), объекта EmailMessage (для message/rfc822 частей) или объекта bytes (для всех других типов, не являющихся составными). Возбуждает KeyError, если вызвано для multipart. Если часть является text частью и задан errors, используйте его как обработчик ошибок при декодировании полезной нагрузки в Unicode. По умолчанию используется обработчик ошибок replace.

email.contentmanager.set_content(msg, <'str'>, subtype="plain", charset='utf-8' cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)

email.contentmanager.set_content(msg, <'bytes'>, maintype, subtype, cte="base64", disposition=None, filename=None, cid=None, params=None, headers=None)

email.contentmanager.set_content(msg, <'Message'>, cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)

email.contentmanager.set_content(msg, <'list'>, subtype='mixed', disposition=None, filename=None, cid=None, params=None, headers=None)

Добавить заголовки и полезную нагрузку к msg:

Добавить заголовок Content-Type со значением maintype/subtype.

• Для str, задайте MIME maintype на text, и установите подтип на subtype, если он задан, или plain если он не задан.
• Для bytes, используйте указанные maintype и subtype, или вызовите TypeError, если они не указаны.
• Для объектов Message, установите maintype на message, и установите подтип на subtype, если он задан, или rfc822 если он не задан. Если subtype является partial, вызовите ошибку (объекты bytes должны использоваться для построения message/partial частей).
• Для <’list’>, который должен быть списком объектов Message, установите maintype на multipart, а subtype на subtype, если он задан, и mixed если он не задан. Если части сообщения в <’list’> содержат заголовки MIME-Version, удалите их.

Если задан charset (что допустимо только для str), закодируйте строку в байты с использованием указанного набора символов. По умолчанию utf-8. Если указанный charset является известным псевдонимом для стандартного имени набора символов MIME, используйте стандартный набор символов вместо него.

Если cte задано, закодируйте полезную нагрузку с использованием указанной кодировки перевода содержимого и задайте заголовок Content-Transfer-Encoding на это значение. Для объектов str, если он не задан, используйте эвристику для определения наиболее компактной кодировки. Возможные значения для cte — quoted-printable, base64, 7bit, 8bit, и binary. Если вход не может быть закодирован в указанной кодировке (например: 7bit), вызовите ValueError. Для Message, в соответствии с RFC 2046, вызовите ошибку, если запрошено cte quoted-printable или base64 для subtype rfc822, и для любого cte, отличного от 7bit для subtype external-body. Для message/rfc822, используйте 8bit если cte не указано. Для всех других значений subtype, используйте 7bit.

Примечание

cte значения binary на самом деле ещё не работает корректно. Объект Message, изменённый set_content, корректен, но BytesGenerator не сериализует его корректно.

Если disposition задано, используйте его в качестве значения заголовка Content-Disposition. Если не задано и filename задано, добавьте заголовок со значением attachment. Если не задано и filename также не задано, не добавляйте заголовок. Единственные допустимые значения для disposition — attachment и inline.

Если filename указано, используйте его в качестве значения параметра filename заголовка Content-Disposition. Значения по умолчанию нет.

Если cid задано, добавьте заголовок Content-ID со значением cid.

Если params задано, переберите его метод items и используйте полученные пары (key, value) для установки дополнительных параметров в заголовке Content-Type.

Если headers задано и является списком строк вида headername: headervalue или списком объектов header (отличающихся от строк наличием атрибута name), добавьте заголовки к msg.