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

Источник: Lib/email/contentmanager.py

Added in version 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 в качестве функции, которая будет вызываться, когда в set_content() будет передан объект типа, соответствующего typekey. Возможные значения 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 (для всех остальных типов, не являющихся многокомпонентными). При вызове на multipart поднимается сообщение KeyError. Если часть является частью 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, а подтип - в подтип, если он указан, или в rfc822, если не указан. Если подтип равен 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, вызывайте ошибку, если для подтипа rfc822 запрашивается cte из quoted-printable или base64, и для любого cte, отличного от 7bit, для подтипа external-body. Если cte не указан, то для подтипа message/rfc822 используйте 8bit. Для всех остальных значений подтипа используйте 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.

Сноски