email.contentmanager: Managing MIME Content

Kod źródłowy: Lib/email/contentmanager.py

Added in version 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. Prior to encoding, str.splitlines() is used to normalize all line boundaries, ensuring that each line of the payload is terminated by the current policy's linesep property (even if the original string did not end with one).

  • For bytes objects, cte is taken to be base64 if not set, and the aforementioned newline translation is not performed.

  • Для EmailMessage, відповідно до RFC 2046, викликати помилку, якщо cte quoted-printable або base64 запитується для підтипу rfc822 і для будь-якого cte, крім 7bit для підтипу external-body. Для message/rfc822 використовуйте 8bit, якщо cte не вказано. Для всіх інших значень subtype використовуйте 7bit.

Catatan

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

Catatan kaki