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

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

Добавлено в версии 3.6: 1

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__).

  • квалификационное имя типа (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().

Экземпляры контент-менеджера

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

email.contentmanager.raw_data_manager

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

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

Возвращает полезную нагрузку части в виде строки (для частей text), объекта EmailMessage (для частей message/rfc822) или объекта bytes (для всех других типов, не являющихся многочастными). Вызывает ошибку KeyError, если вызывается на multipart. Если часть является частью text и указано errors, используйте его в качестве обработчика ошибок при декодировании полезной нагрузки в юникод. По умолчанию обработчиком ошибок является 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, <'EmailMessage'>, cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)

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

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

  • Для str установите MIME maintype в text и установите подтип в subtype, если он указан, или plain, если он не указан.

  • Для bytes используйте указанные основной тип и подтип, или вызовите ошибку TypeError, если они не указаны.

  • Для объектов EmailMessage установите основной тип в message, а подтип - в subtype, если он указан, или в rfc822, если не указан. Если subtype равен partial, произойдет ошибка (объекты bytes должны использоваться для построения частей message/partial).

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

Если установлено значение cte, кодируйте полезную нагрузку, используя указанную кодировку передачи содержимого, и установите в заголовке Content-Transfer-Encoding это значение. Возможные значения для cte: quoted-printable, base64, 7bit, 8bit и binary. Если входные данные не могут быть закодированы в указанной кодировке (например, указав cte 7bit для входных данных, содержащих значения, отличные от ASCII), следует выдать ошибку ValueError.

  • Для объектов str, если cte не задан, используйте эвристику для определения наиболее компактного кодирования.

  • Для EmailMessage, в соответствии с RFC 2046, вызывайте ошибку, если для подтипа quoted-printable запрашивается cte из base64 или rfc822, и для любого cte, отличного от 7bit для подтипа external-body. Для message/rfc822 используйте 8bit, если cte не указан. Для всех остальных значений подтипа используйте 7bit.

Примечание

Объект cte из binary еще не работает корректно. Объект EmailMessage, модифицированный set_content, корректен, но BytesGenerator не сериализует его правильно.

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

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

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

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

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

Сноски

1

Первоначально был добавлен в 3.4 как provisional module.

email.headerregistry: Объекты пользовательских заголовков
email: Примеры
Вернуться на верх