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 типа.- строка, представляющая полный 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
устанавливает для MIMEmaintype
значение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
запрашивается для subtyperfc822
, и для любого cte, отличного от7bit
для subtypeexternal-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 как предварительный модуль. |