`email.contentmanager.md`

107 строк · 14.6 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.15/library/email.contentmanager.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `email.contentmanager`: управление MIME-содержимым89**Исходный код:** [Lib/email/contentmanager.py](https://python-all.ru/src/3.15/Lib/email/contentmanager.py)1011---1213Добавлено в версии 3.6: [\[1\]](https://python-all.ru/3.15/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.15/library/exceptions.html#KeyError) для полного MIME-типа.3031#### `set_content(msg, obj, *args, **kw)`3233Если `maintype` равно `multipart`, возбуждается [`TypeError`](https://python-all.ru/3.15/library/exceptions.html#TypeError); в противном случае находится функция-обработчик на основе типа *obj* (см. следующий абзац), вызывается [`clear_content()`](https://python-all.ru/3.15/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`](https://python-all.ru/3.15/reference/datamodel.html#type.__qualname__) типа (`typ.__qualname__`)40- [`name`](https://python-all.ru/3.15/reference/datamodel.html#type.__name__) типа (`typ.__name__`).4142Если ни одно из перечисленных выше не подошло, все эти проверки повторяются для каждого типа из [MRO](https://python-all.ru/3.15/glossary.html#term-MRO) ([`typ.__mro__`](https://python-all.ru/3.15/reference/datamodel.html#type.__mro__)). Наконец, если ни по одному другому ключу не найден обработчик, проверяется обработчик для ключа `None`. Если обработчика для `None` нет, возбуждается [`KeyError`](https://python-all.ru/3.15/library/exceptions.html#KeyError) для полного квалифицированного имени типа.4344Также добавляется заголовок *MIME-Version*, если он отсутствует (см. также [`MIMEPart`](https://python-all.ru/3.15/library/email.message.html#email.message.MIMEPart)).4546#### `add_get_handler(key, handler)`4748Регистрирует функцию *handler* как обработчик для *key*. Возможные значения *key* описаны в [`get_content()`](https://python-all.ru/3.15/library/email.contentmanager.html#email.contentmanager.get_content).4950#### `add_set_handler(typekey, handler)`5152Регистрирует *handler* как функцию, вызываемую, когда объект типа, соответствующего *typekey*, передаётся в [`set_content()`](https://python-all.ru/3.15/library/email.contentmanager.html#email.contentmanager.set_content). Возможные значения *typekey* описаны в `set_content()`.5354## Экземпляры диспетчера содержимого5556В настоящее время пакет email предоставляет только один конкретный диспетчер содержимого – [`raw_data_manager`](https://python-all.ru/3.15/library/email.contentmanager.html#email.contentmanager.raw_data_manager), хотя в будущем может быть добавлено больше. `raw_data_manager` – это [`content_manager`](https://python-all.ru/3.15/library/email.policy.html#email.policy.EmailPolicy.content_manager), предоставляемый [`EmailPolicy`](https://python-all.ru/3.15/library/email.policy.html#email.policy.EmailPolicy) и его производными.5758#### `email.contentmanager.raw_data_manager`5960Этот диспетчер содержимого предоставляет лишь минимальный интерфейс в дополнение к тому, что предоставляет сам [`Message`](https://python-all.ru/3.15/library/email.compat32-message.html#email.message.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.15/library/email.message.html#email.message.EmailMessage) (для частей `message/rfc822`) или объект `bytes` (для всех других не multipart-типов). Вызывает [`KeyError`](https://python-all.ru/3.15/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.15/library/exceptions.html#TypeError), если они не указаны.78- Для объектов [`EmailMessage`](https://python-all.ru/3.15/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.15/library/exceptions.html#ValueError).8384- Для объектов `str`, если *cte* не установлен, использует эвристику для определения наиболее компактной кодировки. Перед кодированием [`str.splitlines()`](https://python-all.ru/3.15/library/stdtypes.html#str.splitlines) используется для нормализации всех границ строк, гарантируя, что каждая строка содержимого завершается свойством [`linesep`](https://python-all.ru/3.15/library/email.policy.html#email.policy.Policy.linesep) текущей политики (даже если исходная строка не заканчивалась им).85- Для объектов `bytes`, если *cte* не установлен, он считается равным base64, и вышеупомянутое преобразование новых строк не выполняется.86- Для [`EmailMessage`](https://python-all.ru/3.15/library/email.message.html#email.message.EmailMessage), согласно [**RFC 2046**](https://python-all.ru/3.15/library/email.contentmanager.html), вызывает ошибку, если запрашивается *cte* равный `quoted-printable` или `base64` для *subtype* `rfc822`, и для любого *cte*, отличного от `7bit`, для *subtype* `external-body`. Для `message/rfc822` использует `8bit`, если *cte* не указан. Для всех остальных значений *subtype* использует `7bit`.8788> **Примечание**89>90> Значение *cte*, равное `binary`, пока на самом деле не работает корректно. Объект `EmailMessage`, измененный с помощью `set_content`, корректен, но [`BytesGenerator`](https://python-all.ru/3.15/library/email.generator.html#email.generator.BytesGenerator) не сериализует его правильно.9192Если установлен *disposition*, использует его как значение заголовка *Content-Disposition*. Если он не указан, но указан *filename*, добавляет заголовок со значением `attachment`. Если *disposition* не указан и *filename* также не указан, заголовок не добавляется. Единственными допустимыми значениями для *disposition* являются `attachment` и `inline`.9394Если указан *filename*, использует его как значение параметра `filename` заголовка *Content-Disposition*.9596Если указан *cid*, добавляет заголовок *Content-ID* со значением *cid*.9798Если указан *params*, перебирает его метод `items` и использует полученные пары `(key, value)` для установки дополнительных параметров заголовка *Content-Type*.99100Если указан *headers* и это список строк вида `headername: headervalue` или список объектов `header` (отличаются от строк наличием атрибута `name`), добавляет заголовки в *msg*.101102Сноски103104\[[1](https://python-all.ru/3.15/library/email.contentmanager.html#id1)\]105106Изначально добавлено в версии 3.4 как [временный модуль](https://python-all.ru/3.15/glossary.html#term-provisional-package)107