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 (для всех остальных типов, не являющихся составными). Если метод вызван для multipart, возникает исключение KeyError. Если часть имеет тип 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 задает тип равным message, а подтип — равным subtype, если он указан, или rfc822, если не указан. Если subtype равен partial, возникает ошибка (для создания частей message/partial следует использовать объекты bytes).

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

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

• Для объектов str, если cte не задан, с помощью эвристик выбирается наиболее компактное кодирование. Перед кодированием для нормализации всех границ строк используется str.splitlines(), чтобы каждая строка полезной нагрузки завершалась разделителем строк, заданным свойством linesep текущей политики (даже если исходная строка не оканчивалась разделителем).
• Для объектов bytes, если cte не задан, используется base64; упомянутое выше преобразование символов новой строки не выполняется.
• Для объектов EmailMessage согласно RFC 2046 возникает ошибка, если для subtype rfc822 запрошено cte quoted-printable или base64, а для subtype external-body — любое cte, кроме 7bit. Для message/rfc822, если cte не указан, используется 8bit. Для всех остальных значений 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.

Сноски