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 і це список рядків у формі назва заголовка: значення заголовка або список об’єктів заголовка (відрізняються від рядків наявністю атрибута назва), додайте заголовки на повідомлення.

Виноски