# `codecs` — Codec registry and base classes

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

Цей модуль визначає базові класи для стандартних кодеків Python (кодери та декодери) і надає доступ до внутрішнього реєстру кодеків Python, який керує процесом пошуку кодека та обробки помилок. Більшість стандартних кодеків — це кодування тексту, які кодують текст у байти (і декодують байти в текст), але є також кодеки, які кодують текст у текст і байти в байти. Спеціальні кодеки можуть кодувати та декодувати між довільними типами, але деякі функції модулів обмежено для використання спеціально з текстовими кодуваннями або з кодеками, які кодують у `bytes`.

Модуль визначає такі функції для кодування та декодування будь-яким кодеком:

codecs.encode(obj, encoding='utf-8', errors='strict')

  Кодує obj за допомогою кодека, зареєстрованого для кодування.

  Помилки можуть бути надані для встановлення потрібної схеми обробки помилок. Обробником помилок за замовчуванням є `'strict'`, що означає, що помилки кодування викликають `ValueError` (або більш специфічний підклас кодека, наприклад `UnicodeEncodeError`). Зверніться до Базові класи кодеків для отримання додаткової інформації щодо обробки помилок кодека.

codecs.decode(obj, encoding='utf-8', errors='strict')

  Декодує obj за допомогою кодека, зареєстрованого для кодування.

  Помилки можуть бути надані для встановлення потрібної схеми обробки помилок. Обробником помилок за замовчуванням є `'strict'`, що означає, що помилки декодування викликають `ValueError` (або більш специфічний підклас кодека, такий як `UnicodeDecodeError`). Зверніться до Базові класи кодеків для отримання додаткової інформації про обробку помилок кодека.

codecs.charmap_build(string)

  Return a mapping suitable for encoding with a custom single-byte encoding. Given a `str` string of up to 256 characters representing a decoding table, returns either a compact internal mapping object `EncodingMap` or a `dictionary` mapping character ordinals to byte values. Raises a `TypeError` on invalid input.

Повну інформацію про кожен кодек також можна переглянути безпосередньо:

codecs.lookup(encoding, /)

  Шукає інформацію про кодек у реєстрі кодеків Python і повертає об’єкт `CodecInfo`, як визначено нижче.

  This function first normalizes the encoding: all ASCII letters are converted to lower case, spaces are replaced with hyphens. Then encoding is looked up in the registry’s cache. If not found, the list of registered search functions is scanned. If no `CodecInfo` object is found, a `LookupError` is raised. Otherwise, the `CodecInfo` object is stored in the cache and returned to the caller.

  Змінено в версії 3.9: Any characters except ASCII letters and digits and a dot are converted to underscore.

  Змінено в версії 3.15: No characters are converted to underscore anymore. Spaces are converted to hyphens.

class codecs.CodecInfo(encode, decode, streamreader=None, streamwriter=None, incrementalencoder=None, incrementaldecoder=None, name=None)

  Відомості про кодек під час пошуку реєстру кодеків. Аргументи конструктора зберігаються в однойменних атрибутах:

  name

    Назва кодування.

  encode
  decode

    Функції кодування та декодування без збереження стану. Це мають бути функції чи методи, які мають той самий інтерфейс, що й методи `encode()` і `decode()` екземплярів кодека (див. Інтерфейс кодека). Очікується, що функції або методи працюватимуть у режимі без збереження стану.

  incrementalencoder
  incrementaldecoder

    Класи інкрементального кодера та декодера або заводські функції. Вони мають забезпечувати інтерфейс, визначений базовими класами `IncrementalEncoder` та `IncrementalDecoder` відповідно. Інкрементні кодеки можуть підтримувати стан.

  streamwriter
  streamreader

    Класи потокового запису та читання або фабричні функції. Вони мають забезпечувати інтерфейс, визначений базовими класами `StreamWriter` і `StreamReader` відповідно. Потокові кодеки можуть підтримувати стан.

Щоб спростити доступ до різних компонентів кодека, модуль надає такі додаткові функції, які використовують `lookup()` для пошуку кодека:

codecs.getencoder(encoding)

  Знайдіть кодек для даного кодування та поверніть його функцію кодувальника.

  Викликає `LookupError`, якщо кодування не знайдено.

codecs.getdecoder(encoding)

  Знайдіть кодек для даного кодування та поверніть його функцію декодера.

  Викликає `LookupError`, якщо кодування не знайдено.

codecs.getincrementalencoder(encoding)

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

  Викликає `LookupError`, якщо кодування не знайдено або кодек не підтримує інкрементний кодер.

codecs.getincrementaldecoder(encoding)

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

  Викликає `LookupError`, якщо кодування не знайдено або кодек не підтримує інкрементний декодер.

codecs.getreader(encoding)

  Знайдіть кодек для вказаного кодування та поверніть його клас `StreamReader` або фабричну функцію.

  Викликає `LookupError`, якщо кодування не знайдено.

codecs.getwriter(encoding)

  Знайдіть кодек для вказаного кодування та поверніть його клас `StreamWriter` або фабричну функцію.

  Викликає `LookupError`, якщо кодування не знайдено.

Спеціальні кодеки стають доступними, якщо зареєструвати відповідну функцію пошуку кодеків:

codecs.register(search_function, /)

  Register a codec search function. Search functions are expected to take one argument, being the encoding name in all lower case letters with spaces converted to hyphens, and return a `CodecInfo` object. In case a search function cannot find a given encoding, it should return `None`.

codecs.unregister(search_function, /)

  Скасуйте реєстрацію функції пошуку кодеків і очистіть кеш реєстру. Якщо функція пошуку не зареєстрована, нічого не робіть.

  Added in version 3.10.

Хоча вбудований `open()` і пов’язаний модуль `io` є рекомендованим підходом для роботи з кодованими текстовими файлами, цей модуль надає додаткові службові функції та класи, які дозволяють використовувати ширший діапазон кодеків під час роботи з бінарними файлами:

codecs.open(filename, mode='r', encoding=None, errors='strict', buffering=-1)

  Відкрийте закодований файл у заданому режимі та поверніть екземпляр `StreamReaderWriter`, забезпечуючи прозоре кодування/декодування. Типовим режимом файлу є `'r''`, що означає відкриття файлу в режимі читання.

  Примітка

  If encoding is not `None`, then the underlying encoded files are always opened in binary mode. No automatic conversion of `'\n'` is done on reading and writing. The mode argument may be any binary mode acceptable to the built-in `open()` function; the `'b'` is automatically added.

  encoding визначає кодування, яке буде використано для файлу. Дозволяється будь-яке кодування, яке кодує та декодує з байтів, а типи даних, які підтримуються методами файлів, залежать від використовуваного кодека.

  errors можуть бути надані для визначення обробки помилок. За замовчуванням встановлено значення `'strict''`, що спричиняє виникнення `ValueError` у разі виникнення помилки кодування.

  buffering має те саме значення, що й вбудована функція `open()`. За замовчуванням він дорівнює -1, що означає, що буде використано стандартний розмір буфера.

  Змінено в версії 3.11: The `'U'` mode has been removed.

  Застаріло починаючи з версії 3.14: `codecs.open()` has been superseded by `open()`.

