codecs — Codec registry and base classes

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

---

This module defines base classes for standard Python codecs (encoders and decoders) and provides access to the internal Python codec registry, which manages the codec and error handling lookup process. Most standard codecs are text encodings, which encode text to bytes, but there are also codecs provided that encode text to text, and bytes to bytes. Custom codecs may encode and decode between arbitrary types, but some module features are restricted to use specifically with text encodings, or with codecs that encode to 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.lookup(encoding)

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

Кодування спочатку шукаються в кеші реєстру. Якщо не знайдено, сканується список зареєстрованих функцій пошуку. Якщо об’єкт CodecInfo не знайдено, виникає LookupError. В іншому випадку об’єкт CodecInfo зберігається в кеші та повертається абоненту.

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, and return a CodecInfo object. In case a search function cannot find a given encoding, it should return None.

Примітка

Search function registration is not currently reversible, which may cause problems in some cases, such as unit testing or module reloading.

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

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

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

Примітка

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, що означає, що буде використано стандартний розмір буфера.

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)

Використовує інкрементальний кодувальник для ітеративного кодування вхідних даних, наданих iterator. Ця функція є generator. Аргумент errors (як і будь-який інший аргумент ключового слова) передається до інкрементального кодувальника.

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

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

Використовує інкрементальний декодер для ітеративного декодування вхідних даних, наданих iterator. Ця функція є generator. Аргумент errors (як і будь-який інший аргумент ключового слова) передається до інкрементального декодера.

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

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

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.

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

Модуль codecs визначає набір базових класів, які визначають інтерфейси для роботи з об’єктами кодеків, а також може бути використаний як основа для користувацьких реалізацій кодеків.

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

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

To simplify and standardize error handling, codecs may implement different error handling schemes by accepting the errors string argument. The following string values are defined and implemented by all standard Python codecs:

Значення	Значення
'строгий''	Raise UnicodeError (or a subclass); this is the default. Implemented in strict_errors().
'ігнорувати''	Ігноруйте неправильні дані та продовжуйте без додаткового повідомлення. Реалізовано в ignore_errors().

The following error handlers are only applicable to text encodings:

Значення	Значення
'замінити'	Replace with a suitable replacement marker; Python will use the official U+FFFD REPLACEMENT CHARACTER for the built-in codecs on decoding, and „?“ on encoding. Implemented in replace_errors().
'xmlcharrefreplace'	Replace with the appropriate XML character reference (only for encoding). Implemented in xmlcharrefreplace_errors().
'заміна зворотної косої риски''	Replace with backslashed escape sequences. Implemented in backslashreplace_errors().
'namereplace'	Replace with \N{...} escape sequences (only for encoding). Implemented in namereplace_errors().
'сурогатна втеча'	Під час декодування замініть байт окремим сурогатним кодом у діапазоні від U+DC80 до U+DCFF. Потім цей код буде перетворено назад у той самий байт, коли під час кодування даних використовується обробник помилок 'surrogateescape'. (Докладніше див. PEP 383.)

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

Значення	Кодеки	Значення
'сурогатний пропуск''	utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le	Allow encoding and decoding of surrogate codes. These codecs normally treat the presence of surrogates as an error.

Нове в версії 3.1: Обробники помилок 'surrogateescape' і 'surrogatepass'.

Змінено в версії 3.4: The 'surrogatepass' error handlers now works with utf-16* and utf-32* codecs.

Нове в версії 3.5: Обробник помилок 'namereplace.

Змінено в версії 3.5: The 'backslashreplace' error handlers now works with decoding and translating.

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

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)

Implements the 'strict' error handling: each encoding or decoding error raises a UnicodeError.

codecs.replace_errors(exception)

Implements the 'replace' error handling (for text encodings only): substitutes '?' for encoding errors (to be encoded by the codec), and '\ufffd' (the Unicode replacement character) for decoding errors.

codecs.ignore_errors(exception)

Implements the 'ignore' error handling: malformed data is ignored and encoding or decoding is continued without further notice.

codecs.xmlcharrefreplace_errors(exception)

Implements the 'xmlcharrefreplace' error handling (for encoding with text encodings only): the unencodable character is replaced by an appropriate XML character reference.

codecs.backslashreplace_errors(exception)

Implements the 'backslashreplace' error handling (for text encodings only): malformed data is replaced by a backslashed escape sequence.

codecs.namereplace_errors(exception)

Implements the 'namereplace' error handling (for encoding with text encodings only): the unencodable character is replaced by a \N{...} escape sequence.

Нове в версії 3.5.

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

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

Codec.encode(input[, errors])

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

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

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

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

Codec.decode(input[, errors])

Декодує об’єкт 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])

Кодує об’єкт (з урахуванням поточного стану кодувальника) і повертає отриманий закодований об’єкт. Якщо це останній виклик 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])

Декодує об’єкт (з урахуванням поточного стану декодера) і повертає отриманий декодований об’єкт. Якщо це останній виклик 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)

Writes the concatenated list of strings to the stream (possibly by reusing the write() method). The standard bytes-to-bytes codecs do not support this method.

reset()

Flushes and resets the codec buffers used for keeping state.

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

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

Об’єкти StreamReader

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

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

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

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

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

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

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

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

