This document is for an old version of Python that is no longer supported. You should upgrade, and read the Python documentation for the current stable release.

# `email.charset`: Representing character sets

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

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

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

Цей модуль надає клас `Charset` для представлення наборів символів і перетворення наборів символів у повідомленнях електронної пошти, а також реєстр наборів символів і декілька зручних методів для маніпулювання цим реєстром. Екземпляри `Charset` використовуються в кількох інших модулях у пакеті `email`.

Імпортуйте цей клас із модуля `email.charset`.

class `email.charset.``Charset`(input_charset=DEFAULT_CHARSET)

  Зіставте набори символів із властивостями електронної пошти.

  Цей клас надає інформацію про вимоги до електронної пошти для певного набору символів. Він також надає зручні процедури для перетворення між наборами символів, враховуючи наявність застосовних кодеків. Маючи набір символів, він докладе всіх зусиль, щоб надати інформацію про те, як використовувати цей набір символів у повідомленні електронної пошти відповідно до RFC.

  Певні набори символів мають бути закодовані за допомогою citaty-printable або base64, якщо вони використовуються в заголовках або тілах електронних листів. Певні набори символів потрібно відразу конвертувати, і їх заборонено використовувати в електронній пошті.

  Додатковий input_charset, як описано нижче; це завжди примусово до малого регістру. Після нормалізації псевдоніма він також використовується як пошук у реєстрі наборів символів, щоб дізнатися кодування заголовка, кодування основного тексту та кодек перетворення виводу, який буде використано для набору символів. Наприклад, якщо input_charset дорівнює `iso-8859-1`, тоді заголовки та тіла кодуватимуться з використанням параметра «quote-printable», і кодек для перетворення виводу не потрібен. Якщо input_charset має значення `euc-jp`, тоді заголовки будуть закодовані за допомогою base64, тіла не будуть закодовані, але вихідний текст буде перетворено з набору символів `euc-jp` на `iso- 2022-jp` набір символів.

  Екземпляри `Charset` мають такі атрибути даних:

  `input_charset`

    Зазначений початковий набір символів. Загальні псевдоніми перетворюються на офіційні імена електронної пошти (наприклад, `latin_1` перетворюється на `iso-8859-1`). За замовчуванням 7-бітний `us-ascii`.

  `header_encoding`

    If the character set must be encoded before it can be used in an email header, this attribute will be set to `charset.QP` (for quoted-printable), `charset.BASE64` (for base64 encoding), or `charset.SHORTEST` for the shortest of QP or BASE64 encoding. Otherwise, it will be `None`.

  `body_encoding`

    Same as header_encoding, but describes the encoding for the mail message’s body, which indeed may be different than the header encoding. `charset.SHORTEST` is not allowed for body_encoding.

  `output_charset`

    Деякі набори символів потрібно перетворити, перш ніж їх можна буде використовувати в заголовках або тексті електронних листів. Якщо input_charset є одним із них, цей атрибут міститиме ім’я набору символів, у який буде перетворено вихід. В іншому випадку буде `None`.

  `input_codec`

    Назва кодека Python, який використовується для перетворення input_charset в Unicode. Якщо кодек перетворення не потрібен, цей атрибут матиме значення `None`.

  `output_codec`

    Назва кодека Python, який використовується для перетворення Unicode у output_charset. Якщо кодек перетворення не потрібен, цей атрибут матиме те саме значення, що й input_codec.

  Екземпляри `Charset` також мають такі методи:

  `get_body_encoding`()

    Повертає кодування передачі вмісту, яке використовується для кодування тіла.

    Це або рядок `quoted-printable` або `base64` залежно від кодування, що використовується, або це функція, у цьому випадку ви повинні викликати функцію з одним аргументом, об’єкт Message, який кодується. Потім функція має встановити відповідний заголовок Content-Transfer-Encoding.

    Повертає рядок `quoted-printable`, якщо body_encoding має значення `QP`, повертає рядок `base64`, якщо body_encoding має `BASE64`, і повертає рядок `7bit` в іншому випадку .

  `get_output_charset`()

    Повернути вихідний набір символів.

    Це атрибут output_charset, якщо це не `None`, інакше це input_charset.

  `header_encode`(string)

    Заголовок кодує рядок string.

    Тип кодування (base64 або друковані цитати) базуватиметься на атрибуті header_encoding.

  `header_encode_lines`(string, maxlengths)

    Заголовок кодує рядок, спочатку перетворюючи його на байти.

    Це схоже на `header_encode()`, за винятком того, що рядок вписується в максимальну довжину рядка, задану аргументом maxlengths, який має бути ітератором: кожен елемент, повернутий цим ітератором, забезпечить наступну максимальну довжину рядка.

  `body_encode`(string)

    Основне кодування рядка string.

    Тип кодування (base64 або з можливістю друку в цитатах) базуватиметься на атрибуті body_encoding.

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

  `__str__`()

    Returns input_charset as a string coerced to lower case. `__repr__()` is an alias for `__str__()`.

  `__eq__`(other)

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

  `__ne__`(other)

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

Модуль `email.charset` також надає такі функції для додавання нових записів до глобального набору символів, псевдонімів і реєстрів кодеків:

`email.charset.``add_charset`(charset, header_enc=None, body_enc=None, output_charset=None)

  Додайте властивості символів до глобального реєстру.

  charset — це вхідний набір символів і має бути канонічною назвою набору символів.

  Optional header_enc and body_enc is either `charset.QP` for quoted-printable, `charset.BASE64` for base64 encoding, `charset.SHORTEST` for the shortest of quoted-printable or base64 encoding, or `None` for no encoding. `SHORTEST` is only valid for header_enc. The default is `None` for no encoding.

  Необов’язковий output_charset — це набір символів, у якому мають бути виведені дані. Під час виклику методу `Charset.convert()` перетворення відбуватиметься з вхідного набору символів у Unicode у вихідний набір символів. За замовчуванням виводиться той самий набір символів, що й вхід.

  Як input_charset, так і output_charset повинні мати записи кодека Юнікод у відображенні набору символів у кодек модуля; використовуйте `add_codec()`, щоб додати кодеки, про які модуль не знає. Для отримання додаткової інформації дивіться документацію модуля `codecs`.

  Глобальний реєстр набору символів зберігається в глобальному словнику модуля `CHARSETS`.

`email.charset.``add_alias`(alias, canonical)

  Додайте псевдонім набору символів. alias — псевдонім, напр. `латин-1`. canonical — це канонічне ім’я набору символів, напр. `iso-8859-1`.

  Глобальний реєстр псевдонімів кодування зберігається в глобальному словнику модуля `ALIASES`.

`email.charset.``add_codec`(charset, codecname)

  Додайте кодек, який відображає символи в заданому наборі символів у та з Unicode.

  charset — це канонічна назва набору символів. codecname — це назва кодека Python, відповідно до другого аргументу методу `str` `encode()`.