codecs.EncodedFile(file, data_encoding, file_encoding=None, errors='strict')

  Повертає екземпляр `StreamRecoder`, загорнуту версію файлу, яка забезпечує прозоре перекодування. Вихідний файл закривається, коли закривається упакована версія.

  Дані, записані в обгорнутий файл, декодуються відповідно до заданого data_encoding, а потім записуються в вихідний файл у вигляді байтів за допомогою file_encoding. Байти, зчитані з вихідного файлу, декодуються відповідно до file_encoding, а результат кодується за допомогою data_encoding.

  Якщо file_encoding не вказано, за умовчанням буде data_encoding.

  errors можуть бути надані для визначення обробки помилок. За замовчуванням встановлено `'strict'`, що спричиняє `ValueError`, що виникає у випадку помилки кодування.

codecs.iterencode(iterator, encoding, errors='strict', **kwargs)

  Uses an incremental encoder to iteratively encode the input provided by iterator. iterator must yield `str` objects. This function is a generator. The errors argument (as well as any other keyword argument) is passed through to the incremental encoder.

  Ця функція вимагає, щоб кодек приймав текстові об’єкти `str` для кодування. Тому він не підтримує кодувальники байт-у-байт, такі як `base64_codec`.

codecs.iterdecode(iterator, encoding, errors='strict', **kwargs)

  Uses an incremental decoder to iteratively decode the input provided by iterator. iterator must yield `bytes` objects. This function is a generator. The errors argument (as well as any other keyword argument) is passed through to the incremental decoder.

  Ця функція вимагає, щоб кодек приймав об’єкти `bytes` для декодування. Тому він не підтримує кодувальники тексту в текст, такі як `rot_13`, хоча `rot_13` можна використовувати еквівалентно з `iterencode()`.

codecs.readbuffer_encode(buffer, errors=None, /)

  Return a `tuple` containing the raw bytes of buffer, a buffer-compatible object or `str` (encoded to UTF-8 before processing), and their length in bytes.

  The errors argument is ignored.

      >>> codecs.readbuffer_encode(b"Zito")
      (b'Zito', 4)

Модуль також надає наступні константи, які корисні для читання та запису в залежні від платформи файли:

codecs.BOM
codecs.BOM_BE
codecs.BOM_LE
codecs.BOM_UTF8
codecs.BOM_UTF16
codecs.BOM_UTF16_BE
codecs.BOM_UTF16_LE
codecs.BOM_UTF32
codecs.BOM_UTF32_BE
codecs.BOM_UTF32_LE

  Ці константи визначають різні послідовності байтів, будучи мітками порядку байтів Unicode (BOM) для кількох кодувань. Вони використовуються в потоках даних UTF-16 і UTF-32 для позначення використовуваного порядку байтів, а в UTF-8 як підпис Юнікод. `BOM_UTF16` є або `BOM_UTF16_BE`, або `BOM_UTF16_LE` залежно від рідного порядку байтів платформи, `BOM` є псевдонімом для `BOM_UTF16`, `BOM_LE` для `BOM_UTF16_LE` і `BOM_BE` для `BOM_UTF16_BE`. Інші представляють специфікацію в кодуваннях UTF-8 і UTF-32.

## Базові класи кодеків

The `codecs` module defines a set of base classes which define the interfaces for working with codec objects, and can also be used as the basis for custom codec implementations.

Кожен кодек має визначати чотири інтерфейси, щоб зробити його придатним для використання як кодек у Python: кодер без стану, декодер без стану, читач потоку та запис потоку. Зчитувач і записувач потоків зазвичай повторно використовують кодер/декодер без збереження стану для реалізації протоколів файлів. Автори кодеків також повинні визначити, як кодек оброблятиме помилки кодування та декодування.

### Обробники помилок

Щоб спростити та стандартизувати обробку помилок, кодеки можуть реалізовувати різні схеми обробки помилок, приймаючи рядковий аргумент errors:

    >>> 'German ß, ♬'.encode(encoding='ascii', errors='backslashreplace')
    b'German \\xdf, \\u266c'
    >>> 'German ß, ♬'.encode(encoding='ascii', errors='xmlcharrefreplace')
    b'German &#223;, &#9836;'

Наступні обробники помилок можна використовувати з усіма кодеками Python Стандартні кодування:

Значення | Значення
--- | ---
`'строгий''` | Викликати `UnicodeError` (або підклас), це типово. Реалізовано в `strict_errors()`.
`'ігнорувати''` | Ігноруйте неправильні дані та продовжуйте без додаткового повідомлення. Реалізовано в `ignore_errors()`.
`'замінити'` | Замініть маркером заміни. У кодуванні використовуйте `?` (символ ASCII). Під час декодування використовуйте `�` (U+FFFD, офіційний СИМВОЛ ЗАМІНИ). Реалізовано в `replace_errors()`.
`'заміна зворотної косої риски''` | Replace with backslashed escape sequences. On encoding, use hexadecimal form of Unicode code point with formats `\xhh` `\uxxxx` `\Uxxxxxxxx`. On decoding, use hexadecimal form of byte value with format `\xhh`. Implemented in `backslashreplace_errors()`.
`'сурогатна втеча'` | Під час декодування замініть байт окремим сурогатним кодом у діапазоні від `U+DC80` до `U+DCFF`. Потім цей код буде перетворено назад у той самий байт, коли під час кодування даних використовується обробник помилок `'surrogateescape'`. (Докладніше див. PEP 383.)

Наступні обробники помилок застосовуються лише до кодування (в межах кодування тексту):

Значення | Значення
--- | ---
`'xmlcharrefreplace'` | Replace with XML/HTML numeric character reference, which is a decimal form of Unicode code point with format `&#num;`. Implemented in `xmlcharrefreplace_errors()`.
`'namereplace'` | Замініть керуючу послідовність `\N{...}`, що відображається в фігурних дужках — це властивість Name із бази даних символів Unicode. Реалізовано в `namereplace_errors()`.

Крім того, наступний обробник помилок є специфічним для даних кодеків:

Значення | Кодеки | Значення
--- | --- | ---
`'сурогатний пропуск''` | utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le | Дозволити кодування та декодування сурогатної кодової точки (`U+D800` - `U+DFFF`) як звичайну кодову точку. Інакше ці кодеки розглядають наявність сурогатної кодової точки в `str` як помилку.

Added in version 3.1: Обробники помилок `'surrogateescape'` і `'surrogatepass'`.

