`unicode.md`

1256 строк · 102.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.13/c-api/unicode.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты Unicode и кодеки89## Объекты Unicode1011Начиная с реализации [**PEP 393**](https://python-all.ru/3.13/c-api/unicode.html) в Python 3.3, объекты Unicode внутри используют различные представления, чтобы обеспечить обработку полного диапазона символов Unicode, оставаясь при этом эффективными по памяти. Существуют особые случаи для строк, где все кодовые точки находятся ниже 128, 256 или 65536; в противном случае кодовые точки должны быть ниже 1114112 (то есть полного диапазона Unicode).1213Представление UTF-8 создаётся по требованию и кэшируется в объекте Unicode.1415> **Примечание**16>17> Представление [`Py_UNICODE`](https://python-all.ru/3.13/c-api/unicode.html#c.Py_UNICODE) было удалено начиная с Python 3.12 вместе с устаревшими API. См. [**PEP 623**](https://python-all.ru/3.13/c-api/unicode.html) для получения дополнительной информации.1819### Тип Unicode2021Это основные типы объектов Unicode, используемые в реализации Unicode в Python:2223#### `type Py_UCS4`2425#### `type Py_UCS2`2627#### `type Py_UCS1`2829*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*3031Эти типы являются псевдонимами для беззнаковых целочисленных типов, достаточно широких для хранения символов размером 32, 16 и 8 бит соответственно. При работе с отдельными символами Unicode используйте [`Py_UCS4`](https://python-all.ru/3.13/c-api/unicode.html#c.Py_UCS4).3233Добавлено в версии 3.3.3435#### `type Py_UNICODE`3637Это typedef для `wchar_t`, 16-битный или 32-битный тип в зависимости от платформы.3839Изменено в версии 3.3: В предыдущих версиях это был 16-битный или 32-битный тип в зависимости от того, была ли выбрана «узкая» или «широкая» версия Unicode Python при сборке.4041Устарело с версии 3.13, будет удалено в версии 3.15.4243#### `type PyASCIIObject`4445#### `type PyCompactUnicodeObject`4647#### `type PyUnicodeObject`4849Эти подтипы [`PyObject`](https://python-all.ru/3.13/c-api/structures.html#c.PyObject) представляют объект Unicode в Python. В почти всех случаях их не следует использовать напрямую, так как все функции API, работающие с объектами Unicode, принимают и возвращают указатели `PyObject`.5051Добавлено в версии 3.3.5253#### `PyTypeObject PyUnicode_Type`5455*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*5657Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.13/c-api/type.html#c.PyTypeObject) представляет тип Python Unicode. Он доступен в коде Python как `str`.5859#### `PyTypeObject PyUnicodeIter_Type`6061*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*6263Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.13/c-api/type.html#c.PyTypeObject) представляет тип итератора Unicode в Python. Он используется для итерации по объектам строк Unicode.6465Следующие API представляют собой макросы C и статические встроенные функции для быстрых проверок и доступа к внутренним данным только для чтения объектов Unicode:6667#### `int PyUnicode_Check(PyObject *obj)`6869Возвращает true, если объект *obj* является объектом Unicode или экземпляром подтипа Unicode. Эта функция всегда завершается успешно.7071#### `int PyUnicode_CheckExact(PyObject *obj)`7273Возвращает true, если объект *obj* является объектом Unicode, но не экземпляром подтипа. Эта функция всегда завершается успешно.7475#### `int PyUnicode_READY(PyObject *unicode)`7677Возвращает `0`. Этот API сохранён только для обратной совместимости.7879Добавлено в версии 3.3.8081Устарело с версии 3.10: Этот API ничего не делает, начиная с Python 3.12.8283#### `Py_ssize_t PyUnicode_GET_LENGTH(PyObject *unicode)`8485Возвращает длину строки Unicode в кодовых точках. *unicode* должен быть объектом Unicode в «каноническом» представлении (не проверяется).8687Добавлено в версии 3.3.8889#### `Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *unicode)`9091#### `Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *unicode)`9293#### `Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *unicode)`9495Возвращает указатель на каноническое представление, приведённый к целочисленным типам UCS1, UCS2 или UCS4 для прямого доступа к символам. Не выполняется проверок, имеет ли каноническое представление правильный размер символа; используйте [`PyUnicode_KIND()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_KIND), чтобы выбрать подходящую функцию.9697Добавлено в версии 3.3.9899#### `PyUnicode_1BYTE_KIND`100101#### `PyUnicode_2BYTE_KIND`102103#### `PyUnicode_4BYTE_KIND`104105Возвращает значения макроса [`PyUnicode_KIND()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_KIND).106107Добавлено в версии 3.3.108109Изменено в версии 3.12: `PyUnicode_WCHAR_KIND` был удалён.110111#### `int PyUnicode_KIND(PyObject *unicode)`112113Возвращает одну из констант вида PyUnicode (см. выше), которые указывают, сколько байт на символ использует данный объект Unicode для хранения своих данных. *unicode* должен быть объектом Unicode в «каноническом» представлении (не проверяется).114115Добавлено в версии 3.3.116117#### `void *PyUnicode_DATA(PyObject *unicode)`118119Возвращает указатель void на сырой буфер Unicode. *unicode* должен быть объектом Unicode в «каноническом» представлении (не проверяется).120121Добавлено в версии 3.3.122123#### `void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)`124125Записывает в каноническое представление *data* (полученное с помощью [`PyUnicode_DATA()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_DATA)). Эта функция не выполняет проверок корректности и предназначена для использования в циклах. Вызывающий код должен кэшировать значение *kind* и указатель *data*, полученные из других вызовов. *index* – это индекс в строке (начинается с 0), а *value* – это новое значение кодовой точки, которое должно быть записано в эту позицию.126127Добавлено в версии 3.3.128129#### `Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)`130131Читает кодовую точку из канонического представления *data* (полученного с помощью [`PyUnicode_DATA()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_DATA)). Никаких проверок или вызовов готовности не выполняется.132133Добавлено в версии 3.3.134135#### `Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)`136137Читает символ из объекта Unicode *unicode*, который должен быть в «каноническом» представлении. Это менее эффективно, чем [`PyUnicode_READ()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_READ), если выполняется несколько последовательных чтений.138139Добавлено в версии 3.3.140141#### `Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *unicode)`142143Возвращает максимальную кодовую точку, подходящую для создания другой строки на основе *unicode*, который должен быть в «каноническом» представлении. Это всегда приближение, но более эффективное, чем перебор строки.144145Добавлено в версии 3.3.146147#### `int PyUnicode_IsIdentifier(PyObject *unicode)`148149*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*150151Возвращает `1`, если строка является допустимым идентификатором в соответствии с определением языка, раздел [Идентификаторы и ключевые слова](https://python-all.ru/3.13/reference/lexical_analysis.html#identifiers). В противном случае возвращает `0`.152153Изменено в версии 3.9: Функция больше не вызывает [`Py_FatalError()`](https://python-all.ru/3.13/c-api/sys.html#c.Py_FatalError), если строка не готова.154155### Свойства символов Unicode156157Unicode предоставляет множество различных свойств символов. Наиболее востребованные из них доступны через следующие макросы, которые сопоставляются с функциями на C в зависимости от конфигурации Python.158159#### `int Py_UNICODE_ISSPACE(Py_UCS4 ch)`160161Возвращает `1` или `0` в зависимости от того, является ли *ch* пробельным символом.162163#### `int Py_UNICODE_ISLOWER(Py_UCS4 ch)`164165Возвращает `1` или `0` в зависимости от того, является ли *ch* символом в нижнем регистре.166167#### `int Py_UNICODE_ISUPPER(Py_UCS4 ch)`168169Возвращает `1` или `0` в зависимости от того, является ли *ch* символом в верхнем регистре.170171#### `int Py_UNICODE_ISTITLE(Py_UCS4 ch)`172173Возвращает `1` или `0` в зависимости от того, является ли *ch* символом в регистре заголовка (titlecase).174175#### `int Py_UNICODE_ISLINEBREAK(Py_UCS4 ch)`176177Возвращает `1` или `0` в зависимости от того, является ли *ch* символом разрыва строки.178179#### `int Py_UNICODE_ISDECIMAL(Py_UCS4 ch)`180181Возвращает `1` или `0` в зависимости от того, является ли *ch* десятичным символом.182183#### `int Py_UNICODE_ISDIGIT(Py_UCS4 ch)`184185Возвращает `1` или `0` в зависимости от того, является ли *ch* цифровым символом.186187#### `int Py_UNICODE_ISNUMERIC(Py_UCS4 ch)`188189Возвращает `1` или `0` в зависимости от того, является ли *ch* числовым символом.190191#### `int Py_UNICODE_ISALPHA(Py_UCS4 ch)`192193Возвращает `1` или `0` в зависимости от того, является ли *ch* буквенным символом.194195#### `int Py_UNICODE_ISALNUM(Py_UCS4 ch)`196197Возвращает `1` или `0` в зависимости от того, является ли *ch* буквенно-цифровым символом.198199#### `int Py_UNICODE_ISPRINTABLE(Py_UCS4 ch)`200201Возвращает `1` или `0` в зависимости от того, является ли *ch* печатным символом в смысле [`str.isprintable()`](https://python-all.ru/3.13/library/stdtypes.html#str.isprintable).202203Эти API можно использовать для быстрых прямых преобразований символов:204205#### `Py_UCS4 Py_UNICODE_TOLOWER(Py_UCS4 ch)`206207Возвращает символ *ch*, преобразованный в нижний регистр.208209#### `Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4 ch)`210211Возвращает символ *ch*, преобразованный в верхний регистр.212213#### `Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4 ch)`214215Возвращает символ *ch*, приведённый к регистру заголовка.216217#### `int Py_UNICODE_TODECIMAL(Py_UCS4 ch)`218219Возвращает символ *ch*, преобразованный в положительное десятичное целое. Возвращает `-1`, если это невозможно. Эта функция не вызывает исключений.220221#### `int Py_UNICODE_TODIGIT(Py_UCS4 ch)`222223Возвращает символ *ch*, преобразованный в целое число из одной цифры. Возвращает `-1`, если это невозможно. Эта функция не вызывает исключений.224225#### `double Py_UNICODE_TONUMERIC(Py_UCS4 ch)`226227Возвращает символ *ch*, преобразованный в число двойной точности (double). Возвращает `-1.0`, если это невозможно. Эта функция не вызывает исключений.228229Эти API можно использовать для работы с суррогатами:230231#### `int Py_UNICODE_IS_SURROGATE(Py_UCS4 ch)`232233Проверяет, является ли *ch* суррогатом (`0xD800 <= ch <= 0xDFFF`).234235#### `int Py_UNICODE_IS_HIGH_SURROGATE(Py_UCS4 ch)`236237Проверяет, является ли *ch* старшим суррогатом (`0xD800 <= ch <= 0xDBFF`).238239#### `int Py_UNICODE_IS_LOW_SURROGATE(Py_UCS4 ch)`240241Проверяет, является ли *ch* младшим суррогатом (`0xDC00 <= ch <= 0xDFFF`).242243#### `Py_UCS4 Py_UNICODE_HIGH_SURROGATE(Py_UCS4 ch)`244245Возвращает старший суррогат UTF-16 (от `0xD800` до `0xDBFF`) для кодовой точки Unicode в диапазоне `[0x10000; 0x10FFFF]`.246247#### `Py_UCS4 Py_UNICODE_LOW_SURROGATE(Py_UCS4 ch)`248249Возвращает младший суррогат UTF-16 (от `0xDC00` до `0xDFFF`) для кодовой точки Unicode в диапазоне `[0x10000; 0x10FFFF]`.250251#### `Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)`252253Соединяет две суррогатные кодовые точки и возвращает одно значение [`Py_UCS4`](https://python-all.ru/3.13/c-api/unicode.html#c.Py_UCS4). *high* и *low* – это соответственно старший и младший суррогаты в суррогатной паре. *high* должен быть в диапазоне `[0xD800; 0xDBFF]`, а *low* – в диапазоне `[0xDC00; 0xDFFF]`.254255### Создание строк Unicode и доступ к ним256257Для создания объектов Unicode и доступа к их базовым свойствам последовательности используйте следующие API:258259#### `PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)`260261*Возвращаемое значение: новая ссылка.*262263Создаёт новый объект Unicode. *maxchar* должен быть истинным максимальным кодом, который будет помещён в строку. В качестве приближения его можно округлить до ближайшего значения из последовательности 127, 255, 65535, 1114111.264265Это рекомендуемый способ выделения нового объекта Unicode. Объекты, созданные с помощью этой функции, не подлежат изменению размера.266267При ошибке устанавливает исключение и возвращает `NULL`.268269Добавлено в версии 3.3.270271#### `PyObject *PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)`272273*Возвращаемое значение: новая ссылка.*274275Создаёт новый объект Unicode с заданным *видом* (возможные значения: [`PyUnicode_1BYTE_KIND`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_1BYTE_KIND) и т.д., возвращаемые [`PyUnicode_KIND()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_KIND)). *Буфер* должен указывать на массив из *size* единиц по 1, 2 или 4 байта на символ, в зависимости от вида.276277При необходимости входной *буфер* копируется и преобразуется в каноническое представление. Например, если *buffer* – это строка UCS4 ([`PyUnicode_4BYTE_KIND`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_4BYTE_KIND)) и состоит только из кодовых точек в диапазоне UCS1, она будет преобразована в UCS1 ([`PyUnicode_1BYTE_KIND`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_1BYTE_KIND)).278279Добавлено в версии 3.3.280281#### `PyObject *PyUnicode_FromStringAndSize(const char *str, Py_ssize_t size)`282283*Возвращаемое значение: новая ссылка.*284285*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*286287Создаёт объект Unicode из символьного буфера *str*. Байты интерпретируются как закодированные в UTF-8. Буфер копируется в новый объект. Возвращаемое значение может быть разделяемым объектом, т.е. изменение данных не допускается.288289Эта функция вызывает [`SystemError`](https://python-all.ru/3.13/library/exceptions.html#SystemError) в следующих случаях:290291- *size* \< 0292- *str* равен `NULL` и *size* \> 0293294Изменено в версии 3.12: *str* == `NULL` при *size* \> 0 больше не допускается.295296#### `PyObject *PyUnicode_FromString(const char *str)`297298*Возвращаемое значение: новая ссылка.*299300*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*301302Создаёт объект Unicode из UTF-8-кодированного нуль-терминированного символьного буфера *str*.303304#### `PyObject *PyUnicode_FromFormat(const char *format, ...)`305306*Возвращаемое значение: новая ссылка.*307308*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*309310Принимает строку формата в стиле C `printf()` *format* и переменное число аргументов, вычисляет размер результирующей строки Python Unicode и возвращает строку с отформатированными значениями. Переменные аргументы должны быть типами C и строго соответствовать символам формата в *format* ASCII-кодированной строке.311312Спецификатор преобразования содержит два или более символа и состоит из следующих компонентов, которые должны располагаться в указанном порядке:3133141. Символ `'%'`, обозначающий начало спецификатора.3152. Флаги преобразования (необязательно), влияющие на результат для некоторых типов преобразования.3163. Минимальная ширина поля (необязательно). Если задана как `'*'` (звёздочка), фактическая ширина передаётся в следующем аргументе, который должен иметь тип int, а преобразуемый объект следует после минимальной ширины поля и необязательной точности.3174. Точность (необязательно), задаётся как `'.'` (точка), за которой следует точность. Если указана как `'*'` (звёздочка), фактическая точность передаётся в следующем аргументе, который должен иметь тип int, а преобразуемое значение следует после точности.3185. Модификатор длины (необязательно).3196. Тип преобразования.320321Символы флагов преобразования:322323| Флаг | Значение |324| --- | --- |325| `0` | Для числовых значений преобразование будет дополняться нулями. |326| `-` | Преобразованное значение выравнивается по левому краю (отменяет флаг `0` , если указаны оба). |327328Модификаторы длины для следующих целочисленных преобразований (`d`, `i`, `o`, `u`, `x` или `X`) определяют тип аргумента (по умолчанию int):329330| Модификатор | Типы |331| --- | --- |332| `l` | long или unsigned long |333| `ll` | long long или unsigned long long |334| `j` | `intmax_t` или `uintmax_t` |335| `z` | `size_t` или `ssize_t` |336| `t` | `ptrdiff_t` |337338Модификатор длины `l` для следующих преобразований `s` или `V` указывает, что тип аргумента – const wchar\_t\*.339340Спецификаторы преобразования:341342| Спецификатор преобразования | Тип | Описание |343| --- | --- | --- |344| `%` | *н/д* | Литеральный символ `%`. |345| `d`, `i` | Указывается модификатором длины | Десятичное представление знакового целого C. |346| `u` | Указывается модификатором длины | Десятичное представление беззнакового целого C. |347| `o` | Указывается модификатором длины | Восьмеричное представление беззнакового целого C. |348| `x` | Указывается модификатором длины | Шестнадцатеричное представление беззнакового целого C (строчные буквы). |349| `X` | Указывается модификатором длины | Шестнадцатеричное представление беззнакового целого C (прописные буквы). |350| `c` | int | Один символ. |351| `s` | const char\* или const wchar\_t\* | Символьный массив C с нулевым завершителем. |352| `p` | const void\* | Шестнадцатеричное представление указателя C. В основном эквивалентно `printf("%p")`, за исключением того, что гарантированно начинается с литерала `0x` независимо от того, что возвращает `printf` на платформе. |353| `A` | [PyObject](https://python-all.ru/3.13/c-api/structures.html#c.PyObject)\* | Результат вызова [`ascii()`](https://python-all.ru/3.13/library/functions.html#ascii). |354| `U` | [PyObject](https://python-all.ru/3.13/c-api/structures.html#c.PyObject)\* | Объект Unicode. |355| `V` | [PyObject](https://python-all.ru/3.13/c-api/structures.html#c.PyObject)\*, const char\* или const wchar\_t\* | Объект Unicode (который может быть `NULL`) и завершающийся нулевым байтом символьный массив C в качестве второго параметра (который будет использован, если первый параметр равен `NULL`). |356| `S` | [PyObject](https://python-all.ru/3.13/c-api/structures.html#c.PyObject)\* | Результат вызова [`PyObject_Str()`](https://python-all.ru/3.13/c-api/object.html#c.PyObject_Str). |357| `R` | [PyObject](https://python-all.ru/3.13/c-api/structures.html#c.PyObject)\* | Результат вызова [`PyObject_Repr()`](https://python-all.ru/3.13/c-api/object.html#c.PyObject_Repr). |358| `T` | [PyObject](https://python-all.ru/3.13/c-api/structures.html#c.PyObject)\* | Получить полное квалифицированное имя типа объекта; вызвать [`PyType_GetFullyQualifiedName()`](https://python-all.ru/3.13/c-api/type.html#c.PyType_GetFullyQualifiedName). |359| `#T` | [PyObject](https://python-all.ru/3.13/c-api/structures.html#c.PyObject)\* | Похож на формат `T`, но использует двоеточие (`:`) в качестве разделителя между именем модуля и квалифицированным именем. |360| `N` | [PyTypeObject](https://python-all.ru/3.13/c-api/type.html#c.PyTypeObject)\* | Получить полное квалифицированное имя типа; вызвать [`PyType_GetFullyQualifiedName()`](https://python-all.ru/3.13/c-api/type.html#c.PyType_GetFullyQualifiedName). |361| `#N` | [PyTypeObject](https://python-all.ru/3.13/c-api/type.html#c.PyTypeObject)\* | Похож на формат `N`, но использует двоеточие (`:`) в качестве разделителя между именем модуля и квалифицированным именем. |362363> **Примечание**364>365> Единицей форматтера ширины является количество символов, а не байтов. Единицей форматтера точности является количество байтов или `wchar_t` элементов (если используется модификатор длины `l`) для `"%s"` и `"%V"` (если аргумент `PyObject*` равен `NULL`), а также количество символов для `"%A"`, `"%U"`, `"%S"`, `"%R"` и `"%V"` (если аргумент `PyObject*` не равен `NULL`).366367> **Примечание**368>369> В отличие от C `printf()` флаг `0` действует, даже если для целочисленных преобразований задана точность (`d`, `i`, `u`, `o`, `x` или `X`).370371Изменено в версии 3.2: Добавлена поддержка `"%lld"` и `"%llu"`.372373Изменено в версии 3.3: Добавлена поддержка `"%li"`, `"%lli"` и `"%zi"`.374375Изменено в версии 3.4: Добавлена поддержка форматтеров ширины и точности для `"%s"`, `"%A"`, `"%U"`, `"%V"`, `"%S"`, `"%R"`.376377Изменено в версии 3.12: Добавлена поддержка спецификаторов преобразования `o` и `X`. Добавлена поддержка модификаторов длины `j` и `t`. Модификаторы длины теперь применяются ко всем целочисленным преобразованиям. Модификатор длины `l` теперь применяется к спецификаторам преобразования `s` и `V`. Добавлена поддержка переменной ширины и точности `*`. Добавлена поддержка флага `-`.378379Неопознанный символ формата теперь вызывает [`SystemError`](https://python-all.ru/3.13/library/exceptions.html#SystemError). В предыдущих версиях он приводил к тому, что оставшаяся часть строки формата копировалась в результирующую строку как есть, а все лишние аргументы отбрасывались.380381Изменено в версии 3.13: Добавлена поддержка форматов `%T`, `%#T`, `%N` и `%#N`.382383#### `PyObject *PyUnicode_FromFormatV(const char *format, va_list vargs)`384385*Возвращаемое значение: новая ссылка.*386387*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*388389Идентично [`PyUnicode_FromFormat()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_FromFormat), за исключением того, что принимает ровно два аргумента.390391#### `PyObject *PyUnicode_FromObject(PyObject *obj)`392393*Возвращаемое значение: новая ссылка.*394395*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*396397Копирует экземпляр подтипа Unicode в новый настоящий объект Unicode, если это необходимо. Если *obj* уже является настоящим объектом Unicode (не подтипом), возвращает новую [сильную ссылку](https://python-all.ru/3.13/glossary.html#term-strong-reference) на этот объект.398399Объекты, отличные от Unicode или его подтипов, вызывают [`TypeError`](https://python-all.ru/3.13/library/exceptions.html#TypeError).400401#### `PyObject *PyUnicode_FromOrdinal(int ordinal)`402403*Возвращаемое значение: новая ссылка.*404405*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*406407Создаёт объект Unicode из заданной кодовой точки Unicode *ordinal*.408409Значение ordinal должно находиться в диапазоне `range(0x110000)`. В противном случае возбуждается [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError).410411#### `PyObject *PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)`412413*Возвращаемое значение: новая ссылка.*414415*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*416417Декодирует закодированный объект *obj* в объект Unicode.418419[`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes), [`bytearray`](https://python-all.ru/3.13/library/stdtypes.html#bytearray) и другие [объекты, подобные байтовым строкам](https://python-all.ru/3.13/glossary.html#term-bytes-like-object) декодируются в соответствии с заданной *encoding* и с использованием обработки ошибок, определённой *errors*. Оба параметра могут быть `NULL`, чтобы интерфейс использовал значения по умолчанию (см. [Встроенные кодеки](https://python-all.ru/3.13/c-api/unicode.html#builtincodecs) для подробностей).420421Все остальные объекты, включая объекты Unicode, приводят к установке [`TypeError`](https://python-all.ru/3.13/library/exceptions.html#TypeError).422423API возвращает `NULL` в случае ошибки. Вызывающий отвечает за уменьшение счётчика ссылок (decref) возвращённых объектов.424425#### `PyObject *PyUnicode_BuildEncodingMap(PyObject *string)`426427*Возвращаемое значение: новая ссылка.*428429*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*430431Возвращает отображение, подходящее для декодирования пользовательской однобайтовой кодировки. Принимает строку Unicode *string* длиной до 256 символов, представляющую таблицу кодировки, и возвращает либо компактный внутренний объект отображения, либо словарь, сопоставляющий кодовые точки символов с байтовыми значениями. В случае недопустимых входных данных вызывает [`TypeError`](https://python-all.ru/3.13/library/exceptions.html#TypeError) и возвращает `NULL`. .. versionadded:: 3.2432433#### `const char *PyUnicode_GetDefaultEncoding(void)`434435*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*436437Возвращает имя кодировки строк по умолчанию, `"utf-8"`. См. [`sys.getdefaultencoding()`](https://python-all.ru/3.13/library/sys.html#sys.getdefaultencoding).438439Возвращаемую строку не нужно освобождать, она действует до завершения интерпретатора.440441#### `Py_ssize_t PyUnicode_GetLength(PyObject *unicode)`442443*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*444445Возвращает длину объекта Unicode в кодовых точках.446447При ошибке устанавливает исключение и возвращает `-1`.448449Добавлено в версии 3.3.450451#### `Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t from_start, Py_ssize_t how_many)`452453Копирует символы из одного объекта Unicode в другой. При необходимости выполняет преобразование символов и, если возможно, использует `memcpy()`. Возвращает `-1` и устанавливает исключение при ошибке, в противном случае возвращает количество скопированных символов.454455Добавлено в версии 3.3.456457#### `Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)`458459Заполняет строку символом: записывает *fill\_char* в `unicode[start:start+length]`.460461Завершается ошибкой, если *fill\_char* больше максимального символа строки или если у строки больше одной ссылки.462463Возвращает количество записанных символов или `-1` и возбуждает исключение при ошибке.464465Добавлено в версии 3.3.466467#### `int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)`468469*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*470471Записывает символ в строку. Строка должна быть создана с помощью [`PyUnicode_New()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_New). Поскольку строки Unicode считаются неизменяемыми, строка не должна быть общей или уже хэшированной.472473Эта функция проверяет, что *unicode* является объектом Unicode, индекс не выходит за границы, и объект можно безопасно изменять (т.е. его счётчик ссылок равен единице).474475Возвращает `0` при успехе, `-1` при ошибке с установленным исключением.476477Добавлено в версии 3.3.478479#### `Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)`480481*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*482483Читает символ из строки. Эта функция проверяет, что *unicode* является объектом Unicode и индекс не выходит за границы, в отличие от [`PyUnicode_READ_CHAR()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_READ_CHAR), которая не выполняет проверку ошибок.484485Возвращает символ при успехе, `-1` при ошибке с установленным исключением.486487Добавлено в версии 3.3.488489#### `PyObject *PyUnicode_Substring(PyObject *unicode, Py_ssize_t start, Py_ssize_t end)`490491*Возвращаемое значение: новая ссылка.*492493*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*494495Возвращает подстроку *unicode* от индекса символа *start* (включительно) до индекса *end* (исключительно). Отрицательные индексы не поддерживаются. При ошибке устанавливает исключение и возвращает `NULL`.496497Добавлено в версии 3.3.498499#### `Py_UCS4 *PyUnicode_AsUCS4(PyObject *unicode, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)`500501*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*502503Копирует строку *unicode* в буфер UCS4, включая нулевой символ, если *copy\_null* установлен. Возвращает `NULL` и устанавливает исключение при ошибке (в частности, [`SystemError`](https://python-all.ru/3.13/library/exceptions.html#SystemError), если *buflen* меньше длины *unicode*). При успехе возвращается *buffer*.504505Добавлено в версии 3.3.506507#### `Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)`508509*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*510511Копирует строку *unicode* в новый буфер UCS4, выделенный с помощью [`PyMem_Malloc()`](https://python-all.ru/3.13/c-api/memory.html#c.PyMem_Malloc). В случае неудачи возвращается `NULL` с установленным [`MemoryError`](https://python-all.ru/3.13/library/exceptions.html#MemoryError). Возвращаемый буфер всегда содержит дополнительный нулевой код в конце.512513Добавлено в версии 3.3.514515### Кодировка локали516517Текущую кодировку локали можно использовать для декодирования текста из операционной системы.518519#### `PyObject *PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t length, const char *errors)`520521*Возвращаемое значение: новая ссылка.*522523*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*524525Decode 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.13/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.526527Используйте [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize) для декодирования строки из [кодировки файловой системы и обработчика ошибок](https://python-all.ru/3.13/glossary.html#term-filesystem-encoding-and-error-handler).528529Эта функция игнорирует [режим UTF-8 Python](https://python-all.ru/3.13/library/os.html#utf8-mode).530531> **См. также**532>533> Функция [`Py_DecodeLocale()`](https://python-all.ru/3.13/c-api/sys.html#c.Py_DecodeLocale).534535Добавлено в версии 3.3.536537Изменено в версии 3.7: Теперь функция также использует текущую кодировку локали для обработчика ошибок `surrogateescape`, за исключением Android. Ранее для `surrogateescape` использовался [`Py_DecodeLocale()`](https://python-all.ru/3.13/c-api/sys.html#c.Py_DecodeLocale), а для `strict` использовалась текущая кодировка локали.538539#### `PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors)`540541*Возвращаемое значение: новая ссылка.*542543*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*544545Аналогично [`PyUnicode_DecodeLocaleAndSize()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_DecodeLocaleAndSize), но длина строки вычисляется с помощью `strlen()`.546547Добавлено в версии 3.3.548549#### `PyObject *PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)`550551*Возвращаемое значение: новая ссылка.*552553*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*554555Encode 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.13/c-api/unicode.html)). The encoder uses `"strict"` error handler if *errors* is `NULL`. Return a [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes) object. *unicode* cannot contain embedded null characters.556557Используйте [`PyUnicode_EncodeFSDefault()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_EncodeFSDefault) для кодирования строки в [кодировку файловой системы и обработчик ошибок](https://python-all.ru/3.13/glossary.html#term-filesystem-encoding-and-error-handler).558559Эта функция игнорирует [режим UTF-8 Python](https://python-all.ru/3.13/library/os.html#utf8-mode).560561> **См. также**562>563> Функция [`Py_EncodeLocale()`](https://python-all.ru/3.13/c-api/sys.html#c.Py_EncodeLocale).564565Добавлено в версии 3.3.566567Изменено в версии 3.7: Теперь функция также использует текущую кодировку локали для обработчика ошибок `surrogateescape`, за исключением Android. Ранее для `surrogateescape` использовался [`Py_EncodeLocale()`](https://python-all.ru/3.13/c-api/sys.html#c.Py_EncodeLocale), а для `strict` использовалась текущая кодировка локали.568569### Кодировка файловой системы570571Functions encoding to and decoding from the [filesystem encoding and error handler](https://python-all.ru/3.13/glossary.html#term-filesystem-encoding-and-error-handler) ([**PEP 383**](https://python-all.ru/3.13/c-api/unicode.html) and [**PEP 529**](https://python-all.ru/3.13/c-api/unicode.html)).572573Для кодирования имен файлов в [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes) во время разбора аргументов следует использовать конвертер `"O&"`, передавая `PyUnicode_FSConverter()` в качестве функции преобразования:574575#### `int PyUnicode_FSConverter(PyObject *obj, void *result)`576577*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*578579[PyArg\_Parse\* converter](https://python-all.ru/3.13/c-api/arg.html#arg-parsing): encode [`str`](https://python-all.ru/3.13/library/stdtypes.html#str) objects – obtained directly or through the [`os.PathLike`](https://python-all.ru/3.13/library/os.html#os.PathLike) interface – to [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes) using [`PyUnicode_EncodeFSDefault()`](https://python-all.ru/3.13/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.13/c-api/structures.html#c.PyObject)\* (or [PyBytesObject](https://python-all.ru/3.13/c-api/bytes.html#c.PyBytesObject)\*). On success, set the variable to a new [strong reference](https://python-all.ru/3.13/glossary.html#term-strong-reference) to a [bytes object](https://python-all.ru/3.13/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.13/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.580581Если *obj* равно `NULL`, функция освобождает сильную ссылку, сохраненную в переменной, на которую указывает *result*, и возвращает `1`.582583Добавлено в версии 3.1.584585Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.13/glossary.html#term-path-like-object).586587Для декодирования имен файлов в [`str`](https://python-all.ru/3.13/library/stdtypes.html#str) во время разбора аргументов следует использовать конвертер `"O&"`, передавая `PyUnicode_FSDecoder()` в качестве функции преобразования:588589#### `int PyUnicode_FSDecoder(PyObject *obj, void *result)`590591*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*592593[PyArg\_Parse\* converter](https://python-all.ru/3.13/c-api/arg.html#arg-parsing): decode [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes) objects – obtained either directly or indirectly through the [`os.PathLike`](https://python-all.ru/3.13/library/os.html#os.PathLike) interface – to [`str`](https://python-all.ru/3.13/library/stdtypes.html#str) using [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.13/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.13/c-api/structures.html#c.PyObject)\* (or [PyUnicodeObject](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicodeObject)\*). On success, set the variable to a new [strong reference](https://python-all.ru/3.13/glossary.html#term-strong-reference) to a [Unicode object](https://python-all.ru/3.13/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.13/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.594595Если *obj* равно `NULL`, освободите сильную ссылку на объект, на который указывает *result*, и верните `1`.596597Добавлено в версии 3.2.598599Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.13/glossary.html#term-path-like-object).600601#### `PyObject *PyUnicode_DecodeFSDefaultAndSize(const char *str, Py_ssize_t size)`602603*Возвращаемое значение: новая ссылка.*604605*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*606607Декодирует строку из [кодировки файловой системы и обработчика ошибок](https://python-all.ru/3.13/glossary.html#term-filesystem-encoding-and-error-handler).608609Если требуется декодировать строку из текущей кодировки локали, используйте [`PyUnicode_DecodeLocaleAndSize()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_DecodeLocaleAndSize).610611> **См. также**612>613> Функция [`Py_DecodeLocale()`](https://python-all.ru/3.13/c-api/sys.html#c.Py_DecodeLocale).614615Изменено в версии 3.6: Теперь используется [обработчик ошибок файловой системы](https://python-all.ru/3.13/glossary.html#term-filesystem-encoding-and-error-handler).616617#### `PyObject *PyUnicode_DecodeFSDefault(const char *str)`618619*Возвращаемое значение: новая ссылка.*620621*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*622623Декодирует строку, завершающуюся нулевым символом, из [кодировки файловой системы и обработчика ошибок](https://python-all.ru/3.13/glossary.html#term-filesystem-encoding-and-error-handler).624625Если длина строки известна, используйте [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize).626627Изменено в версии 3.6: Теперь используется [обработчик ошибок файловой системы](https://python-all.ru/3.13/glossary.html#term-filesystem-encoding-and-error-handler).628629#### `PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)`630631*Возвращаемое значение: новая ссылка.*632633*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*634635Кодирует объект Unicode в [кодировку и обработчик ошибок файловой системы](https://python-all.ru/3.13/glossary.html#term-filesystem-encoding-and-error-handler) и возвращает [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes). Обратите внимание, что результирующий объект `bytes` может содержать нулевые байты.636637Если требуется закодировать строку в текущую кодировку локали, используйте [`PyUnicode_EncodeLocale()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_EncodeLocale).638639> **См. также**640>641> Функция [`Py_EncodeLocale()`](https://python-all.ru/3.13/c-api/sys.html#c.Py_EncodeLocale).642643Добавлено в версии 3.2.644645Изменено в версии 3.6: Теперь используется [обработчик ошибок файловой системы](https://python-all.ru/3.13/glossary.html#term-filesystem-encoding-and-error-handler).646647### Поддержка wchar\_t648649`wchar_t` поддержка на платформах, которые её поддерживают:650651#### `PyObject *PyUnicode_FromWideChar(const wchar_t *wstr, Py_ssize_t size)`652653*Возвращаемое значение: новая ссылка.*654655*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*656657Создаёт объект Unicode из буфера `wchar_t` *wstr* заданного *размера*. Передача `-1` в качестве *размера* указывает, что функция должна сама вычислить длину с помощью `wcslen()`. В случае ошибки возвращает `NULL`.658659#### `Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *wstr, Py_ssize_t size)`660661*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*662663Копирует содержимое объекта Unicode в буфер `wchar_t` *wstr*. Копируется не более *size* `wchar_t` символов (исключая возможно завершающий нулевой символ). Возвращает количество скопированных `wchar_t` символов или `-1` в случае ошибки.664665Если *wstr* равно `NULL`, вместо этого возвращает *размер*, который потребуется для хранения всего *unicode*, включая завершающий нуль.666667Обратите внимание, что результирующая строка wchar\_t\* может быть как завершена нулевым символом, так и нет. Вызывающий код должен гарантировать, что строка wchar\_t\* завершается нулевым символом, если это требуется приложением. Кроме того, строка wchar\_t\* может содержать нулевые символы, что приведёт к усечению строки при использовании с большинством функций C.668669#### `wchar_t *PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)`670671*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*672673Преобразует объект Unicode в широкую строку. Результирующая строка всегда завершается нулевым символом. Если *size* не равно `NULL`, записывает количество широких символов (исключая завершающий нулевой символ) в *\*size*. Обратите внимание, что результирующая строка `wchar_t` может содержать нулевые символы, что приведёт к усечению строки при использовании с большинством функций C. Если *size* равно `NULL` и строка wchar\_t\* содержит нулевые символы, возбуждается [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError).674675В случае успеха возвращает буфер, выделенный функцией [`PyMem_New`](https://python-all.ru/3.13/c-api/memory.html#c.PyMem_New) (для освобождения используйте [`PyMem_Free()`](https://python-all.ru/3.13/c-api/memory.html#c.PyMem_Free)). При ошибке возвращает `NULL`, а *\*size* не определён. Возбуждает [`MemoryError`](https://python-all.ru/3.13/library/exceptions.html#MemoryError), если выделение памяти не удалось.676677Добавлено в версии 3.2.678679Изменено в версии 3.7: Возбуждает [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError), если *size* равно `NULL` и строка wchar\_t\* содержит нулевые символы.680681## Встроенные кодеки682683Python предоставляет набор встроенных кодеков, написанных на C для скорости. Все эти кодеки могут использоваться напрямую через следующие функции.684685Многие из следующих API принимают два аргумента: encoding и errors, и их семантика совпадает с семантикой соответствующих аргументов встроенного конструктора строк [`str()`](https://python-all.ru/3.13/library/stdtypes.html#str).686687Установка encoding в `NULL` приводит к использованию кодировки по умолчанию, которой является UTF-8. Файловые системные вызовы должны использовать [`PyUnicode_FSConverter()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_FSConverter) для кодирования имён файлов. Внутри используется [кодировка и обработчик ошибок файловой системы](https://python-all.ru/3.13/glossary.html#term-filesystem-encoding-and-error-handler).688689Обработка ошибок задаётся параметром errors, который также может быть установлен в `NULL`, что означает использование обработки по умолчанию, определённой для кодека. По умолчанию для всех встроенных кодеков используется строгий режим (возбуждается [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError)).690691Все кодеки используют схожий интерфейс. Для простоты документированы только отличия от приведённого ниже общего описания.692693### Общие кодеки694695Это общие API кодеков:696697#### `PyObject *PyUnicode_Decode(const char *str, Py_ssize_t size, const char *encoding, const char *errors)`698699*Возвращаемое значение: новая ссылка.*700701*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*702703Создаёт объект Unicode путём декодирования *size* байт закодированной строки *str*. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры встроенной функции [`str()`](https://python-all.ru/3.13/library/stdtypes.html#str). Используемый кодек ищется с помощью реестра кодеков Python. Возвращает `NULL`, если кодек возбудил исключение.704705#### `PyObject *PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)`706707*Возвращаемое значение: новая ссылка.*708709*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*710711Кодирует объект Unicode и возвращает результат в виде объекта bytes. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода [`encode()`](https://python-all.ru/3.13/library/stdtypes.html#str.encode) объекта Unicode. Используемый кодек ищется с помощью реестра кодеков Python. Возвращает `NULL`, если кодек возбудил исключение.712713### Кодеки UTF-8714715Это API кодеков UTF-8:716717#### `PyObject *PyUnicode_DecodeUTF8(const char *str, Py_ssize_t size, const char *errors)`718719*Возвращаемое значение: новая ссылка.*720721*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*722723Создаёт объект Unicode, декодируя *size* байтов UTF-8-закодированной строки *str*. Возвращает `NULL`, если кодек вызвал исключение.724725#### `PyObject *PyUnicode_DecodeUTF8Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`726727*Возвращаемое значение: новая ссылка.*728729*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*730731Если *consumed* равно `NULL`, ведёт себя как [`PyUnicode_DecodeUTF8()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_DecodeUTF8). Если *consumed* не равно `NULL`, неполные конечные последовательности байтов UTF-8 не будут считаться ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.732733#### `PyObject *PyUnicode_AsUTF8String(PyObject *unicode)`734735*Возвращаемое значение: новая ссылка.*736737*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*738739Кодирует объект Unicode в UTF-8 и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.740741Функция завершается ошибкой, если строка содержит суррогатные кодовые точки (`U+D800` - `U+DFFF`).742743#### `const char *PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)`744745*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.10.*746747Возвращает указатель на UTF-8-кодировку объекта Unicode и сохраняет размер закодированного представления (в байтах) в *size*. Аргумент *size* может быть `NULL`; в этом случае размер не сохраняется. Возвращаемый буфер всегда содержит дополнительный нулевой байт в конце (не включён в *size*), независимо от наличия других нулевых кодовых точек.748749При ошибке устанавливает исключение, устанавливает *size* в `-1` (если он не NULL) и возвращает `NULL`.750751Функция завершается ошибкой, если строка содержит суррогатные кодовые точки (`U+D800` - `U+DFFF`).752753Это кеширует UTF-8-представление строки в объекте Unicode, и последующие вызовы будут возвращать указатель на тот же буфер. Вызывающий не отвечает за освобождение буфера. Буфер освобождается, а указатели на него становятся недействительными, когда объект Unicode удаляется сборщиком мусора.754755Добавлено в версии 3.3.756757Изменено в версии 3.7: Тип возвращаемого значения теперь `const char *`, а не `char *`.758759Изменено в версии 3.10: Эта функция является частью [ограниченного API](https://python-all.ru/3.13/c-api/stable.html#limited-c-api).760761#### `const char *PyUnicode_AsUTF8(PyObject *unicode)`762763Как [`PyUnicode_AsUTF8AndSize()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_AsUTF8AndSize), но не сохраняет размер.764765> **Предупреждение**766>767> Эта функция не имеет специального поведения для [нулевых символов](https://python-all.ru/3.13/c-api/unicode.html), встроенных в *unicode*. В результате строки, содержащие нулевые символы, останутся в возвращаемой строке, что некоторые функции C могут интерпретировать как конец строки, приводя к усечению. Если усечение является проблемой, рекомендуется использовать [`PyUnicode_AsUTF8AndSize()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_AsUTF8AndSize) вместо этого.768769Добавлено в версии 3.3.770771Изменено в версии 3.7: Тип возвращаемого значения теперь `const char *`, а не `char *`.772773### Кодеки UTF-32774775Это API кодеков UTF-32:776777#### `PyObject *PyUnicode_DecodeUTF32(const char *str, Py_ssize_t size, const char *errors, int *byteorder)`778779*Возвращаемое значение: новая ссылка.*780781*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*782783Декодирует *size* байтов из буферной строки, закодированной в UTF-32, и возвращает соответствующий объект Unicode. *errors* (если не `NULL`) определяет обработку ошибок. По умолчанию – «strict».784785Если *byteorder* не равно `NULL`, декодер начинает декодирование с указанным порядком байтов:786787```c788*byteorder == -1: little endian789*byteorder == 0:  native order790*byteorder == 1:  big endian791```792793Если `*byteorder` равен нулю и первые четыре байта входных данных являются маркером порядка байтов (BOM), декодер переключается на этот порядок байтов, и BOM не копируется в результирующую строку Unicode. Если `*byteorder` равно `-1` или `1`, любой маркер порядка байтов копируется в выходные данные.794795После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных.796797Если *byteorder* равен `NULL`, кодек запускается в режиме собственного порядка байтов.798799Возвращает `NULL`, если кодек вызвал исключение.800801#### `PyObject *PyUnicode_DecodeUTF32Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)`802803*Возвращаемое значение: новая ссылка.*804805*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*806807Если *consumed* равно `NULL`, ведёт себя как [`PyUnicode_DecodeUTF32()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_DecodeUTF32). Если *consumed* не равно `NULL`, [`PyUnicode_DecodeUTF32Stateful()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_DecodeUTF32Stateful) не будет считать неполные конечные последовательности байтов UTF-32 (например, количество байтов, не делящееся на четыре) ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.808809#### `PyObject *PyUnicode_AsUTF32String(PyObject *unicode)`810811*Возвращаемое значение: новая ссылка.*812813*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*814815Возвращает байтовую строку Python в кодировке UTF-32 в собственном порядке байтов. Строка всегда начинается с метки BOM. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.816817### Кодеки UTF-32818819Это API кодеков UTF-32:820821#### `PyObject *PyUnicode_DecodeUTF32(const char *str, Py_ssize_t size, const char *errors, int *byteorder)`822823*Возвращаемое значение: новая ссылка.*824825*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*826827Декодирует *size* байтов из строки буфера, закодированной в UTF-16, и возвращает соответствующий объект Unicode. *errors* (если не `NULL`) определяет обработку ошибок. По умолчанию используется «strict».828829Если *byteorder* не равно `NULL`, декодер начинает декодирование с указанным порядком байтов:830831```c832*byteorder == -1: little endian833*byteorder == 0:  native order834*byteorder == 1:  big endian835```836837Если `*byteorder` равен нулю и первые два байта входных данных являются меткой порядка байтов (BOM), декодер переключается на этот порядок байтов, а BOM не копируется в результирующую строку Unicode. Если `*byteorder` равен `-1` или `1`, любая метка порядка байтов копируется в выходные данные (что приведёт к символу `\ufeff` или `\ufffe`).838839После завершения `*byteorder` устанавливается в текущий порядок байтов в конце входных данных.840841Если *byteorder* равен `NULL`, кодек запускается в режиме собственного порядка байтов.842843Возвращает `NULL`, если кодек вызвал исключение.844845#### `PyObject *PyUnicode_DecodeUTF16Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)`846847*Возвращаемое значение: новая ссылка.*848849*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*850851Если *consumed* равен `NULL`, ведёт себя как [`PyUnicode_DecodeUTF16()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_DecodeUTF16). Если *consumed* не равен `NULL`, [`PyUnicode_DecodeUTF16Stateful()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_DecodeUTF16Stateful) не будет рассматривать хвостовые неполные последовательности байтов UTF-16 (например, нечётное количество байтов или разбитую суррогатную пару) как ошибку. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.852853#### `PyObject *PyUnicode_AsUTF16String(PyObject *unicode)`854855*Возвращаемое значение: новая ссылка.*856857*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*858859Возвращает байтовую строку Python в кодировке UTF-16 в собственном порядке байтов. Строка всегда начинается с метки BOM. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.860861### Кодеки UTF-7862863Это API кодеков UTF-7:864865#### `PyObject *PyUnicode_DecodeUTF7(const char *str, Py_ssize_t size, const char *errors)`866867*Возвращаемое значение: новая ссылка.*868869*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*870871Создаёт объект Unicode путём декодирования *size* байтов строки, закодированной в UTF-7, *str*. Возвращает `NULL`, если кодек вызвал исключение.872873#### `PyObject *PyUnicode_DecodeUTF7Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`874875*Возвращаемое значение: новая ссылка.*876877*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*878879Если *consumed* равен `NULL`, ведёт себя как [`PyUnicode_DecodeUTF7()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_DecodeUTF7). Если *consumed* не равен `NULL`, хвостовые неполные секции base-64 UTF-7 не будут рассматриваться как ошибка. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.880881### Кодеки Unicode-Escape882883Это API кодеков «Unicode Escape»:884885#### `PyObject *PyUnicode_DecodeUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)`886887*Возвращаемое значение: новая ссылка.*888889*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*890891Создаёт объект Unicode путём декодирования *size* байтов строки, закодированной в Unicode-Escape, *str*. Возвращает `NULL`, если кодек вызвал исключение.892893#### `PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)`894895*Возвращаемое значение: новая ссылка.*896897*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*898899Кодирует объект Unicode с помощью Unicode-Escape и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.900901### Кодеки Raw-Unicode-Escape902903Это API кодеков «Raw Unicode Escape»:904905#### `PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)`906907*Возвращаемое значение: новая ссылка.*908909*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*910911Создаёт объект Unicode путём декодирования *size* байтов строки, закодированной в Raw-Unicode-Escape, *str*. Возвращает `NULL`, если кодек вызвал исключение.912913#### `PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)`914915*Возвращаемое значение: новая ссылка.*916917*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*918919Кодирует объект Unicode с помощью Raw-Unicode-Escape и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.920921### Кодеки Latin-1922923Это API кодеков Latin-1: Latin-1 соответствует первым 256 кодовым позициям Unicode, и только они принимаются кодеками при кодировании.924925#### `PyObject *PyUnicode_DecodeLatin1(const char *str, Py_ssize_t size, const char *errors)`926927*Возвращаемое значение: новая ссылка.*928929*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*930931Создаёт объект Unicode путём декодирования *size* байтов строки *str*, закодированной в Latin-1. Возвращает `NULL`, если кодек выбросил исключение.932933#### `PyObject *PyUnicode_AsLatin1String(PyObject *unicode)`934935*Возвращаемое значение: новая ссылка.*936937*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*938939Кодирует объект Unicode с помощью Latin-1 и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает `NULL`, если кодек выбросил исключение.940941### Кодеки ASCII942943Это API кодеков ASCII. Принимаются только 7-битные данные ASCII. Все остальные коды вызывают ошибки.944945#### `PyObject *PyUnicode_DecodeASCII(const char *str, Py_ssize_t size, const char *errors)`946947*Возвращаемое значение: новая ссылка.*948949*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*950951Создаёт объект Unicode путём декодирования *size* байтов строки *str*, закодированной в ASCII. Возвращает `NULL`, если кодек выбросил исключение.952953#### `PyObject *PyUnicode_AsASCIIString(PyObject *unicode)`954955*Возвращаемое значение: новая ссылка.*956957*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*958959Кодирует объект Unicode с помощью ASCII и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает `NULL`, если кодек выбросил исключение.960961### Кодеки с таблицей символов962963Этот кодек особенный тем, что его можно использовать для реализации множества различных кодеков (именно так и были получены большинство стандартных кодеков, входящих в пакет `encodings`). Кодек использует отображения для кодирования и декодирования символов. Предоставляемые объекты отображения должны поддерживать интерфейс отображения [`__getitem__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__getitem__); словари и последовательности прекрасно работают.964965Это API кодеков отображения:966967#### `PyObject *PyUnicode_DecodeCharmap(const char *str, Py_ssize_t length, PyObject *mapping, const char *errors)`968969*Возвращаемое значение: новая ссылка.*970971*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*972973Создаёт объект Unicode путём декодирования *size* байтов закодированной строки *str* с использованием заданного объекта *mapping*. Возвращает `NULL`, если кодек выбросил исключение.974975Если *mapping* равен `NULL`, будет применяться декодирование Latin-1. В противном случае *mapping* должен отображать порядковые номера байтов (целые числа в диапазоне от 0 до 255) в строки Unicode, целые числа (которые затем интерпретируются как кодовые позиции Unicode) или `None`. Неотображённые байты данных – те, которые вызывают [`LookupError`](https://python-all.ru/3.13/library/exceptions.html#LookupError), а также те, которые отображаются в `None`, `0xFFFE` или `'\ufffe'`, считаются неопределёнными отображениями и вызывают ошибку.976977#### `PyObject *PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)`978979*Возвращаемое значение: новая ссылка.*980981*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*982983Кодирует объект Unicode с использованием заданного объекта *mapping* и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает `NULL`, если кодек выбросил исключение.984985Объект *mapping* должен отображать целые числа – кодовые позиции Unicode – в объекты bytes, целые числа в диапазоне от 0 до 255 или `None`. Неотображённые кодовые позиции символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.13/library/exceptions.html#LookupError)), а также отображённые в `None` считаются «неопределённым отображением» и вызывают ошибку.986987Следующее API кодека особенное тем, что отображает Unicode в Unicode.988989#### `PyObject *PyUnicode_Translate(PyObject *unicode, PyObject *table, const char *errors)`990991*Возвращаемое значение: новая ссылка.*992993*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*994995Преобразует строку, применяя к ней таблицу отображения символов, и возвращает результирующий объект Unicode. Возвращает `NULL`, если кодек выбросил исключение.996997Таблица отображения должна отображать целые числа – кодовые позиции Unicode – в целые числа – кодовые позиции Unicode – или в `None` (вызывает удаление символа).998999Таблицы отображения должны лишь предоставлять интерфейс [`__getitem__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__getitem__); словари и последовательности работают хорошо. Неотображённые кодовые позиции символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.13/library/exceptions.html#LookupError)) остаются нетронутыми и копируются как есть.10001001*errors* имеет обычное для кодеков значение. Он может быть `NULL`, что означает использование обработки ошибок по умолчанию.10021003### Кодеки MBCS для Windows10041005Это API кодеков MBCS. В настоящее время они доступны только в Windows и используют преобразователи Win32 MBCS для выполнения преобразований. Обратите внимание, что MBCS (или DBCS) – это класс кодировок, а не одна конкретная. Целевая кодировка определяется пользовательскими настройками на машине, где выполняется кодек.10061007#### `PyObject *PyUnicode_DecodeMBCS(const char *str, Py_ssize_t size, const char *errors)`10081009*Возвращаемое значение: новая ссылка.*10101011*Часть [стабильного ABI](https://python-all.ru/3.13/c-api/stable.html#stable) на Windows с версии 3.7.*10121013Создаёт объект Unicode путём декодирования *size* байтов строки *str*, закодированной в MBCS. Возвращает `NULL`, если кодек выбросил исключение.10141015#### `PyObject *PyUnicode_DecodeMBCSStateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`10161017*Возвращаемое значение: новая ссылка.*10181019*Часть [стабильного ABI](https://python-all.ru/3.13/c-api/stable.html#stable) на Windows с версии 3.7.*10201021Если *consumed* равно `NULL`, поведение аналогично [`PyUnicode_DecodeMBCS()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_DecodeMBCS). Если *consumed* не равно `NULL`, [`PyUnicode_DecodeMBCSStateful()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_DecodeMBCSStateful) не будет декодировать конечный ведущий байт, а количество декодированных байт будет сохранено в *consumed*.10221023#### `PyObject *PyUnicode_DecodeCodePageStateful(int code_page, const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`10241025*Возвращаемое значение: новая ссылка.*10261027*Часть [стабильного ABI](https://python-all.ru/3.13/c-api/stable.html#stable) на Windows с версии 3.7.*10281029Аналогично [`PyUnicode_DecodeMBCSStateful()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_DecodeMBCSStateful), но использует кодовую страницу, указанную в *code\_page*.10301031#### `PyObject *PyUnicode_AsMBCSString(PyObject *unicode)`10321033*Возвращаемое значение: новая ссылка.*10341035*Часть [стабильного ABI](https://python-all.ru/3.13/c-api/stable.html#stable) на Windows с версии 3.7.*10361037Кодирует объект Unicode с помощью MBCS и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.10381039#### `PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)`10401041*Возвращаемое значение: новая ссылка.*10421043*Часть [стабильного ABI](https://python-all.ru/3.13/c-api/stable.html#stable) на Windows с версии 3.7.*10441045Кодирует объект Unicode с помощью указанной кодовой страницы и возвращает объект bytes. Возвращает `NULL`, если кодек вызвал исключение. Используйте кодовую страницу `CP_ACP` для получения кодировщика MBCS.10461047Добавлено в версии 3.3.10481049## Методы и слот-функции10501051Следующие API могут обрабатывать объекты Unicode и строки на входе (в описаниях мы называем их строками) и возвращают объекты Unicode или целые числа по необходимости.10521053Все они возвращают `NULL` или `-1` в случае возникновения исключения.10541055#### `PyObject *PyUnicode_Concat(PyObject *left, PyObject *right)`10561057*Возвращаемое значение: новая ссылка.*10581059*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*10601061Объединяет две строки, возвращая новую строку Unicode.10621063#### `PyObject *PyUnicode_Split(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)`10641065*Возвращаемое значение: новая ссылка.*10661067*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*10681069Разделяет строку, возвращая список строк Unicode. Если *sep* равно `NULL`, разделение происходит по всем пробельным подстрокам. В противном случае разделение происходит по указанному разделителю. Будет выполнено не более *maxsplit* разбиений. Если значение отрицательное, ограничение не задано. Разделители не включаются в результирующий список.10701071При ошибке возвращает `NULL` с установленным исключением.10721073Эквивалентно [`str.split()`](https://python-all.ru/3.13/library/stdtypes.html#str.split).10741075#### `PyObject *PyUnicode_RSplit(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)`10761077*Возвращаемое значение: новая ссылка.*10781079*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*10801081Аналогично [`PyUnicode_Split()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_Split), но разделение начинается с конца строки.10821083При ошибке возвращает `NULL` с установленным исключением.10841085Эквивалентно [`str.rsplit()`](https://python-all.ru/3.13/library/stdtypes.html#str.rsplit).10861087#### `PyObject *PyUnicode_Splitlines(PyObject *unicode, int keepends)`10881089*Возвращаемое значение: новая ссылка.*10901091*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*10921093Разделяет строку Unicode по символам конца строки, возвращая список строк Unicode. CRLF считается одним разрывом строки. Если *keepends* равно `0`, символы конца строки не включаются в результирующие строки.10941095#### `PyObject *PyUnicode_Partition(PyObject *unicode, PyObject *sep)`10961097*Возвращаемое значение: новая ссылка.*10981099*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*11001101Разделяет строку Unicode по первому вхождению *sep* и возвращает кортеж из трёх элементов: часть до разделителя, сам разделитель и часть после разделителя. Если разделитель не найден, возвращает кортеж из трёх элементов: саму строку, а затем две пустые строки.11021103*sep* не должен быть пустым.11041105При ошибке возвращает `NULL` с установленным исключением.11061107Эквивалентно [`str.partition()`](https://python-all.ru/3.13/library/stdtypes.html#str.partition).11081109#### `PyObject *PyUnicode_RPartition(PyObject *unicode, PyObject *sep)`11101111*Возвращаемое значение: новая ссылка.*11121113*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*11141115Аналогично [`PyUnicode_Partition()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_Partition), но разделяет строку Unicode по последнему вхождению *sep*. Если разделитель не найден, возвращает кортеж из трёх элементов: две пустые строки, а затем сама строка.11161117*sep* не должен быть пустым.11181119При ошибке возвращает `NULL` с установленным исключением.11201121Эквивалентно [`str.rpartition()`](https://python-all.ru/3.13/library/stdtypes.html#str.rpartition).11221123#### `PyObject *PyUnicode_Join(PyObject *separator, PyObject *seq)`11241125*Возвращаемое значение: новая ссылка.*11261127*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*11281129Объединяет последовательность строк, используя заданный *разделитель*, и возвращает полученную Unicode-строку.11301131#### `Py_ssize_t PyUnicode_Tailmatch(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)`11321133*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*11341135Возвращает `1`, если *substr* совпадает с `unicode[start:end]` на заданном хвосте (*direction* == `-1` означает проверку на совпадение с началом, *direction* == `1` – с концом), иначе `0`. Возвращает `-1`, если произошла ошибка.11361137#### `Py_ssize_t PyUnicode_Find(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)`11381139*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*11401141Возвращает первую позицию *substr* в `unicode[start:end]`, используя заданное *direction* (*direction* == `1` означает прямой поиск, *direction* == `-1` – обратный). Возвращаемое значение – индекс первого совпадения; значение `-1` означает, что совпадений не найдено, а `-2` – что произошла ошибка и было установлено исключение.11421143#### `Py_ssize_t PyUnicode_FindChar(PyObject *unicode, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)`11441145*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*11461147Возвращает первую позицию символа *ch* в `unicode[start:end]`, используя заданное *direction* (*direction* == `1` означает прямой поиск, *direction* == `-1` – обратный). Возвращаемое значение – индекс первого совпадения; значение `-1` означает, что совпадений не найдено, а `-2` – что произошла ошибка и было установлено исключение.11481149Добавлено в версии 3.3.11501151Изменено в версии 3.7: *start* и *end* теперь скорректированы, чтобы вести себя как `unicode[start:end]`.11521153#### `Py_ssize_t PyUnicode_Count(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end)`11541155*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*11561157Возвращает количество неперекрывающихся вхождений *substr* в `unicode[start:end]`. Возвращает `-1`, если произошла ошибка.11581159#### `PyObject *PyUnicode_Replace(PyObject *unicode, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)`11601161*Возвращаемое значение: новая ссылка.*11621163*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*11641165Заменяет не более *maxcount* вхождений *substr* в *unicode* на *replstr* и возвращает полученный Unicode-объект. *maxcount* == `-1` означает заменить все вхождения.11661167#### `int PyUnicode_Compare(PyObject *left, PyObject *right)`11681169*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*11701171Сравнивает две строки и возвращает `-1`, `0`, `1` для случаев меньше, равно и больше соответственно.11721173Эта функция возвращает `-1` при ошибке, поэтому для проверки на ошибки следует вызывать [`PyErr_Occurred()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Occurred).11741175#### `int PyUnicode_EqualToUTF8AndSize(PyObject *unicode, const char *string, Py_ssize_t size)`11761177*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable), начиная с версии 3.13.*11781179Сравнивает Unicode-объект с буфером символов, который интерпретируется как закодированный в UTF-8 или ASCII, и возвращает true (`1`), если они равны, или false (`0`) в противном случае. Если Unicode-объект содержит суррогатные кодовые точки (`U+D800` - `U+DFFF`) или C-строка не является корректным UTF-8, возвращается false (`0`).11801181Эта функция не вызывает исключений.11821183Добавлено в версии 3.13.11841185#### `int PyUnicode_EqualToUTF8(PyObject *unicode, const char *string)`11861187*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable), начиная с версии 3.13.*11881189Аналогично [`PyUnicode_EqualToUTF8AndSize()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_EqualToUTF8AndSize), но длину *string* вычисляет с помощью `strlen()`. Если Unicode-объект содержит нулевые символы, возвращается false (`0`).11901191Добавлено в версии 3.13.11921193#### `int PyUnicode_CompareWithASCIIString(PyObject *unicode, const char *string)`11941195*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*11961197Сравнивает Unicode-объект *unicode* со строкой *string* и возвращает `-1`, `0`, `1` для случаев меньше, равно и больше соответственно. Рекомендуется передавать только ASCII-строки, но функция интерпретирует входную строку как ISO-8859-1, если она содержит не-ASCII символы.11981199Эта функция не вызывает исключений.12001201#### `PyObject *PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)`12021203*Возвращаемое значение: новая ссылка.*12041205*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*12061207Сравнивает две строки Unicode и возвращает одно из следующих значений:12081209- `NULL` в случае, если возникло исключение1210- [`Py_True`](https://python-all.ru/3.13/c-api/bool.html#c.Py_True) или [`Py_False`](https://python-all.ru/3.13/c-api/bool.html#c.Py_False) для успешных сравнений1211- [`Py_NotImplemented`](https://python-all.ru/3.13/c-api/object.html#c.Py_NotImplemented) в случае, если комбинация типов неизвестна12121213Возможные значения для *op*: [`Py_GT`](https://python-all.ru/3.13/c-api/typeobj.html#c.Py_GT), [`Py_GE`](https://python-all.ru/3.13/c-api/typeobj.html#c.Py_GE), [`Py_EQ`](https://python-all.ru/3.13/c-api/typeobj.html#c.Py_EQ), [`Py_NE`](https://python-all.ru/3.13/c-api/typeobj.html#c.Py_NE), [`Py_LT`](https://python-all.ru/3.13/c-api/typeobj.html#c.Py_LT) и [`Py_LE`](https://python-all.ru/3.13/c-api/typeobj.html#c.Py_LE).12141215#### `PyObject *PyUnicode_Format(PyObject *format, PyObject *args)`12161217*Возвращаемое значение: новая ссылка.*12181219*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*12201221Возвращает новый строковый объект из *format* и *args*; это аналог `format % args`.12221223#### `int PyUnicode_Contains(PyObject *unicode, PyObject *substr)`12241225*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*12261227Проверяет, содержится ли *substr* в *unicode*, и возвращает true или false соответственно.12281229*substr* должен приводиться к строке Unicode из одного элемента. `-1` возвращается в случае ошибки.12301231#### `void PyUnicode_InternInPlace(PyObject **p_unicode)`12321233*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*12341235Интернирует аргумент \*[p\_unicode](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_InternInPlace) на месте. Аргумент должен быть адресом переменной-указателя, указывающей на объект строки Unicode Python. Если уже существует интернированная строка, совпадающая с \*p\_unicode, то он устанавливает \*p\_unicode на неё (освобождая ссылку на старый строковый объект и создавая новую [сильную ссылку](https://python-all.ru/3.13/glossary.html#term-strong-reference) на интернированную строку), в противном случае он оставляет \*p\_unicode без изменений и интернирует её.12361237(Пояснение: хотя здесь много говорится о ссылках, считайте эту функцию нейтральной по отношению к ссылкам. Вы должны владеть объектом, который передаёте; после вызова вы больше не владеете переданной ссылкой, но приобретаете новую ссылку на результат.)12381239Эта функция никогда не вызывает исключение. При ошибке она оставляет свой аргумент без изменений, не интернируя его.12401241Экземпляры подклассов [`str`](https://python-all.ru/3.13/library/stdtypes.html#str) не могут быть интернированы, то есть [PyUnicode\_CheckExact](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_CheckExact)(\*[p\_unicode](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_InternInPlace)) должно быть истинно. Если это не так, то – как и при любой другой ошибке – аргумент остаётся без изменений.12421243Обратите внимание, что интернированные строки не являются «бессмертными». Вы должны сохранять ссылку на результат, чтобы получить выгоду от интернирования.12441245#### `PyObject *PyUnicode_InternFromString(const char *str)`12461247*Возвращаемое значение: новая ссылка.*12481249*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*12501251Комбинация [`PyUnicode_FromString()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_FromString) и [`PyUnicode_InternInPlace()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_InternInPlace), предназначенная для статически выделенных строк.12521253Возвращает новую («владение») ссылку либо на новый интернированный объект строки Unicode, либо на ранее интернированный строковый объект с тем же значением.12541255Python может сохранять ссылку на результат или сделать его [бессмертным](https://python-all.ru/3.13/glossary.html#term-immortal), предотвращая его своевременную сборку мусора. Для интернирования неограниченного количества различных строк, например, поступающих от пользователя, предпочтительнее вызывать [`PyUnicode_FromString()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_FromString) и [`PyUnicode_InternInPlace()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_InternInPlace) напрямую.1256