`email.contentmanager.md`

106 строк · 13.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.8/library/email.contentmanager.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`email.contentmanager`](https://python-all.ru/3.8/library/email.contentmanager.html#module-email.contentmanager): управление MIME-содержимым89**Исходный код:** [Lib/email/contentmanager.py](https://python-all.ru/src/3.8/Lib/email/contentmanager.py)1011---1213Новое в версии 3.6: [1](https://python-all.ru/3.8/library/email.contentmanager.html#id2)1415#### `class email.contentmanager.ContentManager`1617Базовый класс для диспетчеров содержимого. Предоставляет стандартные механизмы регистрации для преобразователей между MIME-содержимым и другими представлениями, а также методы отправки `get_content` и `set_content`.1819#### `get_content(msg, *args, **kw)`2021Находит функцию-обработчик на основе `mimetype` сообщения *msg* (см. следующий абзац), вызывает её, передавая все аргументы, и возвращает результат вызова. Ожидается, что обработчик извлечёт полезную нагрузку из *msg* и вернёт объект, который кодирует информацию об извлечённых данных.2223Для поиска обработчика ищутся следующие ключи в реестре; поиск прекращается при первом найденном:2425> - строка, представляющая полный MIME-тип (`maintype/subtype`)26> - строка, представляющая `maintype`27> - пустая строка2829Если ни один из этих ключей не дал обработчика, возбуждается [`KeyError`](https://python-all.ru/3.8/library/exceptions.html#KeyError) для полного MIME-типа.3031#### `set_content(msg, obj, *args, **kw)`3233Если `maintype` равно `multipart`, возбуждается [`TypeError`](https://python-all.ru/3.8/library/exceptions.html#TypeError); в противном случае находится функция-обработчик на основе типа *obj* (см. следующий абзац), вызывается [`clear_content()`](https://python-all.ru/3.8/library/email.message.html#email.message.EmailMessage.clear_content) на *msg* и вызывается функция-обработчик с передачей всех аргументов. Ожидается, что обработчик преобразует и сохранит *obj* в *msg*, возможно, внося также другие изменения в *msg*, например, добавляя различные MIME-заголовки для кодирования информации, необходимой для интерпретации сохранённых данных.3435Для поиска обработчика получается тип *obj* (`typ = type(obj)`), и в реестре ищутся следующие ключи; поиск прекращается при первом найденном:3637> - сам тип (`typ`)38> - полное квалифицированное имя типа (`typ.__module__ + '.' + typ.__qualname__`).39> - qualname типа (`typ.__qualname__`)40> - имя типа (`typ.__name__`).4142Если ни одно из вышеперечисленных не совпадает, повторить все проверки выше для каждого из типов в [MRO](https://python-all.ru/3.8/glossary.html#term-mro) (`typ.__mro__`). Наконец, если ни один другой ключ не даёт обработчика, проверить наличие обработчика для ключа `None`. Если обработчика для `None` нет, вызвать [`KeyError`](https://python-all.ru/3.8/library/exceptions.html#KeyError) для полного имени типа.4344Также добавляется заголовок *MIME-Version*, если он отсутствует (см. также [`MIMEPart`](https://python-all.ru/3.8/library/email.message.html#email.message.MIMEPart)).4546#### `add_get_handler(key, handler)`4748Регистрирует функцию *handler* как обработчик для *key*. Возможные значения *key* описаны в [`get_content()`](https://python-all.ru/3.8/library/email.contentmanager.html#email.contentmanager.get_content).4950#### `add_set_handler(typekey, handler)`5152Регистрирует *handler* как функцию, вызываемую, когда объект типа, соответствующего *typekey*, передаётся в [`set_content()`](https://python-all.ru/3.8/library/email.contentmanager.html#email.contentmanager.set_content). Возможные значения *typekey* описаны в [`set_content()`](https://python-all.ru/3.8/library/email.contentmanager.html#email.contentmanager.set_content).5354## Экземпляры диспетчера содержимого5556В настоящее время пакет email предоставляет только один конкретный диспетчер содержимого – [`raw_data_manager`](https://python-all.ru/3.8/library/email.contentmanager.html#email.contentmanager.raw_data_manager), хотя в будущем может быть добавлено больше. [`raw_data_manager`](https://python-all.ru/3.8/library/email.contentmanager.html#email.contentmanager.raw_data_manager) – это [`content_manager`](https://python-all.ru/3.8/library/email.policy.html#email.policy.EmailPolicy.content_manager), предоставляемый [`EmailPolicy`](https://python-all.ru/3.8/library/email.policy.html#email.policy.EmailPolicy) и его производными.5758#### `email.contentmanager.raw_data_manager`5960Этот диспетчер содержимого предоставляет лишь минимальный интерфейс в дополнение к тому, что предоставляет сам [`Message`](https://python-all.ru/3.8/library/email.compat32-message.html#email.message.Message): он работает только с текстом, необработанными байтовыми строками и объектами [`Message`](https://python-all.ru/3.8/library/email.compat32-message.html#email.message.Message). Тем не менее, он даёт значительные преимущества по сравнению с базовым API: `get_content` для текстовой части возвращает строку Unicode без необходимости ручного декодирования, `set_content` предоставляет богатый набор опций для управления заголовками, добавляемыми к части, и управления кодировкой передачи содержимого, а также позволяет использовать различные методы `add_`, упрощая создание многокомпонентных сообщений.6162#### `email.contentmanager.get_content(msg, errors='replace')`6364Возвращает содержимое части как строку (для частей `text`), объект [`EmailMessage`](https://python-all.ru/3.8/library/email.message.html#email.message.EmailMessage) (для частей `message/rfc822`) или объект `bytes` (для всех других не multipart-типов). Вызывает [`KeyError`](https://python-all.ru/3.8/library/exceptions.html#KeyError) при вызове для `multipart`. Если часть является `text` и указан *errors*, использует его как обработчик ошибок при декодировании содержимого в unicode. Обработчик ошибок по умолчанию – `replace`.6566#### `email.contentmanager.set_content(msg, <'str'>, subtype="plain", charset='utf-8', cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)`6768#### `email.contentmanager.set_content(msg, <'bytes'>, maintype, subtype, cte="base64", disposition=None, filename=None, cid=None, params=None, headers=None)`6970#### `email.contentmanager.set_content(msg, <'EmailMessage'>, cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)`7172Добавляет заголовки и содержимое в *msg*:7374Добавляет заголовок *Content-Type* со значением `maintype/subtype`.7576> - Для `str` устанавливает MIME `maintype` в `text`, а подтип – в *subtype*, если он указан, или в `plain`, если нет.77> - Для `bytes` использует указанные *maintype* и *subtype*, или вызывает [`TypeError`](https://python-all.ru/3.8/library/exceptions.html#TypeError), если они не указаны.78> - Для объектов [`EmailMessage`](https://python-all.ru/3.8/library/email.message.html#email.message.EmailMessage) устанавливает maintype в `message`, а подтип – в *subtype*, если он указан, или в `rfc822`, если нет. Если *subtype* равен `partial`, вызывает ошибку (объекты `bytes` должны использоваться для создания частей `message/partial`).7980Если указан *charset* (действителен только для `str`), кодирует строку в байты с использованием указанной кодировки. По умолчанию используется `utf-8`. Если указанный *charset* является известным псевдонимом стандартного имени кодировки MIME, использует стандартную кодировку.8182Если установлен *cte*, кодирует содержимое с использованием указанной кодировки передачи содержимого и устанавливает заголовок *Content-Transfer-Encoding* в это значение. Возможные значения для *cte*: `quoted-printable`, `base64`, `7bit`, `8bit` и `binary`. Если входные данные невозможно закодировать в указанной кодировке (например, указание *cte* равным `7bit` для входных данных, содержащих не-ASCII значения), вызывает [`ValueError`](https://python-all.ru/3.8/library/exceptions.html#ValueError).8384> - Для объектов `str`, если *cte* не задан, использовать эвристику для определения наиболее компактной кодировки.85> - Для [`EmailMessage`](https://python-all.ru/3.8/library/email.message.html#email.message.EmailMessage), согласно [**RFC 2046**](https://python-all.ru/3.8/library/email.contentmanager.html), вызывает ошибку, если запрашивается *cte* равный `quoted-printable` или `base64` для *subtype* `rfc822`, и для любого *cte*, отличного от `7bit`, для *subtype* `external-body`. Для `message/rfc822` использует `8bit`, если *cte* не указан. Для всех остальных значений *subtype* использует `7bit`.8687> **Примечание**88>89> Значение *cte*, равное `binary`, пока на самом деле не работает корректно. Объект `EmailMessage`, измененный с помощью `set_content`, корректен, но [`BytesGenerator`](https://python-all.ru/3.8/library/email.generator.html#email.generator.BytesGenerator) не сериализует его правильно.9091Если установлен *disposition*, использует его как значение заголовка *Content-Disposition*. Если он не указан, но указан *filename*, добавляет заголовок со значением `attachment`. Если *disposition* не указан и *filename* также не указан, заголовок не добавляется. Единственными допустимыми значениями для *disposition* являются `attachment` и `inline`.9293Если указан *filename*, использует его как значение параметра `filename` заголовка *Content-Disposition*.9495Если указан *cid*, добавляет заголовок *Content-ID* со значением *cid*.9697Если указан *params*, перебирает его метод `items` и использует полученные пары `(key, value)` для установки дополнительных параметров заголовка *Content-Type*.9899Если указан *headers* и это список строк вида `headername: headervalue` или список объектов `header` (отличаются от строк наличием атрибута `name`), добавляет заголовки в *msg*.100101Сноски102103**[1](https://python-all.ru/3.8/library/email.contentmanager.html#id1)**104105Изначально добавлено в версии 3.4 как [временный модуль](https://python-all.ru/3.8/glossary.html#term-provisional-package)106