Змінено в версії 3.4: Обробник помилок `'surrogatepass'` тепер працює з кодеками utf-16* і utf-32*.

Added in version 3.5: Обробник помилок `'namereplace`.

Змінено в версії 3.5: Обробник помилок `'backslashreplace'` тепер працює з декодуванням і перекладом.

Набір дозволених значень можна розширити, зареєструвавши новий іменований обробник помилок:

codecs.register_error(name, error_handler, /)

  Зареєструйте функцію обробки помилок error_handler під назвою name. Аргумент error_handler буде викликаний під час кодування та декодування у разі помилки, якщо name вказано як параметр errors.

  Для кодування error_handler буде викликано з екземпляром `UnicodeEncodeError`, який містить інформацію про розташування помилки. Обробник помилок повинен або викликати це чи інше виключення, або повернути кортеж із заміною некодованої частини вхідних даних і позиції, де кодування повинно продовжуватися. Заміна може бути `str` або `bytes`. Якщо заміною є байти, кодер просто скопіює їх у вихідний буфер. Якщо заміна є рядком, кодер закодує заміну. Кодування продовжується на початковому введенні у вказаній позиції. Від’ємні значення позиції розглядатимуться як такі, що відносяться до кінця вхідного рядка. Якщо результуюча позиція виходить за межі, буде викликано `IndexError`.

  Декодування та переклад працює аналогічно, за винятком того, що `UnicodeDecodeError` або `UnicodeTranslateError` буде передано обробнику, а заміна з обробника помилок буде введена безпосередньо у вивід.

Раніше зареєстровані обробники помилок (включаючи стандартні обробники помилок) можна шукати за назвою:

codecs.lookup_error(name, /)

  Повернути обробник помилок, попередньо зареєстрований під іменем name.

  Викликає `LookupError`, якщо обробник не знайдено.

Наступні стандартні обробники помилок також доступні як функції рівня модуля:

codecs.strict_errors(exception)

  Реалізує `'сувору'` обробку помилок.

  Кожна помилка кодування або декодування викликає `UnicodeError`.

codecs.ignore_errors(exception)

  Реалізує обробку помилок `'ignore''`.

  Некоректні дані ігноруються; кодування або декодування продовжується без додаткового повідомлення.

codecs.replace_errors(exception)

  Реалізує обробку помилок `'replace''`.

  Замінює `?` (символ ASCII) для помилок кодування або `�` (U+FFFD, офіційний СИМВОЛ ЗАМІНИ) для помилок декодування.

codecs.backslashreplace_errors(exception)

  Реалізує обробку помилок `'backslashreplace'`.

  Malformed data is replaced by a backslashed escape sequence. On encoding, use the hexadecimal form of Unicode code point with formats `\xhh` `\uxxxx` `\Uxxxxxxxx`. On decoding, use the hexadecimal form of byte value with format `\xhh`.

  Змінено в версії 3.5: Працює з декодуванням і перекладом.

codecs.xmlcharrefreplace_errors(exception)

  Реалізує обробку помилок `'xmlcharrefreplace'` (лише для кодування в межах text encoding).

  The unencodable character is replaced by an appropriate XML/HTML numeric character reference, which is a decimal form of Unicode code point with format `&#num;` .

codecs.namereplace_errors(exception)

  Реалізує обробку помилок `'namereplace'` (лише для кодування в межах text encoding).

  Некодований символ замінюється керуючою послідовністю `\N{...}`. Набір символів, що з’являються в фігурних дужках, є властивістю Name з бази даних символів Unicode. Наприклад, німецьку малу літеру `'ß'` буде перетворено на послідовність байтів `\N{LATIN SMALL LETTER SHARP S}` .

  Added in version 3.5.

### Кодування та декодування без збереження стану

Базовий клас `Codec` визначає ці методи, які також визначають функціональні інтерфейси кодера та декодера без збереження стану:

class codecs.Codec
  encode(input, errors='strict')

    Кодує об’єкт input і повертає кортеж (вихідний об’єкт, споживана довжина). Наприклад, text encoding перетворює рядковий об’єкт на об’єкт bytes, використовуючи певне кодування набору символів (наприклад, `cp1252` або `iso-8859-1`).

    Аргумент errors визначає застосовувану обробку помилок. За замовчуванням `'сувора''` обробка.

    Метод може не зберігати стан в екземплярі `Codec`. Використовуйте `StreamWriter` для кодеків, які мають зберігати стан, щоб зробити кодування ефективним.

    У цій ситуації кодер повинен мати можливість обробляти вхідні дані нульової довжини та повертати порожній об’єкт типу вихідного об’єкта.

  decode(input, errors='strict')

    Декодує об’єкт input і повертає кортеж (вихідний об’єкт, споживана довжина). Наприклад, для text encoding декодування перетворює об’єкт bytes, закодований за допомогою кодування певного набору символів, на рядковий об’єкт.

    Для текстових кодувань і кодеків від байтів до байтів input має бути об’єктом bytes або таким, який забезпечує інтерфейс буфера лише для читання – наприклад, об’єкти буфера та файли, відображені в пам’яті.

    Аргумент errors визначає застосовувану обробку помилок. За замовчуванням `'сувора''` обробка.

    Метод може не зберігати стан в екземплярі `Codec`. Використовуйте `StreamReader` для кодеків, які мають зберігати стан, щоб зробити декодування ефективним.

    У цій ситуації декодер повинен мати можливість обробляти вхідні дані нульової довжини та повертати порожній об’єкт типу вихідного об’єкта.

### Інкрементне кодування та декодування

Класи `IncrementalEncoder` і `IncrementalDecoder` забезпечують базовий інтерфейс для інкрементного кодування та декодування. Кодування/декодування вхідних даних виконується не одним викликом функції кодувальника/декодера без збереження стану, а кількома викликами методу `encode()`/`decode()` інкрементального кодувальника /декодер. Інкрементний кодер/декодер відстежує процес кодування/декодування під час викликів методів.

Об’єднаний вихід викликів методу `encode()`/`decode()` такий самий, як якби всі окремі входи були об’єднані в один, і цей вхід було закодовано/декодовано за допомогою кодер/декодер без стану.

#### Об’єкти IncrementalEncoder

Клас `IncrementalEncoder` використовується для кодування вхідних даних у кілька кроків. Він визначає наступні методи, які повинен визначити кожен інкрементальний кодер, щоб бути сумісним із реєстром кодеків Python.

