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().