read([size[, chars[, firstline]]])

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

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

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

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

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

readline([size[, keepends]])

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

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

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

readlines([sizehint[, keepends]])

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

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

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

reset()

Resets the codec buffers used for keeping state.

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

Окрім вищезазначених методів, 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

Strings are stored internally as sequences of code points in range 0x0–0x10FFFF. (See PEP 393 for more details about the implementation.) Once a string object is used outside of CPU and memory, endianness and how these arrays are stored as bytes become an issue. As with other codecs, serialising a string into a sequence of bytes is known as encoding, and recreating the string from the sequence of bytes is known as decoding. There are a variety of different text serialisation codecs, which are collectivity referred to as text encodings.

Найпростіше кодування тексту (називається '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 e.g. you use UTF-32-BE on a little endian machine you will always have to swap bytes on encoding and decoding. UTF-32 avoids this problem: bytes will always be in natural endianness. When these bytes are read by a CPU with a different endianness, then bytes have to be swapped though. To be able to detect the endianness of a UTF-16 or UTF-32 byte sequence, there’s the so called BOM («Byte Order Mark»). 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. So when the first character in an UTF-16 or UTF-32 byte sequence appears to be a 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.

There’s another encoding that is able to encoding the full range of Unicode characters: UTF-8. UTF-8 is an 8-bit encoding, which means there are no issues with byte order in UTF-8. Each byte in a UTF-8 byte sequence consists of two parts: marker bits (the most significant bits) and payload bits. The marker bits are a sequence of zero to four 1 bits followed by a 0 bit. Unicode characters are encoded like this (with x being payload bits, which when concatenated give the Unicode character):

Діапазон	Кодування
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 у декодованому рядку (навіть якщо це перший символ) розглядається як НУЛЬОВА ШИРИНА БЕЗ РОЗБИВУ .

Without external information it’s impossible to reliably determine which encoding was used for encoding a string. Each charmap encoding can decode any random byte sequence. However that’s not possible with UTF-8, as UTF-8 byte sequences have a structure that doesn’t allow arbitrary byte sequences. To increase the reliability with which a UTF-8 encoding can be detected, Microsoft invented a variant of UTF-8 (that Python 2.5 calls "utf-8-sig") for its Notepad program: Before any of the Unicode characters is written to the file, a UTF-8 encoded BOM (which looks like this as a byte sequence: 0xef, 0xbb, 0xbf) is written. As it’s rather improbable that any charmap encoded file starts with these byte values (which would e.g. map to

МАЛА ЛАТИНСЬКА БУКВА I З ДІАРЕЗИСОМ

ПОДВІЙНІ КУТНІ ЛАПКИ, Спрямовані вправо

ПЕРЕВЕРНУТИЙ ЗНАК ПИТАННЯ

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

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

Python поставляється з низкою вбудованих кодеків, реалізованих як функції C або зі словниками як таблиці відображення. У наведеній нижче таблиці наведено кодеки за назвами разом із кількома поширеними псевдонімами та мовами, для яких, ймовірно, використовується кодування. Ні список псевдонімів, ні список мов не є вичерпними. Зауважте, що варіанти написання, які відрізняються лише регістром або використовують дефіс замість підкреслення, також є дійсними псевдонімами; отже, напр. 'utf-8'' є дійсним псевдонімом для 'utf_8'' кодека.

CPython implementation detail: Деякі поширені кодування можуть обійти механізм пошуку кодеків для підвищення продуктивності. Ці можливості оптимізації розпізнаються 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	Німецький Нове в версії 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	болгарська, білоруська, македонська, російська, сербська
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	Японський
cp949	949, ms949, uhc	корейська
cp950	950, мс950	Традиційний китайський
cp1006		урду
cp1026	ibm1026	турецька
cp1125	1125, ibm1125, cp866u, рос	українська Нове в версії 3.4.
cp1140	ibm1140	Західна Європа
cp1250	вікна-1250	Центральна та Східна Європа
cp1251	вікна-1251	болгарська, білоруська, македонська, російська, сербська
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	Балтійські мови
iso8859_5	iso-8859-5, кирил	болгарська, білоруська, македонська, російська, сербська
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		таджицька Нове в версії 3.5.
koi8_u		українська
kz1048	kz_1048, strk1048_2002, rk1048	казахська Нове в версії 3.5.
mac_cyrillic	макирилицею	болгарська, білоруська, македонська, російська, сербська
mac_greek	макгрік	грецька
mac_iceland	maciceland	ісландська
mac_latin2	maclatin2, maccentraleurope	Центральна та Східна Європа
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		всі мови

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

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

Спеціальні кодування 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). Нове в версії 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.
невизначений		Викликати виняток для всіх перетворень, навіть для порожніх рядків. Обробник помилок ігнорується.
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.	uu.encode() / uu.decode()
zlib_codec	zip, zlib	Стисніть операнд за допомогою gzip.	zlib.compress() / zlib.decompress()

1

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

Нове в версії 3.2: Відновлення двійкових перетворень.

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

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

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

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

Нове в версії 3.2: Відновлення текстового перетворення rot_13.

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

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 <https://pypi.org/project/idna/>_.

Ці 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 only.

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

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

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

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