class codecs.IncrementalEncoder(errors='strict')

  Конструктор для екземпляра `IncrementalEncoder`.

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

  `IncrementalEncoder` може реалізовувати різні схеми обробки помилок, надаючи аргумент ключового слова errors. Перегляньте Обробники помилок можливі значення.

  Аргумент errors буде призначено однойменному атрибуту. Призначення цьому атрибуту дає змогу перемикатися між різними стратегіями обробки помилок протягом життя об’єкта `IncrementalEncoder`.

  encode(object, final=False)

    Кодує об’єкт (з урахуванням поточного стану кодувальника) і повертає отриманий закодований об’єкт. Якщо це останній виклик `encode()`, final має бути true (за умовчанням — false).

  reset()

    Скиньте кодер до початкового стану. Вихідні дані відхиляються: викличте `.encode(object, final=True)`, передаючи порожній байт або текстовий рядок, якщо необхідно, щоб скинути кодер і отримати вихідні дані.

  getstate()

    Повертає поточний стан кодувальника, який має бути цілим числом. Реалізація має гарантувати, що `0` є найпоширенішим станом. (Стани, які є складнішими, ніж цілі числа, можна перетворити на ціле число шляхом маршалінгу/вибору стану та кодування байтів результуючого рядка в ціле число.)

  setstate(state)

    Встановіть стан кодера на state. state має бути станом кодувальника, який повертає `getstate()`.

#### Об’єкти IncrementalDecoder

Клас `IncrementalDecoder` використовується для декодування вхідних даних у кілька кроків. Він визначає наступні методи, які повинен визначити кожен інкрементний декодер, щоб бути сумісним із реєстром кодеків Python.

class codecs.IncrementalDecoder(errors='strict')

  Конструктор для екземпляра `IncrementalDecoder`.

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

  `IncrementalDecoder` може реалізовувати різні схеми обробки помилок, надаючи аргумент ключового слова errors. Перегляньте Обробники помилок можливі значення.

  Аргумент errors буде призначено однойменному атрибуту. Призначення цьому атрибуту дає змогу перемикатися між різними стратегіями обробки помилок протягом життя об’єкта `IncrementalDecoder`.

  decode(object, final=False)

    Декодує об’єкт (з урахуванням поточного стану декодера) і повертає отриманий декодований об’єкт. Якщо це останній виклик `decode()`, final має бути true (за умовчанням — false). Якщо final має значення true, декодер повинен повністю декодувати вхідні дані та скинути всі буфери. Якщо це неможливо (наприклад, через неповну послідовність байтів у кінці введення), він повинен ініціювати обробку помилок, як у випадку без стану (що може спричинити виняток).

  reset()

    Скиньте декодер до початкового стану.

  getstate()

    Повернути поточний стан декодера. Це має бути кортеж із двома елементами, перший має бути буфером, що містить ще недекодований вхід. Друге має бути цілим числом і може бути додатковою інформацією про стан. (Реалізація має переконатися, що `0` є найпоширенішою додатковою інформацією про стан.) Якщо ця додаткова інформація про стан `0`, має бути можливим встановити декодер у стан, який не має буферизації вхідних даних і `0` як додаткову інформацію про стан, так що подача попередньо буферизованого вхідного сигналу в декодер повертає його до попереднього стану без виведення. (Додаткову інформацію про стан, яка є складнішою, ніж цілі числа, можна перетворити на ціле число шляхом маршалінгу/вибору інформації та кодування байтів отриманого рядка в ціле число.)

  setstate(state)

    Встановіть стан декодера на state. state має бути станом декодера, який повертає `getstate()`.

### Кодування та декодування потоку

The `StreamWriter` and `StreamReader` classes provide generic working interfaces which can be used to implement new encoding submodules very easily. See `encodings.utf_8` for an example of how this is done.

#### Об’єкти StreamWriter

Клас `StreamWriter` є підкласом `Codec` і визначає наступні методи, які повинен визначити кожен записувач потоків, щоб бути сумісним із реєстром кодеків Python.

class codecs.StreamWriter(stream, errors='strict')

  Конструктор для екземпляра `StreamWriter`.

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

  Аргумент потік має бути файлоподібним об’єктом, відкритим для запису тексту або двійкових даних, відповідно до конкретного кодека.

  `StreamWriter` може реалізовувати різні схеми обробки помилок, надаючи аргумент ключового слова errors. Перегляньте Обробники помилок для стандартних обробників помилок, які може підтримувати основний потоковий кодек.

  Аргумент errors буде призначено однойменному атрибуту. Призначення цьому атрибуту дає змогу перемикатися між різними стратегіями обробки помилок протягом життя об’єкта `StreamWriter`.

  write(object)

    Записує закодований вміст об’єкта в потік.

  writelines(list)

    Записує конкатенований ітерований рядок у потік (можливо, повторно використовуючи метод `write()`). Нескінченні або дуже великі ітерації не підтримуються. Стандартні кодеки від байтів до байтів не підтримують цей метод.

  reset()

    Скидає буфери кодеків, які використовуються для збереження внутрішнього стану.

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

Окрім вищезазначених методів, `StreamWriter` також має успадкувати всі інші методи та атрибути базового потоку.

#### Об’єкти StreamReader

Клас `StreamReader` є підкласом `Codec` і визначає наступні методи, які повинен визначити кожен зчитувач потоку, щоб бути сумісним із реєстром кодеків Python.

class codecs.StreamReader(stream, errors='strict')

  Конструктор для екземпляра `StreamReader`.

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

  Аргумент потік має бути файлоподібним об’єктом, відкритим для читання тексту або двійкових даних, відповідно до конкретного кодека.

  `StreamReader` може реалізовувати різні схеми обробки помилок, надаючи аргумент ключового слова errors. Перегляньте Обробники помилок для стандартних обробників помилок, які може підтримувати основний потоковий кодек.

  Аргумент errors буде призначено однойменному атрибуту. Призначення цьому атрибуту дає змогу перемикатися між різними стратегіями обробки помилок протягом життя об’єкта `StreamReader`.

  Набір дозволених значень для аргументу errors можна розширити за допомогою `register_error()`.

  read(size=-1, chars=-1, firstline=False)

    Декодує дані з потоку та повертає отриманий об’єкт.

    Аргумент chars вказує кількість декодованих кодових точок або байтів, які потрібно повернути. Метод `read()` ніколи не поверне більше даних, ніж вимагається, але може повернути менше, якщо їх буде недостатньо.

    Аргумент size вказує на приблизну максимальну кількість закодованих байтів або кодових точок для читання для декодування. Декодер може змінювати цей параметр за потреби. Значення за замовчуванням -1 вказує на читання та декодування якомога більшої кількості. Цей параметр призначений для запобігання необхідності декодувати великі файли за один крок.

    Прапорець firstline вказує на те, що було б достатньо повернути лише перший рядок, якщо в наступних рядках є помилки декодування.

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

  readline(size=None, keepends=True)

    Прочитати один рядок із вхідного потоку та повернути декодовані дані.

    size, якщо задано, передається як аргумент розміру в метод `read()` потоку.

    Якщо keepends має значення false, закінчення рядків буде видалено з повернутих рядків.

  readlines(sizehint=None, keepends=True)

    Прочитати всі рядки, доступні у вхідному потоці, і повернути їх як список рядків.

    Закінчення рядків реалізуються за допомогою методу кодека `decode()` і включаються до записів списку, якщо keepends має значення true.

    sizehint, якщо його задано, передається як аргумент size у метод потоку `read()`.

  reset()

    Скидає буфери кодеків, які використовуються для збереження внутрішнього стану.

    Зауважте, що переміщення потоку не повинно відбуватися. Цей метод насамперед призначений для відновлення після помилок декодування.

