> **Источник:** https://python-all.ru/3.16/c-api/unicode.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # Объекты Unicode и кодеки ## Объекты Unicode Начиная с реализации [**PEP 393**](https://python-all.ru/3.16/c-api/unicode.html) в Python 3.3, объекты Unicode внутри используют различные представления, чтобы обеспечить обработку полного диапазона символов Unicode, оставаясь при этом эффективными по памяти. Существуют особые случаи для строк, где все кодовые точки находятся ниже 128, 256 или 65536; в противном случае кодовые точки должны быть ниже 1114112 (то есть полного диапазона Unicode). Представление UTF-8 создаётся по требованию и кэшируется в объекте Unicode. > **Примечание** > > Представление [`Py_UNICODE`](https://python-all.ru/3.16/c-api/unicode.html#c.Py_UNICODE) было удалено начиная с Python 3.12 вместе с устаревшими API. См. [**PEP 623**](https://python-all.ru/3.16/c-api/unicode.html) для получения дополнительной информации. ### Тип Unicode Это основные типы объектов Unicode, используемые в реализации Unicode в Python: #### `PyTypeObject PyUnicode_Type` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.16/c-api/type.html#c.PyTypeObject) представляет тип Python Unicode. Он доступен в коде Python как [`str`](https://python-all.ru/3.16/library/stdtypes.html#str). #### `PyTypeObject PyUnicodeIter_Type` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.16/c-api/type.html#c.PyTypeObject) представляет тип итератора Unicode в Python. Он используется для итерации по объектам строк Unicode. #### `type Py_UCS4` #### `type Py_UCS2` #### `type Py_UCS1` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Эти типы являются псевдонимами для беззнаковых целочисленных типов, достаточно широких для хранения символов размером 32, 16 и 8 бит соответственно. При работе с отдельными символами Unicode используйте [`Py_UCS4`](https://python-all.ru/3.16/c-api/unicode.html#c.Py_UCS4). Добавлено в версии 3.3. #### `type PyASCIIObject` #### `type PyCompactUnicodeObject` #### `type PyUnicodeObject` Эти подтипы [`PyObject`](https://python-all.ru/3.16/c-api/structures.html#c.PyObject) представляют объект Unicode в Python. В почти всех случаях их не следует использовать напрямую, так как все функции API, работающие с объектами Unicode, принимают и возвращают указатели `PyObject`. Добавлено в версии 3.3. Структуру конкретного объекта можно определить с помощью следующих макросов. Макросы не завершаются ошибкой; их поведение не определено, если их аргумент не является объектом Unicode Python. #### `PyUnicode_IS_COMPACT(o)` True, если *o* использует структуру [`PyCompactUnicodeObject`](https://python-all.ru/3.16/c-api/unicode.html#c.PyCompactUnicodeObject). Добавлено в версии 3.3. #### `PyUnicode_IS_COMPACT_ASCII(o)` True, если *o* использует структуру [`PyASCIIObject`](https://python-all.ru/3.16/c-api/unicode.html#c.PyASCIIObject). Добавлено в версии 3.3. Следующие API представляют собой макросы C и статические встроенные функции для быстрых проверок и доступа к внутренним данным только для чтения объектов Unicode: #### `int PyUnicode_Check(PyObject *obj)` Возвращает true, если объект *obj* является объектом Unicode или экземпляром подтипа Unicode. Эта функция всегда завершается успешно. #### `int PyUnicode_CheckExact(PyObject *obj)` Возвращает true, если объект *obj* является объектом Unicode, но не экземпляром подтипа. Эта функция всегда завершается успешно. #### `Py_ssize_t PyUnicode_GET_LENGTH(PyObject *unicode)` Возвращает длину строки Unicode в кодовых точках. *unicode* должен быть объектом Unicode в «каноническом» представлении (не проверяется). Добавлено в версии 3.3. #### `Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *unicode)` #### `Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *unicode)` #### `Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *unicode)` Возвращает указатель на каноническое представление, приведённый к целочисленным типам UCS1, UCS2 или UCS4 для прямого доступа к символам. Не выполняется проверок, имеет ли каноническое представление правильный размер символа; используйте [`PyUnicode_KIND()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_KIND), чтобы выбрать подходящую функцию. Добавлено в версии 3.3. #### `PyUnicode_1BYTE_KIND` #### `PyUnicode_2BYTE_KIND` #### `PyUnicode_4BYTE_KIND` Возвращает значения макроса [`PyUnicode_KIND()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_KIND). Добавлено в версии 3.3. Изменено в версии 3.12: `PyUnicode_WCHAR_KIND` был удалён. #### `int PyUnicode_KIND(PyObject *unicode)` Возвращает одну из констант вида PyUnicode (см. выше), которые указывают, сколько байт на символ использует данный объект Unicode для хранения своих данных. *unicode* должен быть объектом Unicode в «каноническом» представлении (не проверяется). Добавлено в версии 3.3. #### `void *PyUnicode_DATA(PyObject *unicode)` Возвращает указатель void на сырой буфер Unicode. *unicode* должен быть объектом Unicode в «каноническом» представлении (не проверяется). Добавлено в версии 3.3. #### `void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)` Записывает кодовую точку *value* по указанному *индексу* (начиная с нуля) в строке. Значение *kind* и указатель *data* должны быть получены из строки с помощью [`PyUnicode_KIND()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_KIND) и [`PyUnicode_DATA()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DATA) соответственно. Необходимо удерживать ссылку на эту строку при вызове `PyUnicode_WRITE()`. Все требования [`PyUnicode_WriteChar()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_WriteChar) также применимы. Функция не выполняет проверок ни одного из своих требований и предназначена для использования в циклах. Добавлено в версии 3.3. #### `Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)` Читает кодовую точку из канонического представления *data* (полученного с помощью [`PyUnicode_DATA()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DATA)). Никаких проверок или вызовов готовности не выполняется. Добавлено в версии 3.3. #### `Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)` Читает символ из объекта Unicode *unicode*, который должен быть в «каноническом» представлении. Это менее эффективно, чем [`PyUnicode_READ()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_READ), если выполняется несколько последовательных чтений. Добавлено в версии 3.3. #### `Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *unicode)` Возвращает максимальную кодовую точку, подходящую для создания другой строки на основе *unicode*, который должен быть в «каноническом» представлении. Это всегда приближение, но более эффективное, чем перебор строки. Добавлено в версии 3.3. #### `int PyUnicode_IsIdentifier(PyObject *unicode)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Возвращает `1`, если строка является допустимым идентификатором согласно определению языка, раздел [Имена (идентификаторы и ключевые слова)](https://python-all.ru/3.16/reference/lexical_analysis.html#identifiers). В противном случае возвращает `0`. Изменено в версии 3.9: Функция больше не вызывает [`Py_FatalError()`](https://python-all.ru/3.16/c-api/sys.html#c.Py_FatalError), если строка не готова. #### `unsigned int PyUnicode_IS_ASCII(PyObject *unicode)` Возвращает true, если строка содержит только символы ASCII. Эквивалентно [`str.isascii()`](https://python-all.ru/3.16/library/stdtypes.html#str.isascii). Добавлено в версии 3.2. #### `Py_hash_t PyUnstable_Unicode_GET_CACHED_HASH(PyObject *str)` > *Это [нестабильное API](https://python-all.ru/3.16/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.* Если хеш *str*, возвращаемый [`PyObject_Hash()`](https://python-all.ru/3.16/c-api/object.html#c.PyObject_Hash), был кэширован и доступен немедленно, возвращает его. В противном случае возвращает `-1` *без* установки исключения. Если *str* не является строкой (то есть если `PyUnicode_Check(obj)` ложно), поведение не определено. Эта функция никогда не завершается исключением. Обратите внимание, что не гарантируется, когда кешируется хеш объекта, и наличие или отсутствие кешированного хеша не означает, что строка обладает какими-либо другими свойствами. ### Свойства символов Unicode Unicode предоставляет множество различных свойств символов. Наиболее востребованные из них доступны через следующие макросы, которые сопоставляются с функциями на C в зависимости от конфигурации Python. #### `int Py_UNICODE_ISSPACE(Py_UCS4 ch)` Возвращает `1` или `0` в зависимости от того, является ли *ch* пробельным символом. #### `int Py_UNICODE_ISLOWER(Py_UCS4 ch)` Возвращает `1` или `0` в зависимости от того, является ли *ch* символом в нижнем регистре. #### `int Py_UNICODE_ISUPPER(Py_UCS4 ch)` Возвращает `1` или `0` в зависимости от того, является ли *ch* символом в верхнем регистре. #### `int Py_UNICODE_ISTITLE(Py_UCS4 ch)` Возвращает `1` или `0` в зависимости от того, является ли *ch* символом в регистре заголовка (titlecase). #### `int Py_UNICODE_ISLINEBREAK(Py_UCS4 ch)` Возвращает `1` или `0` в зависимости от того, является ли *ch* символом разрыва строки. #### `int Py_UNICODE_ISDECIMAL(Py_UCS4 ch)` Возвращает `1` или `0` в зависимости от того, является ли *ch* десятичным символом. #### `int Py_UNICODE_ISDIGIT(Py_UCS4 ch)` Возвращает `1` или `0` в зависимости от того, является ли *ch* цифровым символом. #### `int Py_UNICODE_ISNUMERIC(Py_UCS4 ch)` Возвращает `1` или `0` в зависимости от того, является ли *ch* числовым символом. #### `int Py_UNICODE_ISALPHA(Py_UCS4 ch)` Возвращает `1` или `0` в зависимости от того, является ли *ch* буквенным символом. #### `int Py_UNICODE_ISALNUM(Py_UCS4 ch)` Возвращает `1` или `0` в зависимости от того, является ли *ch* буквенно-цифровым символом. #### `int Py_UNICODE_ISPRINTABLE(Py_UCS4 ch)` Возвращает `1` или `0` в зависимости от того, является ли *ch* печатным символом в смысле [`str.isprintable()`](https://python-all.ru/3.16/library/stdtypes.html#str.isprintable). Эти API можно использовать для быстрых прямых преобразований символов: #### `Py_UCS4 Py_UNICODE_TOLOWER(Py_UCS4 ch)` Возвращает символ *ch*, преобразованный в нижний регистр. #### `Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4 ch)` Возвращает символ *ch*, преобразованный в верхний регистр. #### `Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4 ch)` Возвращает символ *ch*, приведённый к регистру заголовка. #### `int Py_UNICODE_TODECIMAL(Py_UCS4 ch)` Возвращает символ *ch*, преобразованный в положительное десятичное целое. Возвращает `-1`, если это невозможно. Эта функция не вызывает исключений. #### `int Py_UNICODE_TODIGIT(Py_UCS4 ch)` Возвращает символ *ch*, преобразованный в целое число из одной цифры. Возвращает `-1`, если это невозможно. Эта функция не вызывает исключений. #### `double Py_UNICODE_TONUMERIC(Py_UCS4 ch)` Возвращает символ *ch*, преобразованный в число двойной точности (double). Возвращает `-1.0`, если это невозможно. Эта функция не вызывает исключений. Эти API можно использовать для работы с суррогатами: #### `int Py_UNICODE_IS_SURROGATE(Py_UCS4 ch)` Проверяет, является ли *ch* суррогатом (`0xD800 <= ch <= 0xDFFF`). #### `int Py_UNICODE_IS_HIGH_SURROGATE(Py_UCS4 ch)` Проверяет, является ли *ch* старшим суррогатом (`0xD800 <= ch <= 0xDBFF`). #### `int Py_UNICODE_IS_LOW_SURROGATE(Py_UCS4 ch)` Проверяет, является ли *ch* младшим суррогатом (`0xDC00 <= ch <= 0xDFFF`). #### `Py_UCS4 Py_UNICODE_HIGH_SURROGATE(Py_UCS4 ch)` Возвращает старший суррогат UTF-16 (от `0xD800` до `0xDBFF`) для кодовой точки Unicode в диапазоне `[0x10000; 0x10FFFF]`. #### `Py_UCS4 Py_UNICODE_LOW_SURROGATE(Py_UCS4 ch)` Возвращает младший суррогат UTF-16 (от `0xDC00` до `0xDFFF`) для кодовой точки Unicode в диапазоне `[0x10000; 0x10FFFF]`. #### `Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)` Соединяет две суррогатные кодовые точки и возвращает одно значение [`Py_UCS4`](https://python-all.ru/3.16/c-api/unicode.html#c.Py_UCS4). *high* и *low* – это соответственно старший и младший суррогаты в суррогатной паре. *high* должен быть в диапазоне `[0xD800; 0xDBFF]`, а *low* – в диапазоне `[0xDC00; 0xDFFF]`. ### Создание строк Unicode и доступ к ним Для создания объектов Unicode и доступа к их базовым свойствам последовательности используйте следующие API: #### `PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)` *Возвращаемое значение: новая ссылка.* Создаёт новый объект Unicode. *maxchar* должен быть истинным максимальным кодом, который будет помещён в строку. В качестве приближения его можно округлить до ближайшего значения из последовательности 127, 255, 65535, 1114111. При ошибке устанавливает исключение и возвращает `NULL`. После создания строку можно заполнить с помощью [`PyUnicode_WriteChar()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_WriteChar), [`PyUnicode_CopyCharacters()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_CopyCharacters), [`PyUnicode_Fill()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_Fill), [`PyUnicode_WRITE()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_WRITE) или аналогичных функций. Поскольку строки считаются неизменяемыми, следует избегать «использования» результата во время его изменения. В частности, до того как строка заполнена окончательным содержимым, она: - не должна хэшироваться, - не должна быть [`converted to UTF-8`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_AsUTF8AndSize) или другим неканоническим представлением, - не должно изменяться её количество ссылок, - не должна передаваться коду, который может сделать что-либо из перечисленного. Этот список не является исчерпывающим. Избегать такого использования – ваша обязанность; Python не всегда проверяет эти требования. Чтобы случайно не раскрыть частично записанный строковый объект, предпочтительнее использовать API [`PyUnicodeWriter`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicodeWriter) или одну из функций `PyUnicode_From*`, приведённых ниже. Добавлено в версии 3.3. #### `PyObject *PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)` *Возвращаемое значение: новая ссылка.* Создаёт новый объект Unicode с заданным *видом* (возможные значения: [`PyUnicode_1BYTE_KIND`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_1BYTE_KIND) и т.д., возвращаемые [`PyUnicode_KIND()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_KIND)). *Буфер* должен указывать на массив из *size* единиц по 1, 2 или 4 байта на символ, в зависимости от вида. При необходимости входной *буфер* копируется и преобразуется в каноническое представление. Например, если *buffer* – это строка UCS4 ([`PyUnicode_4BYTE_KIND`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_4BYTE_KIND)) и состоит только из кодовых точек в диапазоне UCS1, она будет преобразована в UCS1 ([`PyUnicode_1BYTE_KIND`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_1BYTE_KIND)). Добавлено в версии 3.3. #### `PyObject *PyUnicode_FromStringAndSize(const char *str, Py_ssize_t size)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Создаёт объект Unicode из символьного буфера *str*. Байты интерпретируются как закодированные в UTF-8. Буфер копируется в новый объект. Возвращаемое значение может быть разделяемым объектом, т.е. изменение данных не допускается. Эта функция вызывает [`SystemError`](https://python-all.ru/3.16/library/exceptions.html#SystemError) в следующих случаях: - *size* \< 0 - *str* равен `NULL` и *size* \> 0 Изменено в версии 3.12: *str* == `NULL` при *size* \> 0 больше не допускается. #### `PyObject *PyUnicode_FromString(const char *str)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Создаёт объект Unicode из UTF-8-кодированного нуль-терминированного символьного буфера *str*. #### `PyObject *PyUnicode_FromFormat(const char *format, ...)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Принимает строку формата в стиле C `printf()` *format* и переменное число аргументов, вычисляет размер результирующей строки Python Unicode и возвращает строку с отформатированными значениями. Переменные аргументы должны быть типами C и строго соответствовать символам формата в *format* ASCII-кодированной строке. Спецификатор преобразования содержит два или более символа и состоит из следующих компонентов, которые должны располагаться в указанном порядке: 1. Символ `'%'`, обозначающий начало спецификатора. 2. Флаги преобразования (необязательно), влияющие на результат для некоторых типов преобразования. 3. Минимальная ширина поля (необязательно). Если задана как `'*'` (звёздочка), фактическая ширина передаётся в следующем аргументе, который должен иметь тип int, а преобразуемый объект следует после минимальной ширины поля и необязательной точности. 4. Точность (необязательно), задаётся как `'.'` (точка), за которой следует точность. Если указана как `'*'` (звёздочка), фактическая точность передаётся в следующем аргументе, который должен иметь тип int, а преобразуемое значение следует после точности. 5. Модификатор длины (необязательно). 6. Тип преобразования. Символы флагов преобразования: | Флаг | Значение | | --- | --- | | `0` | Для числовых значений преобразование будет дополняться нулями. | | `-` | Преобразованное значение выравнивается по левому краю (отменяет флаг `0` , если указаны оба). | Модификаторы длины для следующих целочисленных преобразований (`d`, `i`, `o`, `u`, `x` или `X`) определяют тип аргумента (по умолчанию int): | Модификатор | Типы | | --- | --- | | `l` | long или unsigned long | | `ll` | long long или unsigned long long | | `j` | `intmax_t` или `uintmax_t` | | `z` | `size_t` или `ssize_t` | | `t` | `ptrdiff_t` | Модификатор длины `l` для следующих преобразований `s` или `V` указывает, что тип аргумента – const wchar\_t\*. Спецификаторы преобразования: | Спецификатор преобразования | Тип | Описание | | --- | --- | --- | | `%` | *н/д* | Литеральный символ `%`. | | `d`, `i` | Указывается модификатором длины | Десятичное представление знакового целого C. | | `u` | Указывается модификатором длины | Десятичное представление беззнакового целого C. | | `o` | Указывается модификатором длины | Восьмеричное представление беззнакового целого C. | | `x` | Указывается модификатором длины | Шестнадцатеричное представление беззнакового целого C (строчные буквы). | | `X` | Указывается модификатором длины | Шестнадцатеричное представление беззнакового целого C (прописные буквы). | | `c` | int | Один символ. | | `s` | const char\* или const wchar\_t\* | Символьный массив C с нулевым завершителем. | | `p` | const void\* | Шестнадцатеричное представление указателя C. В основном эквивалентно `printf("%p")`, за исключением того, что гарантированно начинается с литерала `0x` независимо от того, что возвращает `printf` на платформе. | | `A` | [PyObject](https://python-all.ru/3.16/c-api/structures.html#c.PyObject)\* | Результат вызова [`ascii()`](https://python-all.ru/3.16/library/functions.html#ascii). | | `U` | [PyObject](https://python-all.ru/3.16/c-api/structures.html#c.PyObject)\* | Объект Unicode. | | `V` | [PyObject](https://python-all.ru/3.16/c-api/structures.html#c.PyObject)\*, const char\* или const wchar\_t\* | Объект Unicode (который может быть `NULL`) и завершающийся нулевым байтом символьный массив C в качестве второго параметра (который будет использован, если первый параметр равен `NULL`). | | `S` | [PyObject](https://python-all.ru/3.16/c-api/structures.html#c.PyObject)\* | Результат вызова [`PyObject_Str()`](https://python-all.ru/3.16/c-api/object.html#c.PyObject_Str). | | `R` | [PyObject](https://python-all.ru/3.16/c-api/structures.html#c.PyObject)\* | Результат вызова [`PyObject_Repr()`](https://python-all.ru/3.16/c-api/object.html#c.PyObject_Repr). | | `T` | [PyObject](https://python-all.ru/3.16/c-api/structures.html#c.PyObject)\* | Получить полное квалифицированное имя типа объекта; вызвать [`PyType_GetFullyQualifiedName()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_GetFullyQualifiedName). | | `#T` | [PyObject](https://python-all.ru/3.16/c-api/structures.html#c.PyObject)\* | Аналогично формату `T`, но использует двоеточие (`:`) в качестве разделителя между именем модуля и квалифицированным именем. | | `N` | [PyTypeObject](https://python-all.ru/3.16/c-api/type.html#c.PyTypeObject)\* | Получить полное квалифицированное имя типа; вызвать [`PyType_GetFullyQualifiedName()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_GetFullyQualifiedName). | | `#N` | [PyTypeObject](https://python-all.ru/3.16/c-api/type.html#c.PyTypeObject)\* | Похож на формат `N`, но использует двоеточие (`:`) в качестве разделителя между именем модуля и квалифицированным именем. | > **Примечание** > > Единицей форматтера ширины является количество символов, а не байтов. Единицей форматтера точности является количество байтов или `wchar_t` элементов (если используется модификатор длины `l`) для `"%s"` и `"%V"` (если аргумент `PyObject*` равен `NULL`), а также количество символов для `"%A"`, `"%U"`, `"%S"`, `"%R"` и `"%V"` (если аргумент `PyObject*` не равен `NULL`). > **Примечание** > > В отличие от C `printf()` флаг `0` действует, даже если для целочисленных преобразований задана точность (`d`, `i`, `u`, `o`, `x` или `X`). Изменено в версии 3.2: Добавлена поддержка `"%lld"` и `"%llu"`. Изменено в версии 3.3: Добавлена поддержка `"%li"`, `"%lli"` и `"%zi"`. Изменено в версии 3.4: Добавлена поддержка форматтеров ширины и точности для `"%s"`, `"%A"`, `"%U"`, `"%V"`, `"%S"`, `"%R"`. Изменено в версии 3.12: Добавлена поддержка спецификаторов преобразования `o` и `X`. Добавлена поддержка модификаторов длины `j` и `t`. Модификаторы длины теперь применяются ко всем целочисленным преобразованиям. Модификатор длины `l` теперь применяется к спецификаторам преобразования `s` и `V`. Добавлена поддержка переменной ширины и точности `*`. Добавлена поддержка флага `-`. Неопознанный символ формата теперь вызывает [`SystemError`](https://python-all.ru/3.16/library/exceptions.html#SystemError). В предыдущих версиях он приводил к тому, что оставшаяся часть строки формата копировалась в результирующую строку как есть, а все лишние аргументы отбрасывались. Изменено в версии 3.13: Добавлена поддержка форматов `%T`, `%#T`, `%N` и `%#N`. #### `PyObject *PyUnicode_FromFormatV(const char *format, va_list vargs)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Идентично [`PyUnicode_FromFormat()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_FromFormat), за исключением того, что принимает ровно два аргумента. #### `PyObject *PyUnicode_FromObject(PyObject *obj)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Копирует экземпляр подтипа Unicode в новый настоящий объект Unicode, если это необходимо. Если *obj* уже является настоящим объектом Unicode (не подтипом), возвращает новую [сильную ссылку](https://python-all.ru/3.16/glossary.html#term-strong-reference) на этот объект. Объекты, отличные от Unicode или его подтипов, вызывают [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError). #### `PyObject *PyUnicode_FromOrdinal(int ordinal)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Создаёт объект Unicode из заданной кодовой точки Unicode *ordinal*. Значение ordinal должно находиться в диапазоне `range(0x110000)`. В противном случае возбуждается [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError). #### `PyObject *PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Декодирует закодированный объект *obj* в объект Unicode. [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes), [`bytearray`](https://python-all.ru/3.16/library/stdtypes.html#bytearray) и другие [объекты, подобные байтовым строкам](https://python-all.ru/3.16/glossary.html#term-bytes-like-object) декодируются в соответствии с заданной *encoding* и с использованием обработки ошибок, определённой *errors*. Оба параметра могут быть `NULL`, чтобы интерфейс использовал значения по умолчанию (см. [Встроенные кодеки](https://python-all.ru/3.16/c-api/unicode.html#builtincodecs) для подробностей). Все остальные объекты, включая объекты Unicode, приводят к установке [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError). API возвращает `NULL` в случае ошибки. Вызывающий отвечает за уменьшение счётчика ссылок (decref) возвращённых объектов. #### `void PyUnicode_Append(PyObject **p_left, PyObject *right)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Добавляет строку *right* в конец *p\_left*. *p\_left* должен указывать на [сильную ссылку](https://python-all.ru/3.16/glossary.html#term-strong-reference) на объект Unicode; `PyUnicode_Append()` освобождает (”[крадёт](https://python-all.ru/3.16/glossary.html#term-steal)”) эту ссылку. В случае ошибки устанавливает *\*p\_left* в `NULL` и возбуждает исключение. В случае успеха устанавливает *\*p\_left* в новую сильную ссылку на результат. #### `void PyUnicode_AppendAndDel(PyObject **p_left, PyObject *right)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Эта функция похожа на [`PyUnicode_Append()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_Append), с тем лишь отличием, что она уменьшает счётчик ссылок *right* на единицу. #### `PyObject *PyUnicode_BuildEncodingMap(PyObject *string)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Возвращает отображение, пригодное для декодирования пользовательской однобайтовой кодировки. Принимает строку Unicode *string* длиной до 256 символов, представляющую таблицу кодировки, и возвращает либо компактный внутренний объект отображения, либо словарь, отображающий коды символов в байтовые значения. Возбуждает [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError) и возвращает `NULL` при неверном входном значении. Добавлено в версии 3.2. #### `const char *PyUnicode_GetDefaultEncoding(void)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Возвращает имя кодировки строк по умолчанию, `"utf-8"`. См. [`sys.getdefaultencoding()`](https://python-all.ru/3.16/library/sys.html#sys.getdefaultencoding). Возвращаемую строку не нужно освобождать, она действует до завершения интерпретатора. #### `Py_ssize_t PyUnicode_GetLength(PyObject *unicode)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.* Возвращает длину объекта Unicode в кодовых точках. При ошибке устанавливает исключение и возвращает `-1`. Добавлено в версии 3.3. #### `Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t from_start, Py_ssize_t how_many)` Копирует символы из одного объекта Unicode в другой. При необходимости выполняет преобразование символов и, если возможно, использует `memcpy()`. Возвращает `-1` и устанавливает исключение при ошибке, в противном случае возвращает количество скопированных символов. Строка ещё не должна была быть «использована». Подробнее см. [`PyUnicode_New()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_New). Добавлено в версии 3.3. #### `int PyUnicode_Resize(PyObject **unicode, Py_ssize_t length);` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Изменяет размер объекта Unicode *\*unicode* до новой *длины* в кодовых точках. Пытается изменить размер строки на месте (обычно это быстрее, чем выделить новую строку и скопировать символы) или создаёт новую строку. *\*unicode* изменяется так, чтобы указывать на новый (изменённый) объект, и возвращается `0` при успехе. В противном случае возвращается `-1` и устанавливается исключение, а *\*unicode* остаётся нетронутым. Функция не проверяет содержимое строки, результат может не быть строкой в каноническом представлении. #### `Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)` Заполняет строку символом: записывает *fill\_char* в `unicode[start:start+length]`. Завершается ошибкой, если *fill\_char* больше максимального символа строки или если у строки больше одной ссылки. Строка ещё не должна была быть «использована». Подробнее см. [`PyUnicode_New()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_New). Возвращает количество записанных символов или `-1` и возбуждает исключение при ошибке. Добавлено в версии 3.3. #### `int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.* Записывает *символ* в строку *unicode* по индексу *index*, начиная с нуля. Возвращает `0` при успехе, `-1` при ошибке с установленным исключением. Эта функция проверяет, что *unicode* является объектом Unicode, что индекс не выходит за границы и что счётчик ссылок объекта равен единице. См. [`PyUnicode_WRITE()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_WRITE) для версии, которая пропускает эти проверки, возлагая их на вас. Строка ещё не должна была быть «использована». Подробнее см. [`PyUnicode_New()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_New). Добавлено в версии 3.3. #### `Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.* Читает символ из строки. Эта функция проверяет, что *unicode* является объектом Unicode и индекс не выходит за границы, в отличие от [`PyUnicode_READ_CHAR()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_READ_CHAR), которая не выполняет проверку ошибок. Возвращает символ при успехе, `-1` при ошибке с установленным исключением. Добавлено в версии 3.3. #### `PyObject *PyUnicode_Substring(PyObject *unicode, Py_ssize_t start, Py_ssize_t end)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.* Возвращает подстроку *unicode* от индекса символа *start* (включительно) до индекса *end* (исключительно). Отрицательные индексы не поддерживаются. При ошибке устанавливает исключение и возвращает `NULL`. Добавлено в версии 3.3. #### `Py_UCS4 *PyUnicode_AsUCS4(PyObject *unicode, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.* Копирует строку *unicode* в буфер UCS4, включая нулевой символ, если *copy\_null* установлен. Возвращает `NULL` и устанавливает исключение при ошибке (в частности, [`SystemError`](https://python-all.ru/3.16/library/exceptions.html#SystemError), если *buflen* меньше длины *unicode*). При успехе возвращается *buffer*. Добавлено в версии 3.3. #### `Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.* Копирует строку *unicode* в новый буфер UCS4, выделенный с помощью [`PyMem_Malloc()`](https://python-all.ru/3.16/c-api/memory.html#c.PyMem_Malloc). В случае неудачи возвращается `NULL` с установленным [`MemoryError`](https://python-all.ru/3.16/library/exceptions.html#MemoryError). Возвращаемый буфер всегда содержит дополнительный нулевой код в конце. Добавлено в версии 3.3. ### Кодировка локали Текущую кодировку локали можно использовать для декодирования текста из операционной системы. #### `PyObject *PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t length, const char *errors)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.* Decode a string from UTF-8 on Android and VxWorks, or from the current locale encoding on other platforms. The supported error handlers are `"strict"` and `"surrogateescape"` ([**PEP 383**](https://python-all.ru/3.16/c-api/unicode.html)). The decoder uses `"strict"` error handler if *errors* is `NULL`. *str* must end with a null character but cannot contain embedded null characters. Используйте [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize) для декодирования строки из [кодировки файловой системы и обработчика ошибок](https://python-all.ru/3.16/glossary.html#term-filesystem-encoding-and-error-handler). Эта функция игнорирует [режим UTF-8 Python](https://python-all.ru/3.16/library/os.html#utf8-mode). > **См. также** > > Функция [`Py_DecodeLocale()`](https://python-all.ru/3.16/c-api/sys.html#c.Py_DecodeLocale). Добавлено в версии 3.3. Изменено в версии 3.7: Теперь функция также использует текущую кодировку локали для обработчика ошибок `surrogateescape`, за исключением Android. Ранее для `surrogateescape` использовался [`Py_DecodeLocale()`](https://python-all.ru/3.16/c-api/sys.html#c.Py_DecodeLocale), а для `strict` использовалась текущая кодировка локали. #### `PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.* Аналогично [`PyUnicode_DecodeLocaleAndSize()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DecodeLocaleAndSize), но длина строки вычисляется с помощью `strlen()`. Добавлено в версии 3.3. #### `PyObject *PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.* Encode a Unicode object to UTF-8 on Android and VxWorks, or to the current locale encoding on other platforms. The supported error handlers are `"strict"` and `"surrogateescape"` ([**PEP 383**](https://python-all.ru/3.16/c-api/unicode.html)). The encoder uses `"strict"` error handler if *errors* is `NULL`. Return a [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes) object. *unicode* cannot contain embedded null characters. Используйте [`PyUnicode_EncodeFSDefault()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_EncodeFSDefault) для кодирования строки в [кодировку файловой системы и обработчик ошибок](https://python-all.ru/3.16/glossary.html#term-filesystem-encoding-and-error-handler). Эта функция игнорирует [режим UTF-8 Python](https://python-all.ru/3.16/library/os.html#utf8-mode). > **См. также** > > Функция [`Py_EncodeLocale()`](https://python-all.ru/3.16/c-api/sys.html#c.Py_EncodeLocale). Добавлено в версии 3.3. Изменено в версии 3.7: Теперь функция также использует текущую кодировку локали для обработчика ошибок `surrogateescape`, за исключением Android. Ранее для `surrogateescape` использовался [`Py_EncodeLocale()`](https://python-all.ru/3.16/c-api/sys.html#c.Py_EncodeLocale), а для `strict` использовалась текущая кодировка локали. ### Кодировка файловой системы Functions encoding to and decoding from the [filesystem encoding and error handler](https://python-all.ru/3.16/glossary.html#term-filesystem-encoding-and-error-handler) ([**PEP 383**](https://python-all.ru/3.16/c-api/unicode.html) and [**PEP 529**](https://python-all.ru/3.16/c-api/unicode.html)). Для кодирования имен файлов в [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes) во время разбора аргументов следует использовать конвертер `"O&"`, передавая `PyUnicode_FSConverter()` в качестве функции преобразования: #### `int PyUnicode_FSConverter(PyObject *obj, void *result)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* [PyArg\_Parse\* converter](https://python-all.ru/3.16/c-api/arg.html#arg-parsing): encode [`str`](https://python-all.ru/3.16/library/stdtypes.html#str) objects – obtained directly or through the [`os.PathLike`](https://python-all.ru/3.16/library/os.html#os.PathLike) interface – to [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes) using [`PyUnicode_EncodeFSDefault()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_EncodeFSDefault); `bytes` objects are output as-is. *result* must be an address of a C variable of type [PyObject](https://python-all.ru/3.16/c-api/structures.html#c.PyObject)\* (or [PyBytesObject](https://python-all.ru/3.16/c-api/bytes.html#c.PyBytesObject)\*). On success, set the variable to a new [strong reference](https://python-all.ru/3.16/glossary.html#term-strong-reference) to a [bytes object](https://python-all.ru/3.16/c-api/bytes.html#bytesobjects) which must be released when it is no longer used and return a non-zero value ([`Py_CLEANUP_SUPPORTED`](https://python-all.ru/3.16/c-api/arg.html#c.Py_CLEANUP_SUPPORTED)). Embedded null bytes are not allowed in the result. On failure, return `0` with an exception set. Если *obj* равно `NULL`, функция освобождает сильную ссылку, сохраненную в переменной, на которую указывает *result*, и возвращает `1`. Добавлено в версии 3.1. Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.16/glossary.html#term-path-like-object). Для декодирования имен файлов в [`str`](https://python-all.ru/3.16/library/stdtypes.html#str) во время разбора аргументов следует использовать конвертер `"O&"`, передавая `PyUnicode_FSDecoder()` в качестве функции преобразования: #### `int PyUnicode_FSDecoder(PyObject *obj, void *result)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* [PyArg\_Parse\* converter](https://python-all.ru/3.16/c-api/arg.html#arg-parsing): decode [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes) objects – obtained either directly or indirectly through the [`os.PathLike`](https://python-all.ru/3.16/library/os.html#os.PathLike) interface – to [`str`](https://python-all.ru/3.16/library/stdtypes.html#str) using [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize); `str` objects are output as-is. *result* must be an address of a C variable of type [PyObject](https://python-all.ru/3.16/c-api/structures.html#c.PyObject)\* (or [PyUnicodeObject](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicodeObject)\*). On success, set the variable to a new [strong reference](https://python-all.ru/3.16/glossary.html#term-strong-reference) to a [Unicode object](https://python-all.ru/3.16/c-api/unicode.html#unicodeobjects) which must be released when it is no longer used and return a non-zero value ([`Py_CLEANUP_SUPPORTED`](https://python-all.ru/3.16/c-api/arg.html#c.Py_CLEANUP_SUPPORTED)). Embedded null characters are not allowed in the result. On failure, return `0` with an exception set. Если *obj* равно `NULL`, освободите сильную ссылку на объект, на который указывает *result*, и верните `1`. Добавлено в версии 3.2. Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.16/glossary.html#term-path-like-object). #### `PyObject *PyUnicode_DecodeFSDefaultAndSize(const char *str, Py_ssize_t size)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Декодирует строку из [кодировки файловой системы и обработчика ошибок](https://python-all.ru/3.16/glossary.html#term-filesystem-encoding-and-error-handler). Если требуется декодировать строку из текущей кодировки локали, используйте [`PyUnicode_DecodeLocaleAndSize()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DecodeLocaleAndSize). > **См. также** > > Функция [`Py_DecodeLocale()`](https://python-all.ru/3.16/c-api/sys.html#c.Py_DecodeLocale). Изменено в версии 3.6: Теперь используется [обработчик ошибок файловой системы](https://python-all.ru/3.16/glossary.html#term-filesystem-encoding-and-error-handler). #### `PyObject *PyUnicode_DecodeFSDefault(const char *str)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Декодирует строку, завершающуюся нулевым символом, из [кодировки файловой системы и обработчика ошибок](https://python-all.ru/3.16/glossary.html#term-filesystem-encoding-and-error-handler). Если длина строки известна, используйте [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize). Изменено в версии 3.6: Теперь используется [обработчик ошибок файловой системы](https://python-all.ru/3.16/glossary.html#term-filesystem-encoding-and-error-handler). #### `PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Кодирует объект Unicode в [кодировку и обработчик ошибок файловой системы](https://python-all.ru/3.16/glossary.html#term-filesystem-encoding-and-error-handler) и возвращает [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes). Обратите внимание, что результирующий объект `bytes` может содержать нулевые байты. Если требуется закодировать строку в текущую кодировку локали, используйте [`PyUnicode_EncodeLocale()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_EncodeLocale). > **См. также** > > Функция [`Py_EncodeLocale()`](https://python-all.ru/3.16/c-api/sys.html#c.Py_EncodeLocale). Добавлено в версии 3.2. Изменено в версии 3.6: Теперь используется [обработчик ошибок файловой системы](https://python-all.ru/3.16/glossary.html#term-filesystem-encoding-and-error-handler). ### Поддержка wchar\_t `wchar_t` поддержка на платформах, которые её поддерживают: #### `PyObject *PyUnicode_FromWideChar(const wchar_t *wstr, Py_ssize_t size)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Создаёт объект Unicode из буфера `wchar_t` *wstr* заданного *размера*. Передача `-1` в качестве *размера* указывает, что функция должна сама вычислить длину с помощью `wcslen()`. В случае ошибки возвращает `NULL`. #### `Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *wstr, Py_ssize_t size)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Копирует содержимое объекта Unicode в буфер `wchar_t` *wstr*. Копируется не более *size* `wchar_t` символов (исключая возможно завершающий нулевой символ). Возвращает количество скопированных `wchar_t` символов или `-1` в случае ошибки. Если *wstr* равно `NULL`, вместо этого возвращает *размер*, который потребуется для хранения всего *unicode*, включая завершающий нуль. Обратите внимание, что результирующая строка wchar\_t\* может быть как завершена нулевым символом, так и нет. Вызывающий код должен гарантировать, что строка wchar\_t\* завершается нулевым символом, если это требуется приложением. Кроме того, строка wchar\_t\* может содержать нулевые символы, что приведёт к усечению строки при использовании с большинством функций C. #### `wchar_t *PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.* Преобразует объект Unicode в широкую строку. Результирующая строка всегда завершается нулевым символом. Если *size* не равно `NULL`, записывает количество широких символов (исключая завершающий нулевой символ) в *\*size*. Обратите внимание, что результирующая строка `wchar_t` может содержать нулевые символы, что приведёт к усечению строки при использовании с большинством функций C. Если *size* равно `NULL` и строка wchar\_t\* содержит нулевые символы, возбуждается [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError). В случае успеха возвращает буфер, выделенный функцией [`PyMem_New`](https://python-all.ru/3.16/c-api/memory.html#c.PyMem_New) (для освобождения используйте [`PyMem_Free()`](https://python-all.ru/3.16/c-api/memory.html#c.PyMem_Free)). При ошибке возвращает `NULL`, а *\*size* не определён. Возбуждает [`MemoryError`](https://python-all.ru/3.16/library/exceptions.html#MemoryError), если выделение памяти не удалось. Добавлено в версии 3.2. Изменено в версии 3.7: Возбуждает [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError), если *size* равно `NULL` и строка wchar\_t\* содержит нулевые символы. ## Встроенные кодеки Python предоставляет набор встроенных кодеков, написанных на C для скорости. Все эти кодеки могут использоваться напрямую через следующие функции. Многие из следующих API принимают два аргумента: encoding и errors, и их семантика совпадает с семантикой соответствующих аргументов встроенного конструктора строк [`str()`](https://python-all.ru/3.16/library/stdtypes.html#str). Установка encoding в `NULL` приводит к использованию кодировки по умолчанию, которой является UTF-8. Файловые системные вызовы должны использовать [`PyUnicode_FSConverter()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_FSConverter) для кодирования имён файлов. Внутри используется [кодировка и обработчик ошибок файловой системы](https://python-all.ru/3.16/glossary.html#term-filesystem-encoding-and-error-handler). Обработка ошибок задаётся параметром errors, который также может быть установлен в `NULL`, что означает использование обработки по умолчанию, определённой для кодека. По умолчанию для всех встроенных кодеков используется строгий режим (возбуждается [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError)). Все кодеки используют схожий интерфейс. Для простоты документированы только отличия от приведённого ниже общего описания. ### Общие кодеки Предоставляется следующий макрос: #### `Py_UNICODE_REPLACEMENT_CHARACTER` Кодовая точка Unicode `U+FFFD` (замещающий символ). Этот символ Unicode используется в качестве замещающего при декодировании, если аргумент *errors* установлен в «replace». Это общие API кодеков: #### `PyObject *PyUnicode_Decode(const char *str, Py_ssize_t size, const char *encoding, const char *errors)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Создаёт объект Unicode путём декодирования *size* байт закодированной строки *str*. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры встроенной функции [`str()`](https://python-all.ru/3.16/library/stdtypes.html#str). Используемый кодек ищется с помощью реестра кодеков Python. Возвращает `NULL`, если кодек возбудил исключение. #### `PyObject *PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Кодирует объект Unicode и возвращает результат в виде объекта bytes. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода [`encode()`](https://python-all.ru/3.16/library/stdtypes.html#str.encode) объекта Unicode. Используемый кодек ищется с помощью реестра кодеков Python. Возвращает `NULL`, если кодек возбудил исключение. ### Кодеки UTF-8 Это API кодеков UTF-8: #### `PyObject *PyUnicode_DecodeUTF8(const char *str, Py_ssize_t size, const char *errors)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Создаёт объект Unicode, декодируя *size* байтов UTF-8-закодированной строки *str*. Возвращает `NULL`, если кодек вызвал исключение. #### `PyObject *PyUnicode_DecodeUTF8Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Если *consumed* равно `NULL`, ведёт себя как [`PyUnicode_DecodeUTF8()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DecodeUTF8). Если *consumed* не равно `NULL`, неполные конечные последовательности байтов UTF-8 не будут считаться ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*. #### `PyObject *PyUnicode_AsUTF8String(PyObject *unicode)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Кодирует объект Unicode в UTF-8 и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение. Функция завершается ошибкой, если строка содержит суррогатные кодовые точки (`U+D800` - `U+DFFF`). #### `const char *PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.10.* Возвращает указатель на UTF-8-кодировку объекта Unicode и сохраняет размер закодированного представления (в байтах) в *size*. Аргумент *size* может быть `NULL`; в этом случае размер не сохраняется. Возвращаемый буфер всегда содержит дополнительный нулевой байт в конце (не включён в *size*), независимо от наличия других нулевых кодовых точек. При ошибке устанавливает исключение, устанавливает *size* в `-1` (если он не NULL) и возвращает `NULL`. Функция завершается ошибкой, если строка содержит суррогатные кодовые точки (`U+D800` - `U+DFFF`). Это кеширует UTF-8-представление строки в объекте Unicode, и последующие вызовы будут возвращать указатель на тот же буфер. Вызывающий не отвечает за освобождение буфера. Буфер освобождается, а указатели на него становятся недействительными, когда объект Unicode удаляется сборщиком мусора. Добавлено в версии 3.3. Изменено в версии 3.7: Тип возвращаемого значения теперь `const char *`, а не `char *`. Изменено в версии 3.10: Эта функция является частью [ограниченного API](https://python-all.ru/3.16/c-api/stable.html#limited-c-api). #### `const char *PyUnicode_AsUTF8(PyObject *unicode)` Как [`PyUnicode_AsUTF8AndSize()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_AsUTF8AndSize), но не сохраняет размер. > **Предупреждение** > > Эта функция не имеет специального поведения для [нулевых символов](https://python-all.ru/3.16/c-api/unicode.html), встроенных в *unicode*. В результате строки, содержащие нулевые символы, останутся в возвращаемой строке, что некоторые функции C могут интерпретировать как конец строки, приводя к усечению. Если усечение является проблемой, рекомендуется использовать [`PyUnicode_AsUTF8AndSize()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_AsUTF8AndSize) вместо этого. Добавлено в версии 3.3. Изменено в версии 3.7: Тип возвращаемого значения теперь `const char *`, а не `char *`. ### Кодеки UTF-32 Это API кодеков UTF-32: #### `PyObject *PyUnicode_DecodeUTF32(const char *str, Py_ssize_t size, const char *errors, int *byteorder)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Декодирует *size* байтов из буферной строки, закодированной в UTF-32, и возвращает соответствующий объект Unicode. *errors* (если не `NULL`) определяет обработку ошибок. По умолчанию – «strict». Если *byteorder* не равно `NULL`, декодер начинает декодирование, используя заданный порядок байтов: ```c *byteorder == -1: little endian *byteorder == 0: native order *byteorder == 1: big endian ``` Если `*byteorder` равен нулю и первые четыре байта входных данных являются маркером порядка байтов (BOM), декодер переключается на этот порядок байтов, и BOM не копируется в результирующую строку Unicode. Если `*byteorder` равно `-1` или `1`, любой маркер порядка байтов копируется в выходные данные. После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных. Если *byteorder* равно `NULL`, кодек запускается в режиме собственного порядка байтов. Возвращает `NULL`, если кодек вызвал исключение. #### `PyObject *PyUnicode_DecodeUTF32Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Если *consumed* равно `NULL`, ведёт себя как [`PyUnicode_DecodeUTF32()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DecodeUTF32). Если *consumed* не равно `NULL`, [`PyUnicode_DecodeUTF32Stateful()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DecodeUTF32Stateful) не будет считать неполные конечные последовательности байтов UTF-32 (например, количество байтов, не делящееся на четыре) ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*. #### `PyObject *PyUnicode_AsUTF32String(PyObject *unicode)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Возвращает байтовую строку Python в кодировке UTF-32 в собственном порядке байтов. Строка всегда начинается с метки BOM. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение. ### Кодеки UTF-32 Это API кодеков UTF-32: #### `PyObject *PyUnicode_DecodeUTF32(const char *str, Py_ssize_t size, const char *errors, int *byteorder)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Декодирует *size* байтов из строки буфера, закодированной в UTF-16, и возвращает соответствующий объект Unicode. *errors* (если не `NULL`) определяет обработку ошибок. По умолчанию используется «strict». Если *byteorder* не равно `NULL`, декодер начинает декодирование с указанным порядком байтов: ```c *byteorder == -1: little endian *byteorder == 0: native order *byteorder == 1: big endian ``` Если `*byteorder` равен нулю и первые два байта входных данных являются меткой порядка байтов (BOM), декодер переключается на этот порядок байтов, а BOM не копируется в результирующую строку Unicode. Если `*byteorder` равен `-1` или `1`, любая метка порядка байтов копируется в выходные данные (что приведёт к символу `\ufeff` или `\ufffe`). После завершения `*byteorder` устанавливается в текущий порядок байтов в конце входных данных. Если *byteorder* равен `NULL`, кодек запускается в режиме собственного порядка байтов. Возвращает `NULL`, если кодек вызвал исключение. #### `PyObject *PyUnicode_DecodeUTF16Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Если *consumed* равен `NULL`, ведёт себя как [`PyUnicode_DecodeUTF16()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DecodeUTF16). Если *consumed* не равен `NULL`, [`PyUnicode_DecodeUTF16Stateful()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DecodeUTF16Stateful) не будет рассматривать хвостовые неполные последовательности байтов UTF-16 (например, нечётное количество байтов или разбитую суррогатную пару) как ошибку. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*. #### `PyObject *PyUnicode_AsUTF16String(PyObject *unicode)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Возвращает байтовую строку Python в кодировке UTF-16 в собственном порядке байтов. Строка всегда начинается с метки BOM. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение. ### Кодеки UTF-7 Это API кодеков UTF-7: #### `PyObject *PyUnicode_DecodeUTF7(const char *str, Py_ssize_t size, const char *errors)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Создаёт объект Unicode путём декодирования *size* байтов строки, закодированной в UTF-7, *str*. Возвращает `NULL`, если кодек вызвал исключение. #### `PyObject *PyUnicode_DecodeUTF7Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Если *consumed* равен `NULL`, ведёт себя как [`PyUnicode_DecodeUTF7()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DecodeUTF7). Если *consumed* не равен `NULL`, хвостовые неполные секции base-64 UTF-7 не будут рассматриваться как ошибка. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*. ### Кодеки Unicode-Escape Это API кодеков «Unicode Escape»: #### `PyObject *PyUnicode_DecodeUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Создаёт объект Unicode путём декодирования *size* байтов строки, закодированной в Unicode-Escape, *str*. Возвращает `NULL`, если кодек вызвал исключение. #### `PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Кодирует объект Unicode с помощью Unicode-Escape и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение. ### Кодеки Raw-Unicode-Escape Это API кодеков «Raw Unicode Escape»: #### `PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Создаёт объект Unicode путём декодирования *size* байтов строки, закодированной в Raw-Unicode-Escape, *str*. Возвращает `NULL`, если кодек вызвал исключение. #### `PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Кодирует объект Unicode с помощью Raw-Unicode-Escape и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение. ### Кодеки Latin-1 Это API кодеков Latin-1: Latin-1 соответствует первым 256 кодовым позициям Unicode, и только они принимаются кодеками при кодировании. #### `PyObject *PyUnicode_DecodeLatin1(const char *str, Py_ssize_t size, const char *errors)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Создаёт объект Unicode путём декодирования *size* байтов строки *str*, закодированной в Latin-1. Возвращает `NULL`, если кодек выбросил исключение. #### `PyObject *PyUnicode_AsLatin1String(PyObject *unicode)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Кодирует объект Unicode с помощью Latin-1 и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает `NULL`, если кодек выбросил исключение. ### Кодеки ASCII Это API кодеков ASCII. Принимаются только 7-битные данные ASCII. Все остальные коды вызывают ошибки. #### `PyObject *PyUnicode_DecodeASCII(const char *str, Py_ssize_t size, const char *errors)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Создаёт объект Unicode путём декодирования *size* байтов строки *str*, закодированной в ASCII. Возвращает `NULL`, если кодек выбросил исключение. #### `PyObject *PyUnicode_AsASCIIString(PyObject *unicode)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Кодирует объект Unicode с помощью ASCII и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает `NULL`, если кодек выбросил исключение. ### Кодеки с таблицей символов Этот кодек особенный тем, что его можно использовать для реализации множества различных кодеков (именно так и были получены большинство стандартных кодеков, входящих в пакет `encodings`). Кодек использует отображения для кодирования и декодирования символов. Предоставляемые объекты отображения должны поддерживать интерфейс отображения [`__getitem__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__getitem__); словари и последовательности прекрасно работают. Это API кодеков отображения: #### `PyObject *PyUnicode_DecodeCharmap(const char *str, Py_ssize_t length, PyObject *mapping, const char *errors)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Создаёт объект Unicode путём декодирования *size* байтов закодированной строки *str* с использованием заданного объекта *mapping*. Возвращает `NULL`, если кодек выбросил исключение. Если *mapping* равен `NULL`, будет применяться декодирование Latin-1. В противном случае *mapping* должен отображать порядковые номера байтов (целые числа в диапазоне от 0 до 255) в строки Unicode, целые числа (которые затем интерпретируются как кодовые позиции Unicode) или `None`. Неотображённые байты данных – те, которые вызывают [`LookupError`](https://python-all.ru/3.16/library/exceptions.html#LookupError), а также те, которые отображаются в `None`, `0xFFFE` или `'\ufffe'`, считаются неопределёнными отображениями и вызывают ошибку. #### `PyObject *PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Кодирует объект Unicode с использованием заданного объекта *mapping* и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает `NULL`, если кодек выбросил исключение. Объект *mapping* должен отображать целые числа – кодовые позиции Unicode – в объекты bytes, целые числа в диапазоне от 0 до 255 или `None`. Неотображённые кодовые позиции символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.16/library/exceptions.html#LookupError)), а также отображённые в `None` считаются «неопределённым отображением» и вызывают ошибку. Следующее API кодека особенное тем, что отображает Unicode в Unicode. #### `PyObject *PyUnicode_Translate(PyObject *unicode, PyObject *table, const char *errors)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Преобразует строку, применяя к ней таблицу отображения символов, и возвращает результирующий объект Unicode. Возвращает `NULL`, если кодек выбросил исключение. Таблица отображения должна отображать целые числа – кодовые позиции Unicode – в целые числа – кодовые позиции Unicode – или в `None` (вызывает удаление символа). Таблицы отображения должны лишь предоставлять интерфейс [`__getitem__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__getitem__); словари и последовательности работают хорошо. Неотображённые кодовые позиции символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.16/library/exceptions.html#LookupError)) остаются нетронутыми и копируются как есть. *errors* имеет обычное для кодеков значение. Он может быть `NULL`, что означает использование обработки ошибок по умолчанию. ### Кодеки MBCS для Windows Это API кодеков MBCS. В настоящее время они доступны только в Windows и используют преобразователи Win32 MBCS для выполнения преобразований. Обратите внимание, что MBCS (или DBCS) – это класс кодировок, а не одна конкретная. Целевая кодировка определяется пользовательскими настройками на машине, где выполняется кодек. #### `PyObject *PyUnicode_DecodeMBCS(const char *str, Py_ssize_t size, const char *errors)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) в Windows начиная с версии 3.7.* Создаёт объект Unicode путём декодирования *size* байтов строки *str*, закодированной в MBCS. Возвращает `NULL`, если кодек выбросил исключение. #### `PyObject *PyUnicode_DecodeMBCSStateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)` *Возвращаемое значение: новая ссылка.* *Часть [стабильного ABI](https://python-all.ru/3.16/c-api/stable.html#stable) на Windows с версии 3.7.* Если *consumed* равно `NULL`, поведение аналогично [`PyUnicode_DecodeMBCS()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DecodeMBCS). Если *consumed* не равно `NULL`, [`PyUnicode_DecodeMBCSStateful()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DecodeMBCSStateful) не будет декодировать конечный ведущий байт, а количество декодированных байт будет сохранено в *consumed*. #### `PyObject *PyUnicode_DecodeCodePageStateful(int code_page, const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)` *Возвращаемое значение: новая ссылка.* *Часть [стабильного ABI](https://python-all.ru/3.16/c-api/stable.html#stable) на Windows с версии 3.7.* Аналогично [`PyUnicode_DecodeMBCSStateful()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DecodeMBCSStateful), но использует кодовую страницу, указанную в *code\_page*. #### `PyObject *PyUnicode_AsMBCSString(PyObject *unicode)` *Возвращаемое значение: новая ссылка.* *Часть [стабильного ABI](https://python-all.ru/3.16/c-api/stable.html#stable) на Windows с версии 3.7.* Кодирует объект Unicode с помощью MBCS и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение. #### `PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)` *Возвращаемое значение: новая ссылка.* *Часть [стабильного ABI](https://python-all.ru/3.16/c-api/stable.html#stable) на Windows с версии 3.7.* Кодирует объект Unicode с помощью указанной кодовой страницы и возвращает объект bytes. Возвращает `NULL`, если кодек вызвал исключение. Используйте кодовую страницу `CP_ACP` для получения кодировщика MBCS. Добавлено в версии 3.3. ## Методы и слот-функции Следующие API могут обрабатывать объекты Unicode и строки на входе (в описаниях мы называем их строками) и возвращают объекты Unicode или целые числа по необходимости. Все они возвращают `NULL` или `-1` в случае возникновения исключения. #### `PyObject *PyUnicode_Concat(PyObject *left, PyObject *right)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Объединяет две строки, возвращая новую строку Unicode. #### `PyObject *PyUnicode_Split(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Разделяет строку, возвращая список строк Unicode. Если *sep* равно `NULL`, разделение происходит по всем пробельным подстрокам. В противном случае разделение происходит по указанному разделителю. Будет выполнено не более *maxsplit* разбиений. Если значение отрицательное, ограничение не задано. Разделители не включаются в результирующий список. При ошибке возвращает `NULL` с установленным исключением. Эквивалентно [`str.split()`](https://python-all.ru/3.16/library/stdtypes.html#str.split). #### `PyObject *PyUnicode_RSplit(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Аналогично [`PyUnicode_Split()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_Split), но разделение начинается с конца строки. При ошибке возвращает `NULL` с установленным исключением. Эквивалентно [`str.rsplit()`](https://python-all.ru/3.16/library/stdtypes.html#str.rsplit). #### `PyObject *PyUnicode_Splitlines(PyObject *unicode, int keepends)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Разделяет строку Unicode по символам конца строки, возвращая список строк Unicode. CRLF считается одним разрывом строки. Если *keepends* равно `0`, символы конца строки не включаются в результирующие строки. #### `PyObject *PyUnicode_Partition(PyObject *unicode, PyObject *sep)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Разделяет строку Unicode по первому вхождению *sep* и возвращает кортеж из трёх элементов: часть до разделителя, сам разделитель и часть после разделителя. Если разделитель не найден, возвращает кортеж из трёх элементов: саму строку, а затем две пустые строки. *sep* не должен быть пустым. При ошибке возвращает `NULL` с установленным исключением. Эквивалентно [`str.partition()`](https://python-all.ru/3.16/library/stdtypes.html#str.partition). #### `PyObject *PyUnicode_RPartition(PyObject *unicode, PyObject *sep)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Аналогично [`PyUnicode_Partition()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_Partition), но разделяет строку Unicode по последнему вхождению *sep*. Если разделитель не найден, возвращает кортеж из трёх элементов: две пустые строки, а затем сама строка. *sep* не должен быть пустым. При ошибке возвращает `NULL` с установленным исключением. Эквивалентно [`str.rpartition()`](https://python-all.ru/3.16/library/stdtypes.html#str.rpartition). #### `PyObject *PyUnicode_Join(PyObject *separator, PyObject *seq)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Объединяет последовательность строк, используя заданный *разделитель*, и возвращает полученную Unicode-строку. #### `Py_ssize_t PyUnicode_Tailmatch(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Возвращает `1`, если *substr* совпадает с `unicode[start:end]` на заданном хвосте (*direction* == `-1` означает проверку на совпадение с началом, *direction* == `1` – с концом), иначе `0`. Возвращает `-1`, если произошла ошибка. #### `Py_ssize_t PyUnicode_Find(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Возвращает первую позицию *substr* в `unicode[start:end]`, используя заданное *direction* (*direction* == `1` означает прямой поиск, *direction* == `-1` – обратный). Возвращаемое значение – индекс первого совпадения; значение `-1` означает, что совпадений не найдено, а `-2` – что произошла ошибка и было установлено исключение. #### `Py_ssize_t PyUnicode_FindChar(PyObject *unicode, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.* Возвращает первую позицию символа *ch* в `unicode[start:end]`, используя заданное *direction* (*direction* == `1` означает прямой поиск, *direction* == `-1` – обратный). Возвращаемое значение – индекс первого совпадения; значение `-1` означает, что совпадений не найдено, а `-2` – что произошла ошибка и было установлено исключение. Добавлено в версии 3.3. Изменено в версии 3.7: *start* и *end* теперь скорректированы, чтобы вести себя как `unicode[start:end]`. #### `Py_ssize_t PyUnicode_Count(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Возвращает количество неперекрывающихся вхождений *substr* в `unicode[start:end]`. Возвращает `-1`, если произошла ошибка. #### `PyObject *PyUnicode_Replace(PyObject *unicode, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Заменяет не более *maxcount* вхождений *substr* в *unicode* на *replstr* и возвращает полученный Unicode-объект. *maxcount* == `-1` означает заменить все вхождения. #### `int PyUnicode_Compare(PyObject *left, PyObject *right)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Сравнивает две строки и возвращает `-1`, `0`, `1` для случаев меньше, равно и больше соответственно. Эта функция возвращает `-1` при ошибке, поэтому для проверки на ошибки следует вызывать [`PyErr_Occurred()`](https://python-all.ru/3.16/c-api/exceptions.html#c.PyErr_Occurred). > **См. также** > > Функция [`PyUnicode_Equal()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_Equal). #### `int PyUnicode_Equal(PyObject *a, PyObject *b)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.14.* Проверяет, равны ли две строки: - Возвращает `1`, если *a* равно *b*. - Возвращает `0`, если *a* не равно *b*. - Устанавливает исключение [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError) и возвращает `-1`, если *a* или *b* не является объектом [`str`](https://python-all.ru/3.16/library/stdtypes.html#str). Функция всегда выполняется успешно, если *a* и *b* являются объектами [`str`](https://python-all.ru/3.16/library/stdtypes.html#str). Функция работает для подклассов [`str`](https://python-all.ru/3.16/library/stdtypes.html#str), но не учитывает пользовательский метод `__eq__()`. > **См. также** > > Функция [`PyUnicode_Compare()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_Compare). Добавлено в версии 3.14. #### `int PyUnicode_EqualToUTF8AndSize(PyObject *unicode, const char *string, Py_ssize_t size)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable), начиная с версии 3.13.* Сравнивает Unicode-объект с буфером символов, который интерпретируется как закодированный в UTF-8 или ASCII, и возвращает true (`1`), если они равны, или false (`0`) в противном случае. Если Unicode-объект содержит суррогатные кодовые точки (`U+D800` - `U+DFFF`) или C-строка не является корректным UTF-8, возвращается false (`0`). Эта функция не вызывает исключений. Добавлено в версии 3.13. #### `int PyUnicode_EqualToUTF8(PyObject *unicode, const char *string)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable), начиная с версии 3.13.* Аналогично [`PyUnicode_EqualToUTF8AndSize()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_EqualToUTF8AndSize), но длину *string* вычисляет с помощью `strlen()`. Если Unicode-объект содержит нулевые символы, возвращается false (`0`). Добавлено в версии 3.13. #### `int PyUnicode_CompareWithASCIIString(PyObject *unicode, const char *string)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Сравнивает Unicode-объект *unicode* со строкой *string* и возвращает `-1`, `0`, `1` для случаев меньше, равно и больше соответственно. Рекомендуется передавать только ASCII-строки, но функция интерпретирует входную строку как ISO-8859-1, если она содержит не-ASCII символы. Эта функция не вызывает исключений. #### `PyObject *PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Сравнивает две строки Unicode и возвращает одно из следующих значений: - `NULL` в случае, если возникло исключение - [`Py_True`](https://python-all.ru/3.16/c-api/bool.html#c.Py_True) или [`Py_False`](https://python-all.ru/3.16/c-api/bool.html#c.Py_False) для успешных сравнений - [`Py_NotImplemented`](https://python-all.ru/3.16/c-api/object.html#c.Py_NotImplemented) в случае, если комбинация типов неизвестна Возможные значения для *op*: [`Py_GT`](https://python-all.ru/3.16/c-api/typeobj.html#c.Py_GT), [`Py_GE`](https://python-all.ru/3.16/c-api/typeobj.html#c.Py_GE), [`Py_EQ`](https://python-all.ru/3.16/c-api/typeobj.html#c.Py_EQ), [`Py_NE`](https://python-all.ru/3.16/c-api/typeobj.html#c.Py_NE), [`Py_LT`](https://python-all.ru/3.16/c-api/typeobj.html#c.Py_LT) и [`Py_LE`](https://python-all.ru/3.16/c-api/typeobj.html#c.Py_LE). #### `PyObject *PyUnicode_Format(PyObject *format, PyObject *args)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Возвращает новый строковый объект из *format* и *args*; это аналог `format % args`. #### `int PyUnicode_Contains(PyObject *unicode, PyObject *substr)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Проверяет, содержится ли *substr* в *unicode*, и возвращает true или false соответственно. *substr* должен приводиться к строке Unicode из одного элемента. `-1` возвращается в случае ошибки. #### `void PyUnicode_InternInPlace(PyObject **p_unicode)` *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Интернирует аргумент \*[p\_unicode](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_InternInPlace) на месте. Аргумент должен быть адресом переменной-указателя, указывающей на объект строки Unicode Python. Если уже существует интернированная строка, совпадающая с \*p\_unicode, то он устанавливает \*p\_unicode на неё (освобождая ссылку на старый строковый объект и создавая новую [сильную ссылку](https://python-all.ru/3.16/glossary.html#term-strong-reference) на интернированную строку), в противном случае он оставляет \*p\_unicode без изменений и интернирует её. (Пояснение: хотя здесь много говорится о ссылках, считайте эту функцию нейтральной по отношению к ссылкам. Вы должны владеть объектом, который передаёте; после вызова вы больше не владеете переданной ссылкой, но приобретаете новую ссылку на результат.) Эта функция никогда не вызывает исключение. При ошибке она оставляет свой аргумент без изменений, не интернируя его. Экземпляры подклассов [`str`](https://python-all.ru/3.16/library/stdtypes.html#str) не могут быть интернированы, то есть [PyUnicode\_CheckExact](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_CheckExact)(\*[p\_unicode](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_InternInPlace)) должно быть истинно. Если это не так, то – как и при любой другой ошибке – аргумент остаётся без изменений. Обратите внимание, что интернированные строки не являются «бессмертными». Вы должны сохранять ссылку на результат, чтобы получить выгоду от интернирования. #### `PyObject *PyUnicode_InternFromString(const char *str)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).* Комбинация [`PyUnicode_FromString()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_FromString) и [`PyUnicode_InternInPlace()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_InternInPlace), предназначенная для статически выделенных строк. Возвращает новую («владение») ссылку либо на новый интернированный объект строки Unicode, либо на ранее интернированный строковый объект с тем же значением. Python может сохранять ссылку на результат или сделать его [бессмертным](https://python-all.ru/3.16/glossary.html#term-immortal), предотвращая его своевременную сборку мусора. Для интернирования неограниченного количества различных строк, например, поступающих от пользователя, предпочтительнее вызывать [`PyUnicode_FromString()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_FromString) и [`PyUnicode_InternInPlace()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_InternInPlace) напрямую. #### `unsigned int PyUnicode_CHECK_INTERNED(PyObject *str)` Возвращает ненулевое значение, если *str* интернирована, и ноль в противном случае. Аргумент *str* должен быть строкой; это не проверяется. Эта функция всегда завершается успешно. **Особенности реализации CPython:** Ненулевое возвращаемое значение может содержать дополнительную информацию о *том, как* строка интернирована. Значение таких ненулевых результатов, а также детали интернирования каждой конкретной строки могут меняться между версиями CPython. ## PyUnicodeWriter API [`PyUnicodeWriter`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicodeWriter) можно использовать для создания объекта Python [`str`](https://python-all.ru/3.16/library/stdtypes.html#str). Добавлено в версии 3.14. #### `type PyUnicodeWriter` Экземпляр средства записи Unicode. Экземпляр должен быть уничтожен с помощью [`PyUnicodeWriter_Finish()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicodeWriter_Finish) в случае успеха или [`PyUnicodeWriter_Discard()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicodeWriter_Discard) в случае ошибки. #### `PyUnicodeWriter *PyUnicodeWriter_Create(Py_ssize_t length)` Создаёт экземпляр средства записи Unicode. *length* должен быть больше или равен `0`. Если *length* больше `0`, предварительно выделяет внутренний буфер размером *length* символов. Устанавливает исключение и возвращает `NULL` в случае ошибки. #### `PyObject *PyUnicodeWriter_Finish(PyUnicodeWriter *writer)` Возвращает итоговый объект [`str`](https://python-all.ru/3.16/library/stdtypes.html#str) и уничтожает экземпляр объекта записи. Устанавливает исключение и возвращает `NULL` в случае ошибки. После этого вызова экземпляр объекта записи становится недействительным. #### `void PyUnicodeWriter_Discard(PyUnicodeWriter *writer)` Отбрасывает внутренний буфер Unicode и уничтожает экземпляр объекта записи. Если *writer* равен `NULL`, операция не выполняется. После этого вызова экземпляр объекта записи становится недействительным. #### `int PyUnicodeWriter_WriteChar(PyUnicodeWriter *writer, Py_UCS4 ch)` Записывает один символ Unicode *ch* в *объект записи*. При успехе возвращает `0`. При ошибке устанавливает исключение, оставляет объект записи без изменений и возвращает `-1`. #### `int PyUnicodeWriter_WriteUTF8(PyUnicodeWriter *writer, const char *str, Py_ssize_t size)` Декодирует строку *str* из UTF-8 в строгом режиме и записывает результат в *объект записи*. *size* – длина строки в байтах. Если *size* равно `-1`, вызывается `strlen(str)` для получения длины строки. При успехе возвращает `0`. При ошибке устанавливает исключение, оставляет объект записи без изменений и возвращает `-1`. См. также [`PyUnicodeWriter_DecodeUTF8Stateful()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicodeWriter_DecodeUTF8Stateful). #### `int PyUnicodeWriter_WriteASCII(PyUnicodeWriter *writer, const char *str, Py_ssize_t size)` Записывает строку ASCII *str* в *объект записи*. *size* – длина строки в байтах. Если *size* равно `-1`, вызывается `strlen(str)` для получения длины строки. *str* должен содержать только символы ASCII. Поведение не определено, если *str* содержит не-ASCII символы. При успехе возвращает `0`. При ошибке устанавливает исключение, оставляет объект записи без изменений и возвращает `-1`. #### `int PyUnicodeWriter_WriteWideChar(PyUnicodeWriter *writer, const wchar_t *str, Py_ssize_t size)` Записывает широкую строку *str* в *объект записи*. *size* – количество широких символов. Если *size* равно `-1`, вызывается `wcslen(str)` для получения длины строки. При успехе возвращает `0`. При ошибке устанавливает исключение, оставляет объект записи без изменений и возвращает `-1`. #### `int PyUnicodeWriter_WriteUCS4(PyUnicodeWriter *writer, const Py_UCS4 *str, Py_ssize_t size)` Записывает строку UCS4 *str* в *объект записи*. *size* – количество символов UCS4. При успехе возвращает `0`. При ошибке устанавливает исключение, оставляет объект записи без изменений и возвращает `-1`. #### `int PyUnicodeWriter_WriteStr(PyUnicodeWriter *writer, PyObject *obj)` Вызывает [`PyObject_Str()`](https://python-all.ru/3.16/c-api/object.html#c.PyObject_Str) для *obj* и записывает результат в *объект записи*. При успехе возвращает `0`. При ошибке устанавливает исключение, оставляет объект записи без изменений и возвращает `-1`. Чтобы записать подкласс [`str`](https://python-all.ru/3.16/library/stdtypes.html#str), который переопределяет метод [`__str__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__str__), можно использовать [`PyUnicode_FromObject()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_FromObject) для получения исходной строки. #### `int PyUnicodeWriter_WriteRepr(PyUnicodeWriter *writer, PyObject *obj)` Вызывает [`PyObject_Repr()`](https://python-all.ru/3.16/c-api/object.html#c.PyObject_Repr) для *obj* и записывает результат в *объект записи*. Если *obj* равно `NULL`, записывает строку `""` в *объект записи*. В случае успеха возвращает `0`. В случае ошибки устанавливает исключение, оставляет writer без изменений и возвращает `-1`. Изменено в версии 3.14.4: Добавлена поддержка `NULL`. #### `int PyUnicodeWriter_WriteSubstring(PyUnicodeWriter *writer, PyObject *str, Py_ssize_t start, Py_ssize_t end)` Записывает подстроку `str[start:end]` в *writer*. *str* должен быть объектом [`str`](https://python-all.ru/3.16/library/stdtypes.html#str) Python. *start* должен быть больше или равен 0 и меньше или равен *end*. *end* должен быть меньше или равен длине *str*. В случае успеха возвращает `0`. В случае ошибки устанавливает исключение, оставляет writer без изменений и возвращает `-1`. #### `int PyUnicodeWriter_Format(PyUnicodeWriter *writer, const char *format, ...)` Аналогично [`PyUnicode_FromFormat()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_FromFormat), но записывает вывод напрямую в *writer*. В случае успеха возвращает `0`. В случае ошибки устанавливает исключение, оставляет writer без изменений и возвращает `-1`. #### `int PyUnicodeWriter_DecodeUTF8Stateful(PyUnicodeWriter *writer, const char *string, Py_ssize_t length, const char *errors, Py_ssize_t *consumed)` Декодирует строку *str* из UTF-8 с обработчиком ошибок *errors* и записывает вывод в *writer*. *size* – длина строки в байтах. Если *size* равно `-1`, вызывается `strlen(str)` для получения длины строки. *errors* – это имя [обработчика ошибок](https://python-all.ru/3.16/library/codecs.html#error-handlers), например `"replace"`. Если *errors* равно `NULL`, используется строгий обработчик ошибок. Если *consumed* не равно `NULL`, *\*consumed* устанавливается в количество декодированных байтов в случае успеха. Если *consumed* равно `NULL`, завершающие неполные последовательности байтов UTF-8 рассматриваются как ошибка. В случае успеха возвращает `0`. В случае ошибки устанавливает исключение, оставляет writer без изменений и возвращает `-1`. См. также [`PyUnicodeWriter_WriteUTF8()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicodeWriter_WriteUTF8). ## Устаревший API Следующий API устарел. #### `type Py_UNICODE` Это typedef для `wchar_t`, который является 16-битным или 32-битным типом в зависимости от платформы. Вместо этого используйте напрямую `wchar_t`. Изменено в версии 3.3: В предыдущих версиях это был 16-битный или 32-битный тип в зависимости от того, была ли выбрана «узкая» или «широкая» версия Unicode Python при сборке. Устарело с версии 3.13, удалено в версии 3.16. #### `int PyUnicode_READY(PyObject *unicode)` Ничего не делает и возвращает `0`. Этот API сохранён только для обратной совместимости, но нет планов его удалять. Добавлено в версии 3.3. Устарело с версии 3.10: Этот API ничего не делает с Python 3.12. Ранее его нужно было вызывать для каждой строки, созданной с помощью старого API (`PyUnicode_FromUnicode()` или аналогичного). #### `unsigned int PyUnicode_IS_READY(PyObject *unicode)` Ничего не делает и возвращает `1`. Этот API сохранён только для обратной совместимости, но нет планов его удалять. Добавлено в версии 3.3. Устарело с версии 3.14: Этот API ничего не делает с Python 3.12. Ранее его можно было вызывать для проверки, необходимо ли [`PyUnicode_READY()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_READY).