# `email.contentmanager`: Managing MIME Content

Вихідний код: Lib/email/contentmanager.py

Нове в версії 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__`).

    - the type’s qualname (`typ.__qualname__`)

    - the type’s name (`typ.__name__`).

    If none of the above match, repeat all of the checks above for each of the types in the MRO (`typ.__mro__`). Finally, if no other key yields a handler, check for a handler for the key `None`. If there is no handler for `None`, raise a `KeyError` for the fully qualified name of the type.

    Також додайте заголовок MIME-Version, якщо його немає (див. також `MIMEPart`).

  add_get_handler(key, handler)

    Запишіть функцію обробник як обробник для ключа. Можливі значення key див. у `get_content()`.

  add_set_handler(typekey, handler)

    Запишіть обробник як функцію для виклику, коли об’єкт типу, який відповідає typekey, передається до `set_content()`. Можливі значення typekey див. у `set_content()`.

## Примірники Content Manager

Наразі пакет електронної пошти містить лише один конкретний менеджер вмісту, `raw_data_manager`, хоча в майбутньому може бути додано більше. `raw_data_manager` — це `content_manager`, наданий `EmailPolicy` та його похідними.

email.contentmanager.raw_data_manager

  Цей менеджер вмісту надає лише мінімальний інтерфейс, окрім того, який надає сам `Message`: він має справу лише з текстом, необробленими рядками байтів та об’єктами `Message`. Тим не менш, він надає значні переваги порівняно з базовим API: `get_content` у текстовій частині поверне рядок Unicode без необхідності програми вручну декодувати його, `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)

    Додайте заголовки та корисне навантаження до повідомлення:

    Додайте заголовок Content-Type зі значенням `maintype/subtype`.

    - Для `str` встановіть `maintype` MIME на `text` і встановіть підтип на subtype, якщо він указаний, або `plain`, якщо він не вказано.

    - Для `bytes` використовуйте вказані maintype і subtype або викликайте `TypeError`, якщо вони не вказані.

    - Для об’єктів `EmailMessage` встановіть основний тип як `message`, а для підтипу встановіть subtype, якщо він указаний, або `rfc822`, якщо його немає. Якщо subtype має значення `partial`, виникає помилка (об’єкти `bytes` повинні використовуватися для створення частин `message/partial`).

    Якщо надано charset (який дійсний лише для `str`), закодуйте рядок у байти за допомогою вказаного набору символів. Типовим є `utf-8`. Якщо вказаний набір символів є відомим псевдонімом для назви стандартного набору кодів MIME, замість цього використовуйте стандартний набір символів.

    Якщо встановлено cte, закодуйте корисне навантаження, використовуючи вказане кодування передачі вмісту, і встановіть це значення для заголовка Content-Transfer-Encoding. Можливі значення для cte: `quoted-printable`, `base64`, `7bit`, `8bit` і `binary`. Якщо вхідні дані не можна закодувати у вказаному кодуванні (наприклад, вказавши cte `7bit` для вхідних даних, які містять значення, відмінні від ASCII), викликайте `ValueError`.

    - For `str` objects, if cte is not set use heuristics to determine the most compact encoding.

    - Для `EmailMessage`, відповідно до RFC 2046, викликати помилку, якщо cte `quoted-printable` або `base64` запитується для підтипу `rfc822` і для будь-якого cte, крім `7bit` для підтипу `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 і це список рядків у формі `назва заголовка: значення заголовка` або список об’єктів `заголовка` (відрізняються від рядків наявністю атрибута `назва`), додайте заголовки на повідомлення.

Виноски

[1]

Спочатку додано в 3.4 як проміжний модуль