Окрім вищезазначених методів, `StreamReader` також має успадкувати всі інші методи та атрибути базового потоку.

#### Об’єкти StreamReaderWriter

`StreamReaderWriter` — це зручний клас, який дозволяє обгортати потоки, які працюють як у режимі читання, так і в режимі запису.

Конструкція така, що можна використовувати фабричні функції, які повертає функція `lookup()` для створення екземпляра.

class codecs.StreamReaderWriter(stream, Reader, Writer, errors='strict')

  Створює екземпляр `StreamReaderWriter`. потік має бути файлоподібним об’єктом. Reader і Writer повинні бути фабричними функціями або класами, що забезпечують інтерфейс `StreamReader` і `StreamWriter` відповідно. Обробка помилок виконується так само, як визначено для читачів і записів потоку.

Екземпляри `StreamReaderWriter` визначають комбіновані інтерфейси класів `StreamReader` і `StreamWriter`. Вони успадковують усі інші методи та атрибути від основного потоку.

#### Об’єкти StreamRecoder

`StreamRecoder` переводить дані з одного кодування в інше, що іноді корисно, коли ви маєте справу з різними середовищами кодування.

Конструкція така, що можна використовувати фабричні функції, які повертає функція `lookup()` для створення екземпляра.

class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors='strict')

  Creates a `StreamRecoder` instance which implements a two-way conversion: encode and decode work on the frontend — the data visible to code calling `read()` and `write()`, while Reader and Writer work on the backend — the data in stream.

  Ви можете використовувати ці об’єкти для прозорого перекодування, наприклад, з Latin-1 на UTF-8 і назад.

  Аргумент потік має бути файлоподібним об’єктом.

  Аргументи encode і decode мають відповідати інтерфейсу `Codec`. Reader і Writer повинні бути фабричними функціями або класами, що забезпечують об’єкти інтерфейсу `StreamReader` і `StreamWriter` відповідно.

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

Екземпляри `StreamRecoder` визначають комбіновані інтерфейси класів `StreamReader` і `StreamWriter`. Вони успадковують усі інші методи та атрибути основного потоку.

## Кодування та Unicode

Рядки зберігаються внутрішньо як послідовності кодових точок у діапазоні `U+0000`–`U+10FFFF`. (Див. PEP 393 для отримання додаткової інформації про реалізацію.) Коли рядковий об’єкт використовується поза центральним процесором і пам’яттю, стає проблемою порядок байтів і те, як ці масиви зберігаються як байти. Як і в інших кодеках, серіалізація рядка в послідовність байтів відома як кодування, а відтворення рядка з послідовності байтів відоме як декодування. Існує безліч різних кодеків серіалізації тексту, які в сукупності називаються текстовими кодуваннями.

Найпростіше кодування тексту (називається `'latin-1'` або `'iso-8859-1'`) відображає кодові точки 0–255 на байти `0x0`–`0xff`, що означає, що рядковий об’єкт, який містить кодові точки вище `U+00FF`, не може бути закодований цим кодеком. Це призведе до появи `UnicodeEncodeError`, яка виглядає так (хоча деталі повідомлення про помилку можуть відрізнятися): `UnicodeEncodeError: кодек 'latin-1' не може закодувати символ '\u1234' у позиції 3 : порядковий номер не в діапазоні (256)`.

Існує ще одна група кодувань (так звані кодування charmap), які вибирають іншу підмножину всіх кодових точок Unicode і те, як ці кодові точки відображаються на байти `0x0`–`0xff`. Щоб побачити, як це робиться, просто відкрийте, наприклад. `encodings/cp1252.py` (це кодування, яке використовується в основному в Windows). Існує рядкова константа з 256 символами, яка показує, який символ зіставляється з яким значенням байта.

All of these encodings can only encode 256 of the 1114112 code points defined in Unicode. A simple and straightforward way that can store each Unicode code point, is to store each code point as four consecutive bytes. There are two possibilities: store the bytes in big endian or in little endian order. These two encodings are called `UTF-32-BE` and `UTF-32-LE` respectively. Their disadvantage is that if, for example, you use `UTF-32-BE` on a little endian machine you will always have to swap bytes on encoding and decoding. Python’s `UTF-16` and `UTF-32` codecs avoid this problem by using the platform’s native byte order when no BOM is present. Python follows prevailing platform practice, so native-endian data round-trips without redundant byte swapping, even though the Unicode Standard defaults to big-endian when the byte order is unspecified. When these bytes are read by a CPU with a different endianness, the bytes have to be swapped. To be able to detect the endianness of a `UTF-16` or `UTF-32` byte sequence, a BOM («Byte Order Mark») is used. This is the Unicode character `U+FEFF`. This character can be prepended to every `UTF-16` or `UTF-32` byte sequence. The byte swapped version of this character (`0xFFFE`) is an illegal character that may not appear in a Unicode text. When the first character of a `UTF-16` or `UTF-32` byte sequence is `U+FFFE`, the bytes have to be swapped on decoding.

Unfortunately the character `U+FEFF` had a second purpose as a `ZERO WIDTH NO-BREAK SPACE`: a character that has no width and doesn’t allow a word to be split. It can e.g. be used to give hints to a ligature algorithm. With Unicode 4.0 using `U+FEFF` as a `ZERO WIDTH NO-BREAK SPACE` has been deprecated (with `U+2060` (`WORD JOINER`) assuming this role). Nevertheless Unicode software still must be able to handle `U+FEFF` in both roles: as a BOM it’s a device to determine the storage layout of the encoded bytes, and vanishes once the byte sequence has been decoded into a string; as a `ZERO WIDTH NO-BREAK SPACE` it’s a normal character that will be decoded like any other.

Є інше кодування, яке може кодувати повний діапазон символів Unicode: UTF-8. UTF-8 — це 8-бітне кодування, що означає, що в UTF-8 немає проблем із порядком байтів. Кожен байт у послідовності байтів UTF-8 складається з двох частин: бітів маркера (старших бітів) і бітів корисного навантаження. Біти маркера являють собою послідовність із нуля до чотирьох бітів `1`, за якими йде `0` біт. Символи Unicode кодуються таким чином (де x є бітами корисного навантаження, які при з’єднанні дають символ Unicode):

