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

Добавлено в версии 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__).
  • полное имя типа (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().

Экземпляры менеджера контента

В настоящее время пакет 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 объекта (для всех других не составных типов). Вызывается KeyError, если вызывается multipart. Если часть является частью 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 задаёт для основного типа значение 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. Если ввод не может быть закодирован в указанной кодировке (например, указание 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 как предварительный модуль.