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 и возвращает an, который кодирует информацию о извлеченных данных.

Чтобы найти обработчик, найдите в реестре следующие разделы, остановившись на первом найденном:

  • строка, представляющий полный тип 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 на текстовой части будет возвращает a unicode строка без приложения, нуждающегося в ручном декодировании, 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 используйте указанный maintype и subtype, или поднимите TypeError, если они не определены.
  • Для объектов EmailMessage, устанавливает maintype в 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, поднимают ошибку, если cte quoted-printable или base64 запрошенный для subtype rfc822, и для какого-либо cte кроме 7bit для subtype external-body. Для message/rfc822 используйте 8bit, если cte не указан. Для всего другого значения subtype используйте 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 как предварительный пакет