Документация 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__)

  • имя типа (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 не задан, использовать эвристику для определения наиболее компактной кодировки.

  • Для 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 как временный модуль