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

Экземпляры менеджера содержимого

В настоящее время пакет email предоставляет только один конкретный менеджер содержимого — 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). При вызове для 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 использует указанные maintype и subtype либо возбуждает исключение TypeError, если они не указаны.
• Для объектов EmailMessage задаёт maintype равным 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. Если 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.

Сноски