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 задаёт maintype равным message, а subtype — 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.

Сноски