Документация Python неофициальный перевод
Содержание страницы

email.contentmanager: управление MIME-содержимымemail.contentmanager: Managing MIME Content

Исходный код: Lib/email/contentmanager.py

Добавлено в версии 3.6: [1]

class email.contentmanager.ContentManager

Базовый класс для диспетчеров содержимого. Предоставляет стандартные механизмы регистрации для преобразователей между MIME-содержимым и другими представлениями, а также методы отправки get_content и set_content.

get_content(msg, *args, **kw)

Находит функцию-обработчик на основе mimetype сообщения msg (см. следующий абзац), вызывает её, передавая все аргументы, и возвращает результат вызова. Ожидается, что обработчик извлечёт полезную нагрузку из msg и вернёт объект, который кодирует информацию об извлечённых данных.

Для поиска обработчика ищутся следующие ключи в реестре; поиск прекращается при первом найденном:

  • строка, представляющая полный 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__).

  • qualname типа (typ.__qualname__)

  • name типа (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().

Экземпляры диспетчера содержимогоContent Manager Instances

В настоящее время пакет 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 при вызове для 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 не установлен, использует эвристику для определения наиболее компактной кодировки. Перед кодированием str.splitlines() используется для нормализации всех границ строк, гарантируя, что каждая строка содержимого завершается свойством linesep текущей политики (даже если исходная строка не заканчивалась им).

  • Для объектов bytes, если cte не установлен, он считается равным base64, и вышеупомянутое преобразование новых строк не выполняется.

  • Для 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.

Сноски