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

Примеры менеджеров содержимого

В настоящее время пакет 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, <'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 как пробный модуль