Діапазон | Кодування
--- | ---
`U-00000000` … `U-0000007F` | 0xxxxxxx
`U-00000080` … `U-000007FF` | 110xxxxx 10xxxxxx
`U-00000800` … `U-0000FFFF` | 1110xxxx 10xxxxxx 10xxxxxx
`U-00010000` … `U-0010FFFF` | 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx

Наймолодшим бітом символу Юнікод є крайній правий біт x.

Оскільки UTF-8 є 8-бітним кодуванням, специфікація матеріалів не потрібна, і будь-який символ `U+FEFF` у декодованому рядку (навіть якщо це перший символ) розглядається як `НУЛЬОВА ШИРИНА БЕЗ РОЗБИВУ` .

Без зовнішньої інформації неможливо достовірно визначити, яке кодування було використано для кодування рядка. Кожне кодування charmap може декодувати будь-яку випадкову послідовність байтів. Однак це неможливо з UTF-8, оскільки послідовності байтів UTF-8 мають структуру, яка не допускає довільних послідовностей байтів. Щоб підвищити надійність виявлення кодування UTF-8, Microsoft винайшла варіант UTF-8 (який Python називає `"utf-8-sig"`) для своєї програми Notepad: перед будь-яким із символів Unicode записується у файл, записується BOM у кодуванні UTF-8 (який виглядає так як послідовність байтів: `0xef`, `0xbb`, `0xbf`). Оскільки малоймовірно, щоб будь-який файл, закодований charmap, починався з цих значень байтів (що, наприклад, відображатиметься на

> МАЛА ЛАТИНСЬКА БУКВА I З ДІАРЕЗИСОМ
> ПОДВІЙНІ КУТНІ ЛАПКИ, Спрямовані вправо
> ПЕРЕВЕРНУТИЙ ЗНАК ПИТАННЯ

в iso-8859-1), це збільшує ймовірність того, що кодування `utf-8-sig` можна правильно вгадати з послідовності байтів. Отже, тут BOM використовується не для визначення порядку байтів, який використовується для створення послідовності байтів, а як підпис, який допомагає вгадати кодування. Під час кодування кодек utf-8-sig записуватиме `0xef`, `0xbb`, `0xbf` як перші три байти до файлу. Під час декодування `utf-8-sig` пропустить ці три байти, якщо вони відображаються як перші три байти у файлі. В UTF-8 використання BOM не рекомендується, і його слід уникати.

## Стандартні кодування

Python comes with a number of codecs built-in, either implemented as C functions or with dictionaries as mapping tables. The following table lists the codecs by name, together with a few common aliases, and the languages for which the encoding is likely used. Neither the list of aliases nor the list of languages is meant to be exhaustive. Notice that spelling alternatives that only differ in case or use a space or a hyphen instead of an underscore are also valid aliases because they are equivalent when normalized by `normalize_encoding()`. For example, `'utf-8'` is a valid alias for the `'utf_8'` codec.

Примітка

The below table lists the most common aliases, for a complete list refer to the source aliases.py file.

On Windows, `cpXXX` codecs are available for all code pages. But only codecs listed in the following table are guaranteed to exist on other platforms.

Деякі поширені кодування можуть обійти механізм пошуку кодеків для підвищення продуктивності. Ці можливості оптимізації розпізнаються CPython лише для обмеженого набору (незалежних від регістру) псевдонімів: utf-8, utf8, latin-1, latin1, iso-8859-1, iso8859-1, mbcs (лише Windows), ascii, us -ascii, utf-16, utf16, utf-32, utf32 і те саме, використовуючи підкреслення замість тире. Використання альтернативних псевдонімів для цих кодувань може призвести до сповільнення виконання.

Змінено в версії 3.6: Можливість оптимізації визнана для us-ascii.

Багато наборів символів підтримують однакові мови. Вони відрізняються за окремими символами (наприклад, чи підтримується ЗНАК ЄВРО чи ні), а також за призначенням символів позиціям коду. Зокрема, для європейських мов зазвичай існують такі варіанти:

- кодовий набір ISO 8859

- кодова сторінка Microsoft Windows, яка зазвичай походить від коду 8859, але замінює контрольні символи додатковими графічними символами

- кодову сторінку IBM EBCDIC

- кодова сторінка IBM PC, сумісна з ASCII

Кодек | Псевдоніми | Мови
--- | --- | ---
ascii | 646, us-ascii | англійська
великий5 | big5-tw, csbig5 | Традиційний китайський
big5hkscs | big5-hkscs, hkscs | Традиційний китайський
cp037 | IBM037, IBM039 | англійська
cp273 | 273, IBM273, csIBM273 | Німецький Added in version 3.4.
cp424 | EBCDIC-CP-HE, IBM424 | іврит
cp437 | 437, IBM437 | англійська
cp500 | EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500 | Західна Європа
cp720 |  | арабська
cp737 |  | грецька
cp775 | IBM775 | Балтійські мови
cp850 | 850, IBM850 | Західна Європа
cp852 | 852, IBM852 | Центральна та Східна Європа
cp855 | 855, IBM855 | Belarusian, Bulgarian, Macedonian, Russian, Serbian
cp856 |  | іврит
cp857 | 857, IBM857 | турецька
cp858 | 858, IBM858 | Західна Європа
cp860 | 860, IBM860 | португальська
cp861 | 861, CP-IS, IBM861 | ісландська
cp862 | 862, IBM862 | іврит
cp863 | 863, IBM863 | канадський
cp864 | IBM864 | арабська
cp865 | 865, IBM865 | датська, норвезька
cp866 | 866, IBM866 | російський
cp869 | 869, CP-GR, IBM869 | грецька
cp874 |  | тайська
cp875 |  | грецька
cp932 | 932, ms932, mskanji, ms-kanji, windows-31j | Японський
cp949 | 949, ms949, uhc | корейська
cp950 | 950, мс950 | Традиційний китайський
cp1006 |  | урду
cp1026 | ibm1026 | турецька
cp1125 | 1125, ibm1125, cp866u, рос | українська Added in version 3.4.
cp1140 | ibm1140 | Західна Європа
cp1250 | вікна-1250 | Центральна та Східна Європа
cp1251 | вікна-1251 | Belarusian, Bulgarian, Macedonian, Russian, Serbian
cp1252 | вікна-1252 | Західна Європа
cp1253 | вікна-1253 | грецька
cp1254 | windows-1254 | турецька
cp1255 | вікна-1255 | іврит
cp1256 | вікна-1256 | арабська
cp1257 | вікна-1257 | Балтійські мови
cp1258 | вікна-1258 | в’єтнамська
euc_jp | eucjp, ujis, u-jis | Японський
euc_jis_2004 | jisx0213, eucjis2004 | Японський
euc_jisx0213 | eucjisx0213 | Японський
euc_kr | euckr, корейська, ksc5601, ks_c-5601, ks_c-5601-1987, ksx1001, ks_x-1001 | корейська
gb2312 | китайська, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980, gb2312-80, iso-ir-58 | Спрощена Китайська
gbk | 936, cp936, ms936 | Єдина китайська
gb18030 | gb18030-2000 | Єдина китайська
Гц | hzgb, hz-gb, hz-gb-2312 | Спрощена Китайська
iso2022_jp | csiso2022jp, iso2022jp, iso-2022-jp | Японський
iso2022_jp_1 | iso2022jp-1, iso-2022-jp-1 | Японський
iso2022_jp_2 | iso2022jp-2, iso-2022-jp-2 | Японська, корейська, спрощена китайська, західноєвропейська, грецька
iso2022_jp_2004 | iso2022jp-2004, iso-2022-jp-2004 | Японський
iso2022_jp_3 | iso2022jp-3, iso-2022-jp-3 | Японський
iso2022_jp_ext | iso2022jp-ext, iso-2022-jp-ext | Японський
iso2022_kr | csiso2022kr, iso2022kr, iso-2022-kr | корейська
latin_1 | iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1 | Західна Європа
iso8859_2 | iso-8859-2, latin2, L2 | Центральна та Східна Європа
iso8859_3 | iso-8859-3, latin3, L3 | Есперанто, мальтійська
iso8859_4 | iso-8859-4, latin4, L4 | Northern Europe
iso8859_5 | iso-8859-5, кирил | Belarusian, Bulgarian, Macedonian, Russian, Serbian
iso8859_6 | iso-8859-6, араб | арабська
iso8859_7 | iso-8859-7, грецький, грецький8 | грецька
iso8859_8 | iso-8859-8, іврит | іврит
iso8859_9 | iso-8859-9, latin5, L5 | турецька
iso8859_10 | iso-8859-10, latin6, L6 | Скандинавські мови
iso8859_11 | iso-8859-11, тай | тайські мови
iso8859_13 | iso-8859-13, latin7, L7 | Балтійські мови
iso8859_14 | iso-8859-14, latin8, L8 | кельтські мови
iso8859_15 | iso-8859-15, latin9, L9 | Західна Європа
iso8859_16 | iso-8859-16, latin10, L10 | Південно-Східна Європа
Йохаб | cp1361, ms1361 | корейська
koi8_r |  | російський
koi8_t |  | таджицька Added in version 3.5.
koi8_u |  | українська
kz1048 | kz_1048, strk1048_2002, rk1048 | казахська Added in version 3.5.
mac_cyrillic | макирилицею | Belarusian, Bulgarian, Macedonian, Russian, Serbian
mac_greek | макгрік | грецька
mac_iceland | maciceland | ісландська
mac_latin2 | maclatin2, maccentraleurope, mac_centeuro | Центральна та Східна Європа
mac_roman | макромен, макінтош | Західна Європа
mac_turkish | macturkish | турецька
ptcp154 | csptcp154, pt154, cp154, кирилиця-азійська | казахська
shift_jis | csshiftjis, shiftjis, sjis, s_jis | Японський
shift_jis_2004 | shiftjis2004, sjis_2004, sjis2004 | Японський
shift_jisx0213 | shiftjisx0213, sjisx0213, s_jisx0213 | Японський
utf_32 | U32, utf32 | всі мови
utf_32_be | UTF-32BE | всі мови
utf_32_le | UTF-32LE | всі мови
utf_16 | U16, utf16 | всі мови
utf_16_be | UTF-16BE | всі мови
utf_16_le | UTF-16LE | всі мови
utf_7 | U7, unicode-1-1-utf-7 | всі мови
utf_8 | U8, UTF, utf8, cp65001 | всі мови
utf_8_sig | utf8-sig | всі мови

Змінено в версії 3.4: Кодери utf-16* і utf-32* більше не дозволяють кодувати сурогатні кодові точки (`U+D800`–`U+DFFF`). Декодери utf-32* більше не декодують послідовності байтів, які відповідають сурогатним кодовим точкам.

Змінено в версії 3.8: `cp65001` тепер є псевдонімом `utf_8`.

Змінено в версії 3.14: On Windows, `cpXXX` codecs are now available for all code pages.

## Спеціальні кодування Python

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

### Кодування тексту

Наступні кодеки забезпечують кодування `str` до `bytes` і декодування bytes-like object до `str`, подібне до кодування тексту Unicode.

Кодек | Псевдоніми | Значення
--- | --- | ---
idna |  | Реалізація RFC 3490, див. також `encodings.idna`. Підтримується лише `errors='strict'`.
mbcs | ansi, dbcs | Лише для Windows: кодуйте операнд відповідно до кодової сторінки ANSI (CP_ACP).
oem |  | Лише для Windows: кодуйте операнд відповідно до кодової сторінки OEM (CP_OEMCP). Added in version 3.6.
palmos |  | Кодування PalmOS 3.5.
punycode |  | Впровадити RFC 3492. Кодеки з підтримкою стану не підтримуються.
raw_unicode_escape |  | Latin-1 encoding with `\uXXXX` and `\UXXXXXXXX` for other code points. Existing backslashes are not escaped in any way. It is used in the Python pickle protocol.
невизначений |  | This Codec should only be used for testing purposes. Викликати виняток для всіх перетворень, навіть для порожніх рядків. Обробник помилок ігнорується.
unicode_escape |  | Кодування, придатне як вміст літералу Юнікод у вихідному коді Python із кодуванням ASCII, за винятком того, що лапки не екрануються. Декодувати з вихідного коду Latin-1. Майте на увазі, що вихідний код Python насправді використовує UTF-8 за замовчуванням.

Змінено в версії 3.8: Кодек «unicode_internal» видалено.

### Двійкові перетворення

Наступні кодеки забезпечують двійкові перетворення: bytes-like object у `bytes` зіставлення. Вони не підтримуються `bytes.decode()` (який виводить лише `str`).

Кодек | Псевдоніми | Значення | Кодер / декодер
--- | --- | --- | ---
base64_codec [1] | base64, base_64 | Перетворіть операнд на багаторядковий MIME base64 (результат завжди включає `'\n'`). Змінено в версії 3.4: приймає будь-який bytes-like object як вхідні дані для кодування та декодування | `base64.encodebytes()` / `base64.decodebytes()`
bz2_codec | bz2 | Стисніть операнд за допомогою bz2. | `bz2.compress()` / `bz2.decompress()`
hex_codec | шістнадцятковий | Перетворіть операнд у шістнадцяткове подання з двома цифрами на байт. | `binascii.b2a_hex()` / `binascii.a2b_hex()`
quopri_codec | quopri, quotedprintable, quoted_printable | Перетворіть операнд на MIME-цитований для друку. | `quopri.encode()` з `quotetabs=True` / `quopri.decode()`
uu_codec | uu | Перетворіть операнд за допомогою uuencode. |
zlib_codec | zip, zlib | Стисніть операнд за допомогою gzip. | `zlib.compress()` / `zlib.decompress()`

[1]

На додаток до байт-подібних об’єктів, `'base64_codec''` також приймає лише ASCII-примірники `str` для декодування

Added in version 3.2: Відновлення двійкових перетворень.

Змінено в версії 3.4: Відновлення псевдонімів для бінарних перетворень.

### Standalone Codec Functions

The following functions provide encoding and decoding functionality similar to codecs, but are not available as named codecs through `codecs.encode()` or `codecs.decode()`. They are used internally (for example, by `pickle`) and behave similarly to the `string_escape` codec that was removed in Python 3.

codecs.escape_encode(input, errors=None)

  Encode input using escape sequences. Similar to how `repr()` on bytes produces escaped byte values.

  input must be a `bytes` object.

  Returns a tuple `(output, length)` where output is a `bytes` object and length is the number of bytes consumed.

codecs.escape_decode(input, errors=None)

  Decode input from escape sequences back to the original bytes.

  input must be a bytes-like object.

  Returns a tuple `(output, length)` where output is a `bytes` object and length is the number of bytes consumed.

### Перетворення тексту

Наступний кодек забезпечує перетворення тексту: відображення `str` у `str`. Він не підтримується `str.encode()` (який виводить лише `bytes`).

Кодек | Псевдоніми | Значення
--- | --- | ---
rot_13 | гниль13 | Повернути шифрування операнда за допомогою шифру Цезаря.

Added in version 3.2: Відновлення текстового перетворення `rot_13`.

Змінено в версії 3.4: Відновлення псевдоніма `rot13`.

## `encodings` — Encodings package

This module implements the following functions:

encodings.normalize_encoding(encoding)

  Normalize encoding name encoding.

  Normalization works as follows: all non-alphanumeric characters except the dot used for Python package names are collapsed and replaced with a single underscore, leading and trailing underscores are removed. For example, `' -;#'` becomes `'_'`.

  Note that encoding should be ASCII only.

Примітка

The following functions should not be used directly, except for testing purposes; `codecs.lookup()` should be used instead.

encodings.search_function(encoding)

  Search for the codec module corresponding to the given encoding name encoding.

  This function first normalizes the encoding using `normalize_encoding()`, then looks for a corresponding alias. It attempts to import a codec module from the encodings package using either the alias or the normalized name. If the module is found and defines a valid `getregentry()` function that returns a `codecs.CodecInfo` object, the codec is cached and returned.

  If the codec module defines a `getaliases()` function any returned aliases are registered for future use.

encodings.win32_code_page_search_function(encoding)

  Search for a Windows code page encoding encoding of the form `cpXXXX`.

  If the code page is valid and supported, return a `codecs.CodecInfo` object for it.

  Availability: Windows.

  Added in version 3.14.

This module implements the following exception:

exception encodings.CodecRegistryError

  Raised when a codec is invalid or incompatible.

## `encodings.idna` — Інтернаціоналізовані доменні імена в програмах

Цей модуль реалізує RFC 3490 (інтернаціоналізовані доменні імена в програмах) і RFC 3492 (nameprep: профіль Stringprep для інтернаціоналізованих доменних імен (IDN)). Він побудований на основі кодування `punycode` і `stringprep`.

If you need the IDNA 2008 standard from RFC 5891 and RFC 5895, use the third-party idna module.

Ці RFC разом визначають протокол для підтримки символів, відмінних від ASCII, у доменних іменах. Доменне ім’я, що містить символи, відмінні від ASCII (наприклад, `www.Alliancefrançaise.nu`), перетворюється на ASCII-сумісне кодування (ACE, наприклад `www.xn--alliancefranaise-npb.nu`). Форма ACE імені домену потім використовується в усіх місцях, де довільні символи не дозволені протоколом, наприклад у запитах DNS, HTTP Host тощо. Це перетворення здійснюється в додатку; якщо можливо, невидимі для користувача: програма повинна прозоро перетворювати мітки домену Unicode на IDNA на дроті та перетворювати мітки ACE назад у Unicode перед тим, як представляти їх користувачеві.

Python підтримує це перетворення декількома способами: кодек `idna` виконує перетворення між Юнікодом і ACE, розділяючи вхідний рядок на мітки на основі символів-роздільників, визначених у розділі 3.1 RFC 3490, і перетворюючи кожну мітку до ACE за потреби, і навпаки, розділяючи вхідний байтовий рядок на мітки на основі роздільника `.` і перетворюючи будь-які знайдені мітки ACE в Юнікод. Крім того, модуль `socket` прозоро перетворює імена хостів Unicode на ACE, тому програмам не потрібно турбуватися про перетворення самих імен хостів, коли вони передають їх модулю сокетів. Крім того, модулі, які мають імена хостів як параметри функцій, наприклад `http.client` і `ftplib`, приймають імена хостів Unicode (`http.client` потім також прозоро надсилає IDNA ім’я хоста в полі Host, якщо воно взагалі надсилає це поле).

Під час отримання імен хостів із проводу (наприклад, під час зворотного пошуку імен) автоматичне перетворення в Unicode не виконується: програми, які бажають надати такі імена хостів користувачеві, повинні декодувати їх у Unicode.

Модуль `encodings.idna` також реалізує процедуру nameprep, яка виконує певні нормалізації імен хостів, щоб досягти нечутливості до регістру міжнародних доменних імен і уніфікувати схожі символи. За бажанням можна безпосередньо використовувати функції nameprep.

encodings.idna.nameprep(label)

  Повертає запрограмовану версію мітки. Реалізація наразі передбачає рядки запиту, тому `AllowUnassigned` є істинним.

encodings.idna.ToASCII(label)

  Перетворіть мітку на ASCII, як зазначено в RFC 3490. `UseSTD3ASCIIRules` вважається false.

encodings.idna.ToUnicode(label)

  Перетворіть мітку в Unicode, як зазначено в RFC 3490.

## `encodings.mbcs` — кодова сторінка Windows ANSI

Цей модуль реалізує кодову сторінку ANSI (CP_ACP).

Availability: Windows.

Змінено в версії 3.2: До версії 3.2 аргумент errors ігнорувався; `'replace'` завжди використовувався для кодування, а `'ignore''` для декодування.

Змінено в версії 3.3: Підтримка будь-якого засобу обробки помилок.

## `encodings.utf_8_sig` — кодек UTF-8 із підписом BOM

Цей модуль реалізує варіант кодека UTF-8. Під час кодування BOM у кодуванні UTF-8 буде додано до байтів у кодуванні UTF-8. Для кодувальника зі збереженням стану це робиться лише один раз (під час першого запису в потік байтів). Під час декодування додаткова специфікація даних у кодуванні UTF-8 на початку даних буде пропущена.