email.header: Internationalized headers

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

Цей модуль є частиною застарілого (Compat32) API електронної пошти. У поточному API кодування та декодування заголовків обробляється прозоро за допомогою словникового API класу EmailMessage. На додаток до використання у застарілому коді, цей модуль може бути корисним у програмах, яким потрібно повністю контролювати набори символів, що використовуються під час кодування заголовків.

Решта тексту в цьому розділі є оригінальною документацією модуля.

RFC 2822 — це базовий стандарт, який описує формат електронних повідомлень. Він походить від старішого стандарту RFC 822, який набув широкого використання в той час, коли більшість електронних листів складалися лише з символів ASCII. RFC 2822 — це специфікація, написана за умови, що електронна пошта містить лише 7-бітні символи ASCII.

Звичайно, оскільки електронна пошта була розгорнута в усьому світі, вона стала інтернаціоналізованою, так що набори символів для певної мови тепер можна використовувати в електронних повідомленнях. Базовий стандарт все ще вимагає, щоб повідомлення електронної пошти передавалися лише з використанням 7-бітових символів ASCII, тому було написано безліч RFC, які описують, як кодувати електронну пошту, що містить символи, відмінні від ASCII, у RFC 2822-сумісний формат. Ці RFC включають RFC 2045, RFC 2046, RFC 2047 і RFC 2231. Пакет email підтримує ці стандарти у своїх модулях email.header і email.charset.

Якщо ви хочете включити символи, відмінні від ASCII, у заголовки електронної пошти, скажімо, у поля Subject або To, вам слід використовувати клас Header і призначити поле в Message до екземпляра Header замість використання рядка для значення заголовка. Імпортуйте клас Header з модуля email.header. Наприклад:

>>> from email.message import Message
>>> from email.header import Header
>>> msg = Message()
>>> h = Header('p\xf6stal', 'iso-8859-1')
>>> msg['Subject'] = h
>>> msg.as_string()
'Subject: =?iso-8859-1?q?p=F6stal?=\n\n'

Зверніть увагу, як ми хотіли, щоб поле Subject містило символ не ASCII? Ми зробили це, створивши екземпляр Header і передавши набір символів, у якому було закодовано рядок байтів. Коли наступний екземпляр Message було зведено, Subject було правильно закодовано RFC 2047. Програми читання пошти з підтримкою MIME відображатимуть цей заголовок за допомогою вбудованого символу ISO-8859-1.

Ось опис класу Header:

class email.header.Header(s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict')

Створіть MIME-сумісний заголовок, який може містити рядки з різними наборами символів.

Необов’язковий параметр s — початкове значення заголовка. Якщо None (за замовчуванням), початкове значення заголовка не встановлено. Ви можете пізніше додати до заголовка за допомогою викликів методу append(). s може бути екземпляром bytes або str, але див. документацію append() щодо семантики.

Додатковий charset служить двом цілям: він має те саме значення, що й аргумент charset для методу append(). Він також встановлює стандартний набір символів для всіх наступних викликів append(), які пропускають аргумент charset. Якщо charset не надано в конструкторі (за замовчуванням), набір символів us-ascii використовується і як початковий набір символів s, і як типовий для наступних викликів append().

The maximum line length can be specified explicitly via maxlinelen. For splitting the first line to a shorter value (to account for the field header which isn’t included in s, e.g. Subject) pass in the name of the field in header_name. The default maxlinelen is 76, and the default value for header_name is None, meaning it is not taken into account for the first line of a long, split header.

Необов’язковий continuation_ws має бути RFC 2822-сумісним згортаним пробілом і зазвичай є пробілом або символом жорсткої табуляції. Цей символ буде додано до рядків продовження. continuation_ws за замовчуванням використовує один пробіл.

Необов’язкові помилки передаються безпосередньо до методу append().

append(s, charset=None, errors='strict')

Додайте рядок s до заголовка MIME.

Додатковий charset, якщо він наданий, має бути екземпляром Charset (див. email.charset) або назвою набору символів, який буде перетворено на Charset екземпляр. Значення None (за замовчуванням) означає, що використовується набір символів, наданий у конструкторі.

s може бути екземпляром bytes або str. Якщо це екземпляр bytes, тоді charset є кодуванням цього рядка байтів, і UnicodeError буде викликано, якщо рядок не можна декодувати за допомогою цього набору символів.

Якщо s є екземпляром str, тоді charset є підказкою, що визначає набір символів у рядку.

У будь-якому випадку, під час створення RFC 2822-сумісного заголовка з використанням правил RFC 2047 рядок кодуватиметься за допомогою вихідного кодека набору символів. Якщо рядок неможливо закодувати за допомогою вихідного кодека, виникне UnicodeError.

Необов’язковий errors передається як аргумент errors виклику декодування, якщо s є рядком байтів.

encode(splitchars=';, \t', maxlinelen=None, linesep='\n')

Закодуйте заголовок повідомлення у RFC-сумісний формат, можливо, обгортаючи довгі рядки та інкапсулюючи частини, що не належать до ASCII, у кодування base64 або кодування в лапках.

Необов’язковий splitchars — це рядок, що містить символи, яким слід надати додаткову вагу за допомогою алгоритму розбиття під час звичайного обгортання заголовка. Це є дуже грубою підтримкою «синтаксичних розривів вищого рівня» RFC 2822: крапки розділення, яким передує символ розділення, є кращими під час поділу рядка, а символи мають перевагу в тому порядку, в якому вони з’являються в рядку. Пробіл і табуляція можуть бути включені в рядок, щоб вказати, чи слід надавати перевагу одному над іншим як точці розділення, коли інші символи розділення не з’являються в рядку, що розділяється. Splitchars не впливає на рядки, закодовані RFC 2047.

maxlinelen, якщо задано, замінює значення екземпляра для максимальної довжини рядка.

linesep визначає символи, які використовуються для розділення рядків згорнутого заголовка. За замовчуванням це найбільш корисне значення для коду програми Python (\n), але \r\n можна вказати, щоб створити заголовки з RFC-сумісними роздільниками рядків.

Змінено в версії 3.2: Додано аргумент linesep.

Клас Header також надає ряд методів для підтримки стандартних операторів і вбудованих функцій.

__str__()

Повертає наближення Header у вигляді рядка, використовуючи необмежену довжину рядка. Усі фрагменти перетворюються на юнікод із використанням зазначеного кодування та об’єднуються належним чином. Будь-які фрагменти з кодуванням 'unknown-8bit' декодуються як ASCII за допомогою обробника помилок 'replace'.

Змінено в версії 3.2: Додано обробку набору символів 'unknown-8bit''.

__eq__(other)

Цей метод дозволяє порівнювати два екземпляри Header на предмет рівності.

__ne__(other)

Цей метод дозволяє порівнювати два екземпляри Header на предмет нерівності.

Модуль email.header також надає такі зручні функції.

email.header.decode_header(header)

Декодуйте значення заголовка повідомлення без перетворення набору символів. Значення заголовка знаходиться в заголовку.

Ця функція повертає список пар (decoded_string, charset), що містить кожну з декодованих частин заголовка. charset має значення None для незакодованих частин заголовка, інакше рядок у нижньому регістрі, що містить назву набору символів, указаного в закодованому рядку.

Ось приклад:

>>> from email.header import decode_header
>>> decode_header('=?iso-8859-1?q?p=F6stal?=')
[(b'p\xf6stal', 'iso-8859-1')]
email.header.make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')

Створіть екземпляр Header із послідовності пар, які повертає decode_header().

decode_header() приймає рядок значення заголовка та повертає послідовність пар у форматі (decoded_string, charset), де charset — назва набору символів.

Ця функція бере одну з цих пар і повертає екземпляр Header. Необов’язкові maxlinelen, header_name і continuation_ws такі, як у конструкторі Header.