`unicode.md`

753 строк · 65.4 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/2.7/c-api/unicode.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты Unicode и кодеки89## Объекты Unicode1011### Тип Unicode1213Это основные типы объектов Unicode, используемые в реализации Unicode в Python:1415**`Py_UNICODE`**1617Этот тип представляет собой тип хранения, который используется внутри Python для хранения кодовых точек Unicode. В сборках Python по умолчанию для [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) используется 16-битный тип, и значения Unicode хранятся внутри как UCS2. Также можно собрать версию Python UCS4 (большинство современных дистрибутивов Linux поставляются со сборками Python UCS4). В этих сборках для [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) используется 32-битный тип, и данные Unicode хранятся внутри как UCS4. На платформах, где `wchar_t` доступен и совместим с выбранным вариантом сборки Unicode Python, [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) является псевдонимом typedef для `wchar_t` для повышения совместимости с родной платформой. На всех остальных платформах [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) является псевдонимом typedef для `unsigned short` (UCS2) или `unsigned long` (UCS4).1819Обратите внимание, что сборки Python с UCS2 и UCS4 не являются двоично совместимыми. Учитывайте это при написании расширений или интерфейсов.2021**`PyUnicodeObject`**2223Этот подтип [`PyObject`](https://python-all.ru/2.7/c-api/structures.html#c.PyObject) представляет собой объект Unicode Python.2425**[PyTypeObject](https://python-all.ru/2.7/c-api/type.html#c.PyTypeObject) `PyUnicode_Type`**2627Этот экземпляр [`PyTypeObject`](https://python-all.ru/2.7/c-api/type.html#c.PyTypeObject) представляет тип Unicode Python. Он доступен в коде Python как `unicode` и `types.UnicodeType`.2829Следующие API на самом деле являются макросами C и могут использоваться для быстрых проверок и доступа к внутренним данным Unicode объектов только для чтения:3031#### `int PyUnicode_Check(PyObject *o)`3233Возвращает true, если объект *o* является объектом Unicode или экземпляром подтипа Unicode.3435Изменено в версии 2.2: Теперь допускаются подтипы.3637#### `int PyUnicode_CheckExact(PyObject *o)`3839Возвращает true, если объект *o* является объектом Unicode, но не экземпляром подтипа.4041Новое в версии 2.2.4243#### `Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)`4445Возвращает размер объекта. *o* должен быть [`PyUnicodeObject`](https://python-all.ru/2.7/c-api/unicode.html#c.PyUnicodeObject) (не проверяется).4647Изменено в версии 2.5: Эта функция возвращала тип `int`. Возможно, потребуется внести изменения в код для корректной поддержки 64-битных систем.4849#### `Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)`5051Возвращает размер внутреннего буфера объекта в байтах. *o* должен быть [`PyUnicodeObject`](https://python-all.ru/2.7/c-api/unicode.html#c.PyUnicodeObject) (не проверяется).5253Изменено в версии 2.5: Эта функция возвращала тип `int`. Возможно, потребуется внести изменения в код для корректной поддержки 64-битных систем.5455#### `Py_UNICODE* PyUnicode_AS_UNICODE(PyObject*o)`5657Возвращает указатель на внутренний буфер [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) объекта. *o* должен быть [`PyUnicodeObject`](https://python-all.ru/2.7/c-api/unicode.html#c.PyUnicodeObject) (не проверяется).5859#### `const char* PyUnicode_AS_DATA(PyObject*o)`6061Возвращает указатель на внутренний буфер объекта. *o* должен быть [`PyUnicodeObject`](https://python-all.ru/2.7/c-api/unicode.html#c.PyUnicodeObject) (не проверяется).6263#### `int PyUnicode_ClearFreeList()`6465Очищает список свободных элементов. Возвращает общее количество освобождённых элементов.6667Новое в версии 2.6.6869### Свойства символов Unicode7071Unicode предоставляет множество различных свойств символов. Наиболее востребованные из них доступны через следующие макросы, которые сопоставляются с функциями на C в зависимости от конфигурации Python.7273#### `int Py_UNICODE_ISSPACE(Py_UNICODE ch)`7475Возвращает `1` или `0` в зависимости от того, является ли *ch* пробельным символом.7677#### `int Py_UNICODE_ISLOWER(Py_UNICODE ch)`7879Возвращает `1` или `0` в зависимости от того, является ли *ch* символом в нижнем регистре.8081#### `int Py_UNICODE_ISUPPER(Py_UNICODE ch)`8283Возвращает `1` или `0` в зависимости от того, является ли *ch* символом в верхнем регистре.8485#### `int Py_UNICODE_ISTITLE(Py_UNICODE ch)`8687Возвращает `1` или `0` в зависимости от того, является ли *ch* символом в регистре заголовка (titlecase).8889#### `int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)`9091Возвращает `1` или `0` в зависимости от того, является ли *ch* символом разрыва строки.9293#### `int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)`9495Возвращает `1` или `0` в зависимости от того, является ли *ch* десятичным символом.9697#### `int Py_UNICODE_ISDIGIT(Py_UNICODE ch)`9899Возвращает `1` или `0` в зависимости от того, является ли *ch* цифровым символом.100101#### `int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)`102103Возвращает `1` или `0` в зависимости от того, является ли *ch* числовым символом.104105#### `int Py_UNICODE_ISALPHA(Py_UNICODE ch)`106107Возвращает `1` или `0` в зависимости от того, является ли *ch* буквенным символом.108109#### `int Py_UNICODE_ISALNUM(Py_UNICODE ch)`110111Возвращает `1` или `0` в зависимости от того, является ли *ch* буквенно-цифровым символом.112113Эти API можно использовать для быстрых прямых преобразований символов:114115#### `Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)`116117Возвращает символ *ch*, преобразованный в нижний регистр.118119#### `Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)`120121Возвращает символ *ch*, преобразованный в верхний регистр.122123#### `Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)`124125Возвращает символ *ch*, приведённый к регистру заголовка.126127#### `int Py_UNICODE_TODECIMAL(Py_UNICODE ch)`128129Возвращает символ *ch*, преобразованный в десятичное положительное целое. Возвращает `-1`, если это невозможно. Этот макрос не вызывает исключений.130131#### `int Py_UNICODE_TODIGIT(Py_UNICODE ch)`132133Возвращает символ *ch*, преобразованный в целое однозначное число. Возвращает `-1`, если это невозможно. Этот макрос не вызывает исключений.134135#### `double Py_UNICODE_TONUMERIC(Py_UNICODE ch)`136137Возвращает символ *ch*, преобразованный в double. Возвращает `-1.0`, если это невозможно. Этот макрос не вызывает исключений.138139### Простой Py\_UNICODE140141Для создания объектов Unicode и доступа к их базовым свойствам последовательности используйте следующие API:142143#### `PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)`144145*Возвращаемое значение: новая ссылка.*146147Создаёт объект Unicode из буфера Py\_UNICODE *u* указанного размера. *u* может быть *NULL*, что делает содержимое неопределённым. Ответственность за заполнение нужными данными лежит на пользователе. Буфер копируется в новый объект. Если буфер не равен *NULL*, возвращаемое значение может быть разделяемым объектом. Поэтому изменение результирующего объекта Unicode допускается только когда *u* равно *NULL*.148149Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.150151#### `PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)`152153*Возвращаемое значение: новая ссылка.*154155Создаёт объект Unicode из буфера char *u*. Байты интерпретируются как кодировка UTF-8. *u* также может быть *NULL*, что делает содержимое неопределённым. Ответственность за заполнение нужными данными лежит на пользователе. Буфер копируется в новый объект. Если буфер не равен *NULL*, возвращаемое значение может быть разделяемым объектом. Поэтому изменение результирующего объекта Unicode допускается только когда *u* равно *NULL*.156157Новое в версии 2.6.158159#### `PyObject *PyUnicode_FromString(const char *u)`160161*Возвращаемое значение: новая ссылка.*162163Создаёт объект Unicode из UTF-8-закодированного нуль-терминированного буфера символов *u*.164165Новое в версии 2.6.166167#### `PyObject* PyUnicode_FromFormat(const char *format, ...)`168169*Возвращаемое значение: новая ссылка.*170171Принимает строку формата в стиле C `printf()` *формата* и переменное количество аргументов, вычисляет размер результирующей строки Python unicode и возвращает строку с отформатированными значениями. Переменные аргументы должны быть типами C и должны точно соответствовать символам формата в строке *формата*. Допускаются следующие символы формата:172173| Символы формата | Тип | Описание |174| --- | --- | --- |175| `%%` | *н/д* | Буквальный символ %. |176| `%c` | int | Один символ, представленный как C int. |177| `%d` | int | Полностью эквивалентно `printf("%d")`. |178| `%u` | беззнаковый int | Полностью эквивалентно `printf("%u")`. |179| `%ld` | long | Полностью эквивалентно `printf("%ld")`. |180| `%lu` | беззнаковый long | Полностью эквивалентно `printf("%lu")`. |181| `%zd` | Py\_ssize\_t | Полностью эквивалентно `printf("%zd")`. |182| `%zu` | size\_t | Полностью эквивалентно `printf("%zu")`. |183| `%i` | int | Полностью эквивалентно `printf("%i")`. |184| `%x` | int | Полностью эквивалентно `printf("%x")`. |185| `%s` | char\* | Нуль-терминированный массив символов C. |186| `%p` | void\* | Шестнадцатеричное представление указателя C. В основном эквивалентно `printf("%p")`, за исключением того, что гарантированно начинается с литерала `0x` независимо от того, что возвращает `printf` на данной платформе. |187| `%U` | PyObject\* | Unicode-объект. |188| `%V` | PyObject\*, char \* | Unicode-объект (может быть *NULL*) и завершающийся нулевым символом C-массив символов в качестве второго параметра (используется, если первый параметр равен *NULL*). |189| `%S` | PyObject\* | Результат вызова `PyObject_Unicode()`. |190| `%R` | PyObject\* | Результат вызова `PyObject_Repr()`. |191192Нераспознанный символ формата приводит к тому, что вся оставшаяся строка формата копируется как есть в результирующую строку, а все лишние аргументы отбрасываются.193194Новое в версии 2.6.195196#### `PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)`197198*Возвращаемое значение: новая ссылка.*199200Идентично `PyUnicode_FromFormat()`, за исключением того, что принимает ровно два аргумента.201202Новое в версии 2.6.203204#### `Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)`205206Возвращает указатель только для чтения на внутренний буфер [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) объекта Unicode, *NULL*, если *unicode* не является объектом Unicode. Обратите внимание, что результирующая строка [`Py_UNICODE*`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) может содержать встроенные нулевые символы, что приведёт к усечению строки при использовании в большинстве функций C.207208#### `Py_ssize_t PyUnicode_GetSize(PyObject *unicode)`209210Возвращает длину объекта Unicode.211212Изменено в версии 2.5: Эта функция возвращала тип `int`. Возможно, потребуется внести изменения в код для корректной поддержки 64-битных систем.213214#### `PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)`215216*Возвращаемое значение: новая ссылка.*217218Приводит закодированный объект *obj* к объекту Unicode и возвращает ссылку с увеличенным счётчиком ссылок.219220Строки и другие объекты, совместимые с символьными буферами, декодируются в соответствии с заданной кодировкой и с использованием обработки ошибок, определённой параметром errors. Оба параметра могут быть *NULL*, чтобы интерфейс использовал значения по умолчанию (подробнее см. следующий раздел).221222Все остальные объекты, включая объекты Unicode, приводят к установке [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError).223224API возвращает *NULL* при ошибке. Вызывающий отвечает за уменьшение счётчика ссылок возвращённых объектов.225226#### `PyObject* PyUnicode_FromObject(PyObject *obj)`227228*Возвращаемое значение: новая ссылка.*229230Сокращение для `PyUnicode_FromEncodedObject(obj, NULL, "strict")`, которое используется во всём интерпретаторе, когда требуется приведение к Unicode.231232Если платформа поддерживает `wchar_t` и предоставляет заголовочный файл wchar.h, Python может напрямую взаимодействовать с этим типом, используя следующие функции. Поддержка оптимизирована, если собственный тип Python [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) идентичен системному `wchar_t`.233234### Поддержка wchar\_t235236`wchar_t` поддержка на платформах, которые её поддерживают:237238#### `PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)`239240*Возвращаемое значение: новая ссылка.*241242Создаёт объект Unicode из буфера `wchar_t` *w* заданного *размера*. Возвращает *NULL* в случае ошибки.243244Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.245246#### `Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size)`247248Копирует содержимое объекта Unicode в буфер `wchar_t` *w*. Копируется не более *size* символов `wchar_t` (исключая возможный завершающий нулевой символ). Возвращает количество скопированных символов `wchar_t` или `-1` в случае ошибки. Обратите внимание, что результирующая строка `wchar_t` может быть или не быть завершена нулём. Ответственность вызывающего – убедиться, что строка `wchar_t` завершена нулём, если это требуется приложением. Также обратите внимание, что строка `wchar_t*` может содержать нулевые символы, что приведёт к усечению строки при использовании с большинством функций C.249250Изменено в версии 2.5: Эта функция возвращала тип `int` и использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для правильной поддержки 64-битных систем.251252## Встроенные кодеки253254Python предоставляет набор встроенных кодеков, написанных на C для скорости. Все эти кодеки могут использоваться напрямую через следующие функции.255256Многие из следующих API принимают два аргумента: encoding и errors, и имеют ту же семантику, что и аргументы встроенного конструктора объекта Unicode [`unicode()`](https://python-all.ru/2.7/library/functions.html#unicode).257258Установка кодировки в *NULL* приводит к использованию кодировки по умолчанию, а именно ASCII. Системные вызовы файловой системы должны использовать `Py_FileSystemDefaultEncoding` в качестве кодировки для имён файлов. Эту переменную следует рассматривать как доступную только для чтения: в некоторых системах это будет указатель на статическую строку, в других она будет изменяться во время выполнения (например, когда приложение вызывает setlocale).259260Обработка ошибок задаётся параметром errors, который также может быть установлен в *NULL*, что означает использование обработки по умолчанию, определённой для кодека. Обработка ошибок по умолчанию для всех встроенных кодеков – «strict» (возбуждается [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError)).261262Все кодеки используют похожий интерфейс. Для простоты документированы только отклонения от следующего общего описания.263264### Общие кодеки265266Это общие API кодеков:267268#### `PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)`269270*Возвращаемое значение: новая ссылка.*271272Создаёт объект Unicode путём декодирования *size* байт закодированной строки *s*. *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры во встроенной функции [`unicode()`](https://python-all.ru/2.7/library/functions.html#unicode). Используемый кодек ищется с помощью реестра кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.273274Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.275276#### `PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)`277278*Возвращаемое значение: новая ссылка.*279280Кодирует буфер [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) *s* заданного размера *size* и возвращает объект строки Python. *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры в методе Unicode `encode()`. Используемый кодек ищется в реестре кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.281282Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.283284#### `PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)`285286*Возвращаемое значение: новая ссылка.*287288Кодирует объект Unicode и возвращает результат в виде объекта строки Python. *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры в методе Unicode `encode()`. Используемый кодек ищется в реестре кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.289290### Кодеки UTF-8291292Это API кодеков UTF-8:293294#### `PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)`295296*Возвращаемое значение: новая ссылка.*297298Создаёт объект Unicode путём декодирования *size* байт строки, закодированной в UTF-8, *s*. Возвращает *NULL*, если кодек возбудил исключение.299300Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.301302#### `PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`303304*Возвращаемое значение: новая ссылка.*305306Если *consumed* равно *NULL*, ведёт себя как [`PyUnicode_DecodeUTF8()`](https://python-all.ru/2.7/c-api/unicode.html#c.PyUnicode_DecodeUTF8). Если *consumed* не равно *NULL*, концевые неполные последовательности байт UTF-8 не будут считаться ошибкой. Эти байты не будут декодированы, а количество байт, которые были декодированы, будет сохранено в *consumed*.307308Новое в версии 2.4.309310Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.311312#### `PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`313314*Возвращаемое значение: новая ссылка.*315316Кодирует буфер [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) *s* заданного размера *size* с помощью UTF-8 и возвращает объект строки Python. Возвращает *NULL*, если кодек возбудил исключение.317318Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.319320#### `PyObject* PyUnicode_AsUTF8String(PyObject *unicode)`321322*Возвращаемое значение: новая ссылка.*323324Кодирует объект Unicode с использованием UTF-8 и возвращает результат в виде строки Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек возбудил исключение.325326### Кодеки UTF-32327328Это API кодеков UTF-32:329330#### `PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)`331332Декодирует *size* байт из строки буфера в кодировке UTF-32 и возвращает соответствующий объект Unicode. *errors* (если не *NULL*) определяет обработку ошибок. По умолчанию используется «strict».333334Если *byteorder* не равен *NULL*, декодер начинает декодирование с использованием заданного порядка байтов:335336```c337*byteorder == -1: little endian338*byteorder == 0:  native order339*byteorder == 1:  big endian340```341342Если `*byteorder` равен нулю и первые четыре байта входных данных являются маркером порядка байтов (BOM), декодер переключается на этот порядок байтов, и BOM не копируется в результирующую строку Unicode. Если `*byteorder` равно `-1` или `1`, любой маркер порядка байтов копируется в выходные данные.343344После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных.345346В сборке с узкими символами (narrow build) кодовые точки за пределами BMP будут декодированы как суррогатные пары.347348Если *byteorder* равен *NULL*, кодек запускается в режиме собственного порядка байтов.349350Возвращает *NULL*, если кодек сгенерировал исключение.351352Новое в версии 2.6.353354#### `PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)`355356Если *consumed* равен *NULL*, ведёт себя как [`PyUnicode_DecodeUTF32()`](https://python-all.ru/2.7/c-api/unicode.html#c.PyUnicode_DecodeUTF32). Если *consumed* не равен *NULL*, [`PyUnicode_DecodeUTF32Stateful()`](https://python-all.ru/2.7/c-api/unicode.html#c.PyUnicode_DecodeUTF32Stateful) не будет считать неполные завершающие последовательности байт UTF-32 (например, количество байт, не кратное четырём) ошибкой. Эти байты не будут декодированы, а количество декодированных байт будет сохранено в *consumed*.357358Новое в версии 2.6.359360#### `PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)`361362Возвращает объект Python bytes, содержащий значение Unicode-данных из *s*, закодированное в UTF-32. Вывод записывается в соответствии со следующим порядком байтов:363364```c365byteorder == -1: little endian366byteorder == 0:  native byte order (writes a BOM mark)367byteorder == 1:  big endian368```369370Если `0`, выходная строка всегда начинается с метки BOM Unicode (U+FEFF). В двух других режимах метка BOM не добавляется.371372Если *Py\_UNICODE\_WIDE* не определён, суррогатные пары будут выводиться как одна кодовая точка.373374Возвращает *NULL*, если кодек сгенерировал исключение.375376Новое в версии 2.6.377378#### `PyObject* PyUnicode_AsUTF32String(PyObject *unicode)`379380Возвращает строку Python, закодированную в UTF-32 с native порядком байтов. Строка всегда начинается с маркера BOM. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.381382Новое в версии 2.6.383384### Кодеки UTF-32385386Это API кодеков UTF-32:387388#### `PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)`389390*Возвращаемое значение: новая ссылка.*391392Декодирует *size* байт из строки буфера в кодировке UTF-16 и возвращает соответствующий объект Unicode. *errors* (если не *NULL*) определяет обработку ошибок. По умолчанию используется «strict».393394Если *byteorder* не равен *NULL*, декодер начинает декодирование с использованием заданного порядка байтов:395396```c397*byteorder == -1: little endian398*byteorder == 0:  native order399*byteorder == 1:  big endian400```401402Если `*byteorder` равен нулю и первые два байта входных данных являются меткой порядка байтов (BOM), декодер переключается на этот порядок байтов, а BOM не копируется в результирующую строку Unicode. Если `*byteorder` равен `-1` или `1`, любая метка порядка байтов копируется в выходные данные (что приведёт к символу `\ufeff` или `\ufffe`).403404После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных.405406Если *byteorder* равен *NULL*, кодек запускается в режиме собственного порядка байтов.407408Возвращает *NULL*, если кодек сгенерировал исключение.409410Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.411412#### `PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)`413414*Возвращаемое значение: новая ссылка.*415416Если *consumed* равен *NULL*, ведёт себя как [`PyUnicode_DecodeUTF16()`](https://python-all.ru/2.7/c-api/unicode.html#c.PyUnicode_DecodeUTF16). Если *consumed* не равен *NULL*, [`PyUnicode_DecodeUTF16Stateful()`](https://python-all.ru/2.7/c-api/unicode.html#c.PyUnicode_DecodeUTF16Stateful) не будет считать неполные завершающие последовательности байт UTF-16 (например, нечётное количество байт или разделённую суррогатную пару) ошибкой. Эти байты не будут декодированы, а количество декодированных байт будет сохранено в *consumed*.417418Новое в версии 2.4.419420Изменено в версии 2.5: Эта функция использовала тип `int` для *size* и тип `int *` для *consumed*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.421422#### `PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)`423424*Возвращаемое значение: новая ссылка.*425426Возвращает объект строки Python, содержащий значение в кодировке UTF-16 для данных Unicode в *s*. Вывод записывается в следующем порядке байтов:427428```c429byteorder == -1: little endian430byteorder == 0:  native byte order (writes a BOM mark)431byteorder == 1:  big endian432```433434Если `0`, выходная строка всегда начинается с метки BOM Unicode (U+FEFF). В двух других режимах метка BOM не добавляется.435436Если *Py\_UNICODE\_WIDE* определён, одно значение [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) может быть представлено как суррогатная пара. Если он не определён, каждое значение [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) интерпретируется как символ UCS-2.437438Возвращает *NULL*, если кодек сгенерировал исключение.439440Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.441442#### `PyObject* PyUnicode_AsUTF16String(PyObject *unicode)`443444*Возвращаемое значение: новая ссылка.*445446Возвращает строку Python, закодированную в UTF-16 с native порядком байтов. Строка всегда начинается с маркера BOM. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.447448### Кодеки UTF-7449450Это API кодеков UTF-7:451452#### `PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)`453454Создаёт объект Unicode путём декодирования *size* байт строки в кодировке UTF-7 *s*. Возвращает *NULL*, если кодек сгенерировал исключение.455456#### `PyObject* PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`457458Если *consumed* равен *NULL*, ведёт себя как [`PyUnicode_DecodeUTF7()`](https://python-all.ru/2.7/c-api/unicode.html#c.PyUnicode_DecodeUTF7). Если *consumed* не равен *NULL*, завершающие неполные секции base-64 UTF-7 не будут считаться ошибкой. Эти байты не будут декодированы, а количество декодированных байт будет сохранено в *consumed*.459460#### `PyObject* PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)`461462Кодирует буфер [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) заданного размера с использованием UTF-7 и возвращает объект Python bytes. Возвращает *NULL*, если кодек сгенерировал исключение.463464Если *base64SetO* не равно нулю, «Set O» (знаки препинания, не имеющие иного особого значения) будут закодированы в base-64. Если *base64WhiteSpace* не равно нулю, пробельные символы будут закодированы в base-64. Оба параметра установлены в ноль для кодека Python «utf-7».465466### Кодеки Unicode-Escape467468Это API кодеков «Unicode Escape»:469470#### `PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)`471472*Возвращаемое значение: новая ссылка.*473474Создаёт объект Unicode путём декодирования *size* байт строки в кодировке Unicode-Escape *s*. Возвращает *NULL*, если кодек сгенерировал исключение.475476Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.477478#### `PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)`479480*Возвращаемое значение: новая ссылка.*481482Кодирует буфер [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) заданного размера *size* с помощью Unicode-Escape и возвращает объект строки Python. Возвращает *NULL*, если кодек возбудил исключение.483484Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.485486#### `PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)`487488*Возвращаемое значение: новая ссылка.*489490Кодирует объект Unicode с использованием Unicode-Escape и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.491492### Кодеки Raw-Unicode-Escape493494Это API кодеков «Raw Unicode Escape»:495496#### `PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)`497498*Возвращаемое значение: новая ссылка.*499500Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в Raw-Unicode-Escape. Возвращает *NULL*, если кодек вызвал исключение.501502Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.503504#### `PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`505506*Возвращаемое значение: новая ссылка.*507508Кодирует буфер [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) заданного размера *size* с помощью Raw-Unicode-Escape и возвращает объект строки Python. Возвращает *NULL*, если кодек возбудил исключение.509510Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.511512#### `PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)`513514*Возвращаемое значение: новая ссылка.*515516Кодирует объект Unicode с использованием Raw-Unicode-Escape и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.517518### Кодеки Latin-1519520Это API кодеков Latin-1: Latin-1 соответствует первым 256 кодовым позициям Unicode, и только они принимаются кодеками при кодировании.521522#### `PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)`523524*Возвращаемое значение: новая ссылка.*525526Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в Latin-1. Возвращает *NULL*, если кодек вызвал исключение.527528Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.529530#### `PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`531532*Возвращаемое значение: новая ссылка.*533534Кодирует буфер [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) заданного размера *size* с помощью Latin-1 и возвращает объект строки Python. Возвращает *NULL*, если кодек возбудил исключение.535536Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.537538#### `PyObject* PyUnicode_AsLatin1String(PyObject *unicode)`539540*Возвращаемое значение: новая ссылка.*541542Кодирует объект Unicode с помощью Latin-1 и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.543544### Кодеки ASCII545546Это API кодеков ASCII. Принимаются только 7-битные данные ASCII. Все остальные коды вызывают ошибки.547548#### `PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)`549550*Возвращаемое значение: новая ссылка.*551552Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в ASCII. Возвращает *NULL*, если кодек вызвал исключение.553554Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.555556#### `PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`557558*Возвращаемое значение: новая ссылка.*559560Кодирует буфер [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) заданного размера *size* с помощью ASCII и возвращает объект строки Python. Возвращает *NULL*, если кодек возбудил исключение.561562Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.563564#### `PyObject* PyUnicode_AsASCIIString(PyObject *unicode)`565566*Возвращаемое значение: новая ссылка.*567568Кодирует объект Unicode с помощью ASCII и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.569570### Кодеки с таблицей символов571572Этот кодек особенный тем, что его можно использовать для реализации многих различных кодеков (и именно так были получены большинство стандартных кодеков, входящих в пакет `encodings`). Кодек использует отображение для кодирования и декодирования символов.573574Отображения для декодирования должны сопоставлять отдельные символы строки отдельным символам Unicode, целым числам (которые затем интерпретируются как кодовые точки Unicode) или `None` (что означает «неопределённое отображение» и вызывает ошибку).575576Отображения для кодирования должны сопоставлять отдельные символы Unicode отдельным символам строки, целым числам (которые затем интерпретируются как кодовые точки Latin-1) или `None` (что означает «неопределённое отображение» и вызывает ошибку).577578Объекты отображения должны поддерживать только интерфейс отображения \_\_getitem\_\_.579580Если при поиске символа возникает LookupError, символ копируется как есть; это означает, что его порядковое значение будет интерпретироваться как кодовая точка Unicode или Latin-1 соответственно. Из-за этого отображения должны содержать только те соответствия, которые переводят символы в другие кодовые точки.581582Это API кодеков отображения:583584#### `PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors)`585586*Возвращаемое значение: новая ссылка.*587588Создаёт объект Unicode, декодируя *size* байт закодированной строки *s* с помощью заданного объекта *mapping*. Возвращает *NULL*, если кодек вызвал исключение. Если *mapping* равен *NULL*, выполняется декодирование Latin-1. В противном случае это может быть словарь, отображающий байты, или строка Unicode, которая интерпретируется как таблица поиска. Значения байтов, превышающие длину строки, и «символ» U+FFFE считаются «неопределённым отображением».589590Изменено в версии 2.4: Разрешена строка Unicode в качестве аргумента отображения.591592Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.593594#### `PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)`595596*Возвращаемое значение: новая ссылка.*597598Кодирует буфер [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) заданного размера *size* с помощью заданного объекта отображения *mapping* и возвращает объект строки Python. Возвращает *NULL*, если кодек возбудил исключение.599600Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.601602#### `PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)`603604*Возвращаемое значение: новая ссылка.*605606Кодирует объект Unicode с помощью заданного объекта *mapping* и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.607608Следующее API кодека особенное тем, что отображает Unicode в Unicode.609610#### `PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *table, const char *errors)`611612*Возвращаемое значение: новая ссылка.*613614Преобразует буфер [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) заданного размера *size*, применяя к нему отображение символов *table*, и возвращает результирующий объект Unicode. Возвращает *NULL*, если кодек возбудил исключение.615616Таблица отображения *mapping* должна сопоставлять целочисленные кодовые точки Unicode другим целочисленным кодовым точкам Unicode или `None` (что приводит к удалению символа).617618Таблицы отображения должны лишь предоставлять интерфейс [`__getitem__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__getitem__); словари и последовательности работают хорошо. Неотображённые кодовые позиции символов (те, которые вызывают [`LookupError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.LookupError)) остаются нетронутыми и копируются как есть.619620Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.621622### Кодеки MBCS для Windows623624Это API кодеков MBCS. В настоящее время они доступны только в Windows и используют преобразователи Win32 MBCS для выполнения преобразований. Обратите внимание, что MBCS (или DBCS) – это класс кодировок, а не одна конкретная. Целевая кодировка определяется пользовательскими настройками на машине, где выполняется кодек.625626#### `PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)`627628*Возвращаемое значение: новая ссылка.*629630Создаёт объект Unicode, декодируя *size* байтов строки, закодированной в MBCS, из *s*. Возвращает *NULL*, если кодек вызвал исключение.631632Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.633634#### `PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed)`635636Если *consumed* равен *NULL*, действует как [`PyUnicode_DecodeMBCS()`](https://python-all.ru/2.7/c-api/unicode.html#c.PyUnicode_DecodeMBCS). Если *consumed* не равен *NULL*, [`PyUnicode_DecodeMBCSStateful()`](https://python-all.ru/2.7/c-api/unicode.html#c.PyUnicode_DecodeMBCSStateful) не будет декодировать замыкающий ведущий байт, а количество декодированных байтов будет сохранено в *consumed*.637638Новое в версии 2.5.639640#### `PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`641642*Возвращаемое значение: новая ссылка.*643644Кодирует буфер [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) заданного размера *size* с помощью MBCS и возвращает объект строки Python. Возвращает *NULL*, если кодек возбудил исключение.645646Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.647648#### `PyObject* PyUnicode_AsMBCSString(PyObject *unicode)`649650*Возвращаемое значение: новая ссылка.*651652Кодирует объект Unicode, используя MBCS, и возвращает результат в виде объекта строки Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.653654### Методы и слоты655656## Методы и слот-функции657658Следующие API могут обрабатывать объекты Unicode и строки на входе (в описаниях мы называем их строками) и возвращают объекты Unicode или целые числа по необходимости.659660Все они возвращают *NULL* или `-1` в случае исключения.661662#### `PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)`663664*Возвращаемое значение: новая ссылка.*665666Объединяет две строки, возвращая новую строку Unicode.667668#### `PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)`669670*Возвращаемое значение: новая ссылка.*671672Разделяет строку и возвращает список строк Unicode. Если *sep* равен *NULL*, разделение происходит по всем подстрокам из пробельных символов. В противном случае разделение выполняется по указанному разделителю. Выполняется не более *maxsplit* разделений. Если значение отрицательное, ограничение не устанавливается. Разделители не включаются в результирующий список.673674Изменено в версии 2.5: Эта функция использовала тип `int` для *maxsplit*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.675676#### `PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)`677678*Возвращаемое значение: новая ссылка.*679680Разделяет строку Unicode по символам перевода строки и возвращает список строк Unicode. CRLF считается одним переносом строки. Если *keepend* равно `0`, символы перевода строки не включаются в результирующие строки.681682#### `PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)`683684*Возвращаемое значение: новая ссылка.*685686Переводит строку, применяя к ней таблицу отображения символов, и возвращает результирующий объект Unicode.687688Таблица отображения должна отображать целые числа – кодовые позиции Unicode – в целые числа – кодовые позиции Unicode – или в `None` (вызывает удаление символа).689690Таблицы отображения должны лишь предоставлять интерфейс [`__getitem__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__getitem__); словари и последовательности работают хорошо. Неотображённые кодовые позиции символов (те, которые вызывают [`LookupError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.LookupError)) остаются нетронутыми и копируются как есть.691692*errors* имеет обычное для кодеков значение. Может быть *NULL*, что означает использование обработки ошибок по умолчанию.693694#### `PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)`695696*Возвращаемое значение: новая ссылка.*697698Объединяет последовательность строк, используя заданный *разделитель*, и возвращает полученную Unicode-строку.699700#### `Py_ssize_t PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)`701702Возвращает `1`, если *substr* совпадает с `str[start:end]` на заданном хвосте (*direction* == `-1` означает проверку на совпадение с началом, *direction* == `1` – с концом), иначе `0`. Возвращает `-1`, если произошла ошибка.703704Изменено в версии 2.5: Эта функция использовала тип `int` для *start* и *end*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.705706#### `Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)`707708Возвращает первую позицию *substr* в `str[start:end]`, используя заданное *direction* (*direction* == `1` означает прямой поиск, *direction* == `-1` – обратный). Возвращаемое значение – индекс первого совпадения; значение `-1` означает, что совпадений не найдено, а `-2` – что произошла ошибка и было установлено исключение.709710Изменено в версии 2.5: Эта функция использовала тип `int` для *start* и *end*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.711712#### `Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)`713714Возвращает количество неперекрывающихся вхождений *substr* в `str[start:end]`. Возвращает `-1`, если произошла ошибка.715716Изменено в версии 2.5: Эта функция возвращала тип `int` и использовала тип `int` для *start* и *end*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.717718#### `PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)`719720*Возвращаемое значение: новая ссылка.*721722Заменяет не более *maxcount* вхождений *substr* в *str* на *replstr* и возвращает результирующий объект Unicode. *maxcount* == `-1` означает замену всех вхождений.723724Изменено в версии 2.5: Эта функция использовала тип `int` для *maxcount*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.725726#### `int PyUnicode_Compare(PyObject *left, PyObject *right)`727728Сравнивает две строки и возвращает `-1`, `0`, `1` для случаев меньше, равно и больше соответственно.729730#### `int PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)`731732Выполняет расширенное сравнение двух строк unicode и возвращает одно из следующих значений:733734- `NULL` в случае, если возникло исключение735- `Py_True` или `Py_False` для успешных сравнений736- `Py_NotImplemented` в случае, если комбинация типов неизвестна737738Обратите внимание, что сравнения `Py_EQ` и `Py_NE` могут вызвать [`UnicodeWarning`](https://python-all.ru/2.7/library/exceptions.html#exceptions.UnicodeWarning), если преобразование аргументов в Unicode завершится неудачей с [`UnicodeDecodeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.UnicodeDecodeError).739740Возможные значения для *op*: `Py_GT`, `Py_GE`, `Py_EQ`, `Py_NE`, `Py_LT` и `Py_LE`.741742#### `PyObject* PyUnicode_Format(PyObject *format, PyObject *args)`743744*Возвращаемое значение: новая ссылка.*745746Возвращает новый строковый объект из *format* и *args*; это аналог `format % args`.747748#### `int PyUnicode_Contains(PyObject *container, PyObject *element)`749750Проверяет, содержится ли *element* в *container*, и возвращает true или false соответственно.751752*element* должен преобразовываться в односимвольную строку Unicode. Если произошла ошибка, возвращается `-1`.753