email.contentmanager: Управление MIME-контентом

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

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().

Примеры менеджеров контента

В настоящее время пакет 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, установите 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 как временный модуль