# `email.header`: Internationalized headers

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

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

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

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

Of course, as email has been deployed worldwide, it has become internationalized, such that language specific character sets can now be used in email messages. The base standard still requires email messages to be transferred using only 7-bit ASCII characters, so a slew of RFCs have been written describing how to encode email containing non-ASCII characters into RFC 2822-compliant format. These RFCs include RFC 2045, RFC 2046, RFC 2047, and RFC 2231. The `email` package supports these standards in its `email.header` and `email.charset` modules.

If you want to include non-ASCII characters in your email headers, say in the Subject or To fields, you should use the `Header` class and assign the field in the `Message` object to an instance of `Header` instead of using a string for the header value. Import the `Header` class from the `email.header` module. For example:

    >>> 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 78, 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` на предмет нерівності.

The `email.header` module also provides the following convenient functions.

email.header.decode_header(header)

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

  For historical reasons, this function may return either:

  1. A list of pairs containing each of the decoded parts of the header, `(decoded_bytes, charset)`, where decoded_bytes is always an instance of `bytes`, and charset is either:

     > - A lower case string containing the name of the character set specified.

     > - `None` for non-encoded parts of the header.

  2. A list of length 1 containing a pair `(string, None)`, where string is always an instance of `str`.

  An `email.errors.HeaderParseError` may be raised when certain decoding errors occur (e.g. a base64 decoding exception).

  Here are examples:

      >>> from email.header import decode_header
      >>> decode_header('=?iso-8859-1?q?p=F6stal?=')
      [(b'p\xf6stal', 'iso-8859-1')]
      >>> decode_header('unencoded_string')
      [('unencoded_string', None)]
      >>> decode_header('bar =?utf-8?B?ZsOzbw==?=')
      [(b'bar ', None), (b'f\xc3\xb3o', 'utf-8')]

  Примітка

  This function exists for backwards compatibility only. For new code, we recommend using `email.headerregistry.HeaderRegistry`.

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`.

  Примітка

  This function exists for backwards compatibility only, and is not recommended for use in new code.