unicode.md

1> **Источник:** https://python-all.ru/3.16/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.16/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.16/c-api/unicode.html#c.Py_UNICODE) было удалено начиная с Python 3.12 вместе с устаревшими API. См. [**PEP 623**](https://python-all.ru/3.16/c-api/unicode.html) для получения дополнительной информации.1819### Тип Unicode2021Это основные типы объектов Unicode, используемые в реализации Unicode в Python:2223#### `PyTypeObject PyUnicode_Type`2425*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*2627Этот экземпляр [`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).2829#### `PyTypeObject PyUnicodeIter_Type`3031*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*3233Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.16/c-api/type.html#c.PyTypeObject) представляет тип итератора Unicode в Python. Он используется для итерации по объектам строк Unicode.3435#### `type Py_UCS4`3637#### `type Py_UCS2`3839#### `type Py_UCS1`4041*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*4243Эти типы являются псевдонимами для беззнаковых целочисленных типов, достаточно широких для хранения символов размером 32, 16 и 8 бит соответственно. При работе с отдельными символами Unicode используйте [`Py_UCS4`](https://python-all.ru/3.16/c-api/unicode.html#c.Py_UCS4).4445Добавлено в версии 3.3.4647#### `type PyASCIIObject`4849#### `type PyCompactUnicodeObject`5051#### `type PyUnicodeObject`5253Эти подтипы [`PyObject`](https://python-all.ru/3.16/c-api/structures.html#c.PyObject) представляют объект Unicode в Python. В почти всех случаях их не следует использовать напрямую, так как все функции API, работающие с объектами Unicode, принимают и возвращают указатели `PyObject`.5455Добавлено в версии 3.3.5657Структуру конкретного объекта можно определить с помощью следующих макросов. Макросы не завершаются ошибкой; их поведение не определено, если их аргумент не является объектом Unicode Python.5859#### `PyUnicode_IS_COMPACT(o)`6061True, если *o* использует структуру [`PyCompactUnicodeObject`](https://python-all.ru/3.16/c-api/unicode.html#c.PyCompactUnicodeObject).6263Добавлено в версии 3.3.6465#### `PyUnicode_IS_COMPACT_ASCII(o)`6667True, если *o* использует структуру [`PyASCIIObject`](https://python-all.ru/3.16/c-api/unicode.html#c.PyASCIIObject).6869Добавлено в версии 3.3.7071Следующие API представляют собой макросы C и статические встроенные функции для быстрых проверок и доступа к внутренним данным только для чтения объектов Unicode:7273#### `int PyUnicode_Check(PyObject *obj)`7475Возвращает true, если объект *obj* является объектом Unicode или экземпляром подтипа Unicode. Эта функция всегда завершается успешно.7677#### `int PyUnicode_CheckExact(PyObject *obj)`7879Возвращает true, если объект *obj* является объектом Unicode, но не экземпляром подтипа. Эта функция всегда завершается успешно.8081#### `Py_ssize_t PyUnicode_GET_LENGTH(PyObject *unicode)`8283Возвращает длину строки Unicode в кодовых точках. *unicode* должен быть объектом Unicode в «каноническом» представлении (не проверяется).8485Добавлено в версии 3.3.8687#### `Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *unicode)`8889#### `Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *unicode)`9091#### `Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *unicode)`9293Возвращает указатель на каноническое представление, приведённый к целочисленным типам UCS1, UCS2 или UCS4 для прямого доступа к символам. Не выполняется проверок, имеет ли каноническое представление правильный размер символа; используйте [`PyUnicode_KIND()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_KIND), чтобы выбрать подходящую функцию.9495Добавлено в версии 3.3.9697#### `PyUnicode_1BYTE_KIND`9899#### `PyUnicode_2BYTE_KIND`100101#### `PyUnicode_4BYTE_KIND`102103Возвращает значения макроса [`PyUnicode_KIND()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_KIND).104105Добавлено в версии 3.3.106107Изменено в версии 3.12: `PyUnicode_WCHAR_KIND` был удалён.108109#### `int PyUnicode_KIND(PyObject *unicode)`110111Возвращает одну из констант вида PyUnicode (см. выше), которые указывают, сколько байт на символ использует данный объект Unicode для хранения своих данных. *unicode* должен быть объектом Unicode в «каноническом» представлении (не проверяется).112113Добавлено в версии 3.3.114115#### `void *PyUnicode_DATA(PyObject *unicode)`116117Возвращает указатель void на сырой буфер Unicode. *unicode* должен быть объектом Unicode в «каноническом» представлении (не проверяется).118119Добавлено в версии 3.3.120121#### `void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)`122123Записывает кодовую точку *value* по указанному *индексу* (начиная с нуля) в строке.124125Значение *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) также применимы.126127Функция не выполняет проверок ни одного из своих требований и предназначена для использования в циклах.128129Добавлено в версии 3.3.130131#### `Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)`132133Читает кодовую точку из канонического представления *data* (полученного с помощью [`PyUnicode_DATA()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DATA)). Никаких проверок или вызовов готовности не выполняется.134135Добавлено в версии 3.3.136137#### `Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)`138139Читает символ из объекта Unicode *unicode*, который должен быть в «каноническом» представлении. Это менее эффективно, чем [`PyUnicode_READ()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_READ), если выполняется несколько последовательных чтений.140141Добавлено в версии 3.3.142143#### `Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *unicode)`144145Возвращает максимальную кодовую точку, подходящую для создания другой строки на основе *unicode*, который должен быть в «каноническом» представлении. Это всегда приближение, но более эффективное, чем перебор строки.146147Добавлено в версии 3.3.148149#### `int PyUnicode_IsIdentifier(PyObject *unicode)`150151*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*152153Возвращает `1`, если строка является допустимым идентификатором согласно определению языка, раздел [Имена (идентификаторы и ключевые слова)](https://python-all.ru/3.16/reference/lexical_analysis.html#identifiers). В противном случае возвращает `0`.154155Изменено в версии 3.9: Функция больше не вызывает [`Py_FatalError()`](https://python-all.ru/3.16/c-api/sys.html#c.Py_FatalError), если строка не готова.156157#### `unsigned int PyUnicode_IS_ASCII(PyObject *unicode)`158159Возвращает true, если строка содержит только символы ASCII. Эквивалентно [`str.isascii()`](https://python-all.ru/3.16/library/stdtypes.html#str.isascii).160161Добавлено в версии 3.2.162163#### `Py_hash_t PyUnstable_Unicode_GET_CACHED_HASH(PyObject *str)`164165> *Это [нестабильное API](https://python-all.ru/3.16/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*166167Если хеш *str*, возвращаемый [`PyObject_Hash()`](https://python-all.ru/3.16/c-api/object.html#c.PyObject_Hash), был кэширован и доступен немедленно, возвращает его. В противном случае возвращает `-1` *без* установки исключения.168169Если *str* не является строкой (то есть если `PyUnicode_Check(obj)` ложно), поведение не определено.170171Эта функция никогда не завершается исключением.172173Обратите внимание, что не гарантируется, когда кешируется хеш объекта, и наличие или отсутствие кешированного хеша не означает, что строка обладает какими-либо другими свойствами.174175### Свойства символов Unicode176177Unicode предоставляет множество различных свойств символов. Наиболее востребованные из них доступны через следующие макросы, которые сопоставляются с функциями на C в зависимости от конфигурации Python.178179#### `int Py_UNICODE_ISSPACE(Py_UCS4 ch)`180181Возвращает `1` или `0` в зависимости от того, является ли *ch* пробельным символом.182183#### `int Py_UNICODE_ISLOWER(Py_UCS4 ch)`184185Возвращает `1` или `0` в зависимости от того, является ли *ch* символом в нижнем регистре.186187#### `int Py_UNICODE_ISUPPER(Py_UCS4 ch)`188189Возвращает `1` или `0` в зависимости от того, является ли *ch* символом в верхнем регистре.190191#### `int Py_UNICODE_ISTITLE(Py_UCS4 ch)`192193Возвращает `1` или `0` в зависимости от того, является ли *ch* символом в регистре заголовка (titlecase).194195#### `int Py_UNICODE_ISLINEBREAK(Py_UCS4 ch)`196197Возвращает `1` или `0` в зависимости от того, является ли *ch* символом разрыва строки.198199#### `int Py_UNICODE_ISDECIMAL(Py_UCS4 ch)`200201Возвращает `1` или `0` в зависимости от того, является ли *ch* десятичным символом.202203#### `int Py_UNICODE_ISDIGIT(Py_UCS4 ch)`204205Возвращает `1` или `0` в зависимости от того, является ли *ch* цифровым символом.206207#### `int Py_UNICODE_ISNUMERIC(Py_UCS4 ch)`208209Возвращает `1` или `0` в зависимости от того, является ли *ch* числовым символом.210211#### `int Py_UNICODE_ISALPHA(Py_UCS4 ch)`212213Возвращает `1` или `0` в зависимости от того, является ли *ch* буквенным символом.214215#### `int Py_UNICODE_ISALNUM(Py_UCS4 ch)`216217Возвращает `1` или `0` в зависимости от того, является ли *ch* буквенно-цифровым символом.218219#### `int Py_UNICODE_ISPRINTABLE(Py_UCS4 ch)`220221Возвращает `1` или `0` в зависимости от того, является ли *ch* печатным символом в смысле [`str.isprintable()`](https://python-all.ru/3.16/library/stdtypes.html#str.isprintable).222223Эти API можно использовать для быстрых прямых преобразований символов:224225#### `Py_UCS4 Py_UNICODE_TOLOWER(Py_UCS4 ch)`226227Возвращает символ *ch*, преобразованный в нижний регистр.228229#### `Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4 ch)`230231Возвращает символ *ch*, преобразованный в верхний регистр.232233#### `Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4 ch)`234235Возвращает символ *ch*, приведённый к регистру заголовка.236237#### `int Py_UNICODE_TODECIMAL(Py_UCS4 ch)`238239Возвращает символ *ch*, преобразованный в положительное десятичное целое. Возвращает `-1`, если это невозможно. Эта функция не вызывает исключений.240241#### `int Py_UNICODE_TODIGIT(Py_UCS4 ch)`242243Возвращает символ *ch*, преобразованный в целое число из одной цифры. Возвращает `-1`, если это невозможно. Эта функция не вызывает исключений.244245#### `double Py_UNICODE_TONUMERIC(Py_UCS4 ch)`246247Возвращает символ *ch*, преобразованный в число двойной точности (double). Возвращает `-1.0`, если это невозможно. Эта функция не вызывает исключений.248249Эти API можно использовать для работы с суррогатами:250251#### `int Py_UNICODE_IS_SURROGATE(Py_UCS4 ch)`252253Проверяет, является ли *ch* суррогатом (`0xD800 <= ch <= 0xDFFF`).254255#### `int Py_UNICODE_IS_HIGH_SURROGATE(Py_UCS4 ch)`256257Проверяет, является ли *ch* старшим суррогатом (`0xD800 <= ch <= 0xDBFF`).258259#### `int Py_UNICODE_IS_LOW_SURROGATE(Py_UCS4 ch)`260261Проверяет, является ли *ch* младшим суррогатом (`0xDC00 <= ch <= 0xDFFF`).262263#### `Py_UCS4 Py_UNICODE_HIGH_SURROGATE(Py_UCS4 ch)`264265Возвращает старший суррогат UTF-16 (от `0xD800` до `0xDBFF`) для кодовой точки Unicode в диапазоне `[0x10000; 0x10FFFF]`.266267#### `Py_UCS4 Py_UNICODE_LOW_SURROGATE(Py_UCS4 ch)`268269Возвращает младший суррогат UTF-16 (от `0xDC00` до `0xDFFF`) для кодовой точки Unicode в диапазоне `[0x10000; 0x10FFFF]`.270271#### `Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)`272273Соединяет две суррогатные кодовые точки и возвращает одно значение [`Py_UCS4`](https://python-all.ru/3.16/c-api/unicode.html#c.Py_UCS4). *high* и *low* – это соответственно старший и младший суррогаты в суррогатной паре. *high* должен быть в диапазоне `[0xD800; 0xDBFF]`, а *low* – в диапазоне `[0xDC00; 0xDFFF]`.274275### Создание строк Unicode и доступ к ним276277Для создания объектов Unicode и доступа к их базовым свойствам последовательности используйте следующие API:278279#### `PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)`280281*Возвращаемое значение: новая ссылка.*282283Создаёт новый объект Unicode. *maxchar* должен быть истинным максимальным кодом, который будет помещён в строку. В качестве приближения его можно округлить до ближайшего значения из последовательности 127, 255, 65535, 1114111.284285При ошибке устанавливает исключение и возвращает `NULL`.286287После создания строку можно заполнить с помощью [`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) или аналогичных функций. Поскольку строки считаются неизменяемыми, следует избегать «использования» результата во время его изменения. В частности, до того как строка заполнена окончательным содержимым, она:288289- не должна хэшироваться,290- не должна быть [`converted to UTF-8`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_AsUTF8AndSize) или другим неканоническим представлением,291- не должно изменяться её количество ссылок,292- не должна передаваться коду, который может сделать что-либо из перечисленного.293294Этот список не является исчерпывающим. Избегать такого использования – ваша обязанность; Python не всегда проверяет эти требования.295296Чтобы случайно не раскрыть частично записанный строковый объект, предпочтительнее использовать API [`PyUnicodeWriter`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicodeWriter) или одну из функций `PyUnicode_From*`, приведённых ниже.297298Добавлено в версии 3.3.299300#### `PyObject *PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)`301302*Возвращаемое значение: новая ссылка.*303304Создаёт новый объект 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 байта на символ, в зависимости от вида.305306При необходимости входной *буфер* копируется и преобразуется в каноническое представление. Например, если *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)).307308Добавлено в версии 3.3.309310#### `PyObject *PyUnicode_FromStringAndSize(const char *str, Py_ssize_t size)`311312*Возвращаемое значение: новая ссылка.*313314*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*315316Создаёт объект Unicode из символьного буфера *str*. Байты интерпретируются как закодированные в UTF-8. Буфер копируется в новый объект. Возвращаемое значение может быть разделяемым объектом, т.е. изменение данных не допускается.317318Эта функция вызывает [`SystemError`](https://python-all.ru/3.16/library/exceptions.html#SystemError) в следующих случаях:319320- *size* \< 0321- *str* равен `NULL` и *size* \> 0322323Изменено в версии 3.12: *str* == `NULL` при *size* \> 0 больше не допускается.324325#### `PyObject *PyUnicode_FromString(const char *str)`326327*Возвращаемое значение: новая ссылка.*328329*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*330331Создаёт объект Unicode из UTF-8-кодированного нуль-терминированного символьного буфера *str*.332333#### `PyObject *PyUnicode_FromFormat(const char *format, ...)`334335*Возвращаемое значение: новая ссылка.*336337*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*338339Принимает строку формата в стиле C `printf()` *format* и переменное число аргументов, вычисляет размер результирующей строки Python Unicode и возвращает строку с отформатированными значениями. Переменные аргументы должны быть типами C и строго соответствовать символам формата в *format* ASCII-кодированной строке.340341Спецификатор преобразования содержит два или более символа и состоит из следующих компонентов, которые должны располагаться в указанном порядке:3423431. Символ `'%'`, обозначающий начало спецификатора.3442. Флаги преобразования (необязательно), влияющие на результат для некоторых типов преобразования.3453. Минимальная ширина поля (необязательно). Если задана как `'*'` (звёздочка), фактическая ширина передаётся в следующем аргументе, который должен иметь тип int, а преобразуемый объект следует после минимальной ширины поля и необязательной точности.3464. Точность (необязательно), задаётся как `'.'` (точка), за которой следует точность. Если указана как `'*'` (звёздочка), фактическая точность передаётся в следующем аргументе, который должен иметь тип int, а преобразуемое значение следует после точности.3475. Модификатор длины (необязательно).3486. Тип преобразования.349350Символы флагов преобразования:351352| Флаг | Значение |353| --- | --- |354| `0` | Для числовых значений преобразование будет дополняться нулями. |355| `-` | Преобразованное значение выравнивается по левому краю (отменяет флаг `0` , если указаны оба). |356357Модификаторы длины для следующих целочисленных преобразований (`d`, `i`, `o`, `u`, `x` или `X`) определяют тип аргумента (по умолчанию int):358359| Модификатор | Типы |360| --- | --- |361| `l` | long или unsigned long |362| `ll` | long long или unsigned long long |363| `j` | `intmax_t` или `uintmax_t` |364| `z` | `size_t` или `ssize_t` |365| `t` | `ptrdiff_t` |366367Модификатор длины `l` для следующих преобразований `s` или `V` указывает, что тип аргумента – const wchar\_t\*.368369Спецификаторы преобразования:370371| Спецификатор преобразования | Тип | Описание |372| --- | --- | --- |373| `%` | *н/д* | Литеральный символ `%`. |374| `d`, `i` | Указывается модификатором длины | Десятичное представление знакового целого C. |375| `u` | Указывается модификатором длины | Десятичное представление беззнакового целого C. |376| `o` | Указывается модификатором длины | Восьмеричное представление беззнакового целого C. |377| `x` | Указывается модификатором длины | Шестнадцатеричное представление беззнакового целого C (строчные буквы). |378| `X` | Указывается модификатором длины | Шестнадцатеричное представление беззнакового целого C (прописные буквы). |379| `c` | int | Один символ. |380| `s` | const char\* или const wchar\_t\* | Символьный массив C с нулевым завершителем. |381| `p` | const void\* | Шестнадцатеричное представление указателя C. В основном эквивалентно `printf("%p")`, за исключением того, что гарантированно начинается с литерала `0x` независимо от того, что возвращает `printf` на платформе. |382| `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). |383| `U` | [PyObject](https://python-all.ru/3.16/c-api/structures.html#c.PyObject)\* | Объект Unicode. |384| `V` | [PyObject](https://python-all.ru/3.16/c-api/structures.html#c.PyObject)\*, const char\* или const wchar\_t\* | Объект Unicode (который может быть `NULL`) и завершающийся нулевым байтом символьный массив C в качестве второго параметра (который будет использован, если первый параметр равен `NULL`). |385| `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). |386| `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). |387| `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). |388| `#T` | [PyObject](https://python-all.ru/3.16/c-api/structures.html#c.PyObject)\* | Аналогично формату `T`, но использует двоеточие (`:`) в качестве разделителя между именем модуля и квалифицированным именем. |389| `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). |390| `#N` | [PyTypeObject](https://python-all.ru/3.16/c-api/type.html#c.PyTypeObject)\* | Похож на формат `N`, но использует двоеточие (`:`) в качестве разделителя между именем модуля и квалифицированным именем. |391392> **Примечание**393>394> Единицей форматтера ширины является количество символов, а не байтов. Единицей форматтера точности является количество байтов или `wchar_t` элементов (если используется модификатор длины `l`) для `"%s"` и `"%V"` (если аргумент `PyObject*` равен `NULL`), а также количество символов для `"%A"`, `"%U"`, `"%S"`, `"%R"` и `"%V"` (если аргумент `PyObject*` не равен `NULL`).395396> **Примечание**397>398> В отличие от C `printf()` флаг `0` действует, даже если для целочисленных преобразований задана точность (`d`, `i`, `u`, `o`, `x` или `X`).399400Изменено в версии 3.2: Добавлена поддержка `"%lld"` и `"%llu"`.401402Изменено в версии 3.3: Добавлена поддержка `"%li"`, `"%lli"` и `"%zi"`.403404Изменено в версии 3.4: Добавлена поддержка форматтеров ширины и точности для `"%s"`, `"%A"`, `"%U"`, `"%V"`, `"%S"`, `"%R"`.405406Изменено в версии 3.12: Добавлена поддержка спецификаторов преобразования `o` и `X`. Добавлена поддержка модификаторов длины `j` и `t`. Модификаторы длины теперь применяются ко всем целочисленным преобразованиям. Модификатор длины `l` теперь применяется к спецификаторам преобразования `s` и `V`. Добавлена поддержка переменной ширины и точности `*`. Добавлена поддержка флага `-`.407408Неопознанный символ формата теперь вызывает [`SystemError`](https://python-all.ru/3.16/library/exceptions.html#SystemError). В предыдущих версиях он приводил к тому, что оставшаяся часть строки формата копировалась в результирующую строку как есть, а все лишние аргументы отбрасывались.409410Изменено в версии 3.13: Добавлена поддержка форматов `%T`, `%#T`, `%N` и `%#N`.411412#### `PyObject *PyUnicode_FromFormatV(const char *format, va_list vargs)`413414*Возвращаемое значение: новая ссылка.*415416*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*417418Идентично [`PyUnicode_FromFormat()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_FromFormat), за исключением того, что принимает ровно два аргумента.419420#### `PyObject *PyUnicode_FromObject(PyObject *obj)`421422*Возвращаемое значение: новая ссылка.*423424*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*425426Копирует экземпляр подтипа Unicode в новый настоящий объект Unicode, если это необходимо. Если *obj* уже является настоящим объектом Unicode (не подтипом), возвращает новую [сильную ссылку](https://python-all.ru/3.16/glossary.html#term-strong-reference) на этот объект.427428Объекты, отличные от Unicode или его подтипов, вызывают [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError).429430#### `PyObject *PyUnicode_FromOrdinal(int ordinal)`431432*Возвращаемое значение: новая ссылка.*433434*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*435436Создаёт объект Unicode из заданной кодовой точки Unicode *ordinal*.437438Значение ordinal должно находиться в диапазоне `range(0x110000)`. В противном случае возбуждается [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError).439440#### `PyObject *PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)`441442*Возвращаемое значение: новая ссылка.*443444*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*445446Декодирует закодированный объект *obj* в объект Unicode.447448[`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) для подробностей).449450Все остальные объекты, включая объекты Unicode, приводят к установке [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError).451452API возвращает `NULL` в случае ошибки. Вызывающий отвечает за уменьшение счётчика ссылок (decref) возвращённых объектов.453454#### `void PyUnicode_Append(PyObject **p_left, PyObject *right)`455456*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*457458Добавляет строку *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)”) эту ссылку.459460В случае ошибки устанавливает *\*p\_left* в `NULL` и возбуждает исключение.461462В случае успеха устанавливает *\*p\_left* в новую сильную ссылку на результат.463464#### `void PyUnicode_AppendAndDel(PyObject **p_left, PyObject *right)`465466*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*467468Эта функция похожа на [`PyUnicode_Append()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_Append), с тем лишь отличием, что она уменьшает счётчик ссылок *right* на единицу.469470#### `PyObject *PyUnicode_BuildEncodingMap(PyObject *string)`471472*Возвращаемое значение: новая ссылка.*473474*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*475476Возвращает отображение, пригодное для декодирования пользовательской однобайтовой кодировки. Принимает строку Unicode *string* длиной до 256 символов, представляющую таблицу кодировки, и возвращает либо компактный внутренний объект отображения, либо словарь, отображающий коды символов в байтовые значения. Возбуждает [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError) и возвращает `NULL` при неверном входном значении.477478Добавлено в версии 3.2.479480#### `const char *PyUnicode_GetDefaultEncoding(void)`481482*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*483484Возвращает имя кодировки строк по умолчанию, `"utf-8"`. См. [`sys.getdefaultencoding()`](https://python-all.ru/3.16/library/sys.html#sys.getdefaultencoding).485486Возвращаемую строку не нужно освобождать, она действует до завершения интерпретатора.487488#### `Py_ssize_t PyUnicode_GetLength(PyObject *unicode)`489490*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*491492Возвращает длину объекта Unicode в кодовых точках.493494При ошибке устанавливает исключение и возвращает `-1`.495496Добавлено в версии 3.3.497498#### `Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t from_start, Py_ssize_t how_many)`499500Копирует символы из одного объекта Unicode в другой. При необходимости выполняет преобразование символов и, если возможно, использует `memcpy()`. Возвращает `-1` и устанавливает исключение при ошибке, в противном случае возвращает количество скопированных символов.501502Строка ещё не должна была быть «использована». Подробнее см. [`PyUnicode_New()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_New).503504Добавлено в версии 3.3.505506#### `int PyUnicode_Resize(PyObject **unicode, Py_ssize_t length);`507508*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*509510Изменяет размер объекта Unicode *\*unicode* до новой *длины* в кодовых точках.511512Пытается изменить размер строки на месте (обычно это быстрее, чем выделить новую строку и скопировать символы) или создаёт новую строку.513514*\*unicode* изменяется так, чтобы указывать на новый (изменённый) объект, и возвращается `0` при успехе. В противном случае возвращается `-1` и устанавливается исключение, а *\*unicode* остаётся нетронутым.515516Функция не проверяет содержимое строки, результат может не быть строкой в каноническом представлении.517518#### `Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)`519520Заполняет строку символом: записывает *fill\_char* в `unicode[start:start+length]`.521522Завершается ошибкой, если *fill\_char* больше максимального символа строки или если у строки больше одной ссылки.523524Строка ещё не должна была быть «использована». Подробнее см. [`PyUnicode_New()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_New).525526Возвращает количество записанных символов или `-1` и возбуждает исключение при ошибке.527528Добавлено в версии 3.3.529530#### `int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)`531532*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*533534Записывает *символ* в строку *unicode* по индексу *index*, начиная с нуля. Возвращает `0` при успехе, `-1` при ошибке с установленным исключением.535536Эта функция проверяет, что *unicode* является объектом Unicode, что индекс не выходит за границы и что счётчик ссылок объекта равен единице. См. [`PyUnicode_WRITE()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_WRITE) для версии, которая пропускает эти проверки, возлагая их на вас.537538Строка ещё не должна была быть «использована». Подробнее см. [`PyUnicode_New()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_New).539540Добавлено в версии 3.3.541542#### `Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)`543544*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*545546Читает символ из строки. Эта функция проверяет, что *unicode* является объектом Unicode и индекс не выходит за границы, в отличие от [`PyUnicode_READ_CHAR()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_READ_CHAR), которая не выполняет проверку ошибок.547548Возвращает символ при успехе, `-1` при ошибке с установленным исключением.549550Добавлено в версии 3.3.551552#### `PyObject *PyUnicode_Substring(PyObject *unicode, Py_ssize_t start, Py_ssize_t end)`553554*Возвращаемое значение: новая ссылка.*555556*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*557558Возвращает подстроку *unicode* от индекса символа *start* (включительно) до индекса *end* (исключительно). Отрицательные индексы не поддерживаются. При ошибке устанавливает исключение и возвращает `NULL`.559560Добавлено в версии 3.3.561562#### `Py_UCS4 *PyUnicode_AsUCS4(PyObject *unicode, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)`563564*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*565566Копирует строку *unicode* в буфер UCS4, включая нулевой символ, если *copy\_null* установлен. Возвращает `NULL` и устанавливает исключение при ошибке (в частности, [`SystemError`](https://python-all.ru/3.16/library/exceptions.html#SystemError), если *buflen* меньше длины *unicode*). При успехе возвращается *buffer*.567568Добавлено в версии 3.3.569570#### `Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)`571572*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*573574Копирует строку *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). Возвращаемый буфер всегда содержит дополнительный нулевой код в конце.575576Добавлено в версии 3.3.577578### Кодировка локали579580Текущую кодировку локали можно использовать для декодирования текста из операционной системы.581582#### `PyObject *PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t length, const char *errors)`583584*Возвращаемое значение: новая ссылка.*585586*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*587588Decode 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.589590Используйте [`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).591592Эта функция игнорирует [режим UTF-8 Python](https://python-all.ru/3.16/library/os.html#utf8-mode).593594> **См. также**595>596> Функция [`Py_DecodeLocale()`](https://python-all.ru/3.16/c-api/sys.html#c.Py_DecodeLocale).597598Добавлено в версии 3.3.599600Изменено в версии 3.7: Теперь функция также использует текущую кодировку локали для обработчика ошибок `surrogateescape`, за исключением Android. Ранее для `surrogateescape` использовался [`Py_DecodeLocale()`](https://python-all.ru/3.16/c-api/sys.html#c.Py_DecodeLocale), а для `strict` использовалась текущая кодировка локали.601602#### `PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors)`603604*Возвращаемое значение: новая ссылка.*605606*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*607608Аналогично [`PyUnicode_DecodeLocaleAndSize()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DecodeLocaleAndSize), но длина строки вычисляется с помощью `strlen()`.609610Добавлено в версии 3.3.611612#### `PyObject *PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)`613614*Возвращаемое значение: новая ссылка.*615616*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*617618Encode 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.619620Используйте [`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).621622Эта функция игнорирует [режим UTF-8 Python](https://python-all.ru/3.16/library/os.html#utf8-mode).623624> **См. также**625>626> Функция [`Py_EncodeLocale()`](https://python-all.ru/3.16/c-api/sys.html#c.Py_EncodeLocale).627628Добавлено в версии 3.3.629630Изменено в версии 3.7: Теперь функция также использует текущую кодировку локали для обработчика ошибок `surrogateescape`, за исключением Android. Ранее для `surrogateescape` использовался [`Py_EncodeLocale()`](https://python-all.ru/3.16/c-api/sys.html#c.Py_EncodeLocale), а для `strict` использовалась текущая кодировка локали.631632### Кодировка файловой системы633634Functions 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)).635636Для кодирования имен файлов в [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes) во время разбора аргументов следует использовать конвертер `"O&"`, передавая `PyUnicode_FSConverter()` в качестве функции преобразования:637638#### `int PyUnicode_FSConverter(PyObject *obj, void *result)`639640*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*641642[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.643644Если *obj* равно `NULL`, функция освобождает сильную ссылку, сохраненную в переменной, на которую указывает *result*, и возвращает `1`.645646Добавлено в версии 3.1.647648Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.16/glossary.html#term-path-like-object).649650Для декодирования имен файлов в [`str`](https://python-all.ru/3.16/library/stdtypes.html#str) во время разбора аргументов следует использовать конвертер `"O&"`, передавая `PyUnicode_FSDecoder()` в качестве функции преобразования:651652#### `int PyUnicode_FSDecoder(PyObject *obj, void *result)`653654*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*655656[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.657658Если *obj* равно `NULL`, освободите сильную ссылку на объект, на который указывает *result*, и верните `1`.659660Добавлено в версии 3.2.661662Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.16/glossary.html#term-path-like-object).663664#### `PyObject *PyUnicode_DecodeFSDefaultAndSize(const char *str, Py_ssize_t size)`665666*Возвращаемое значение: новая ссылка.*667668*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*669670Декодирует строку из [кодировки файловой системы и обработчика ошибок](https://python-all.ru/3.16/glossary.html#term-filesystem-encoding-and-error-handler).671672Если требуется декодировать строку из текущей кодировки локали, используйте [`PyUnicode_DecodeLocaleAndSize()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DecodeLocaleAndSize).673674> **См. также**675>676> Функция [`Py_DecodeLocale()`](https://python-all.ru/3.16/c-api/sys.html#c.Py_DecodeLocale).677678Изменено в версии 3.6: Теперь используется [обработчик ошибок файловой системы](https://python-all.ru/3.16/glossary.html#term-filesystem-encoding-and-error-handler).679680#### `PyObject *PyUnicode_DecodeFSDefault(const char *str)`681682*Возвращаемое значение: новая ссылка.*683684*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*685686Декодирует строку, завершающуюся нулевым символом, из [кодировки файловой системы и обработчика ошибок](https://python-all.ru/3.16/glossary.html#term-filesystem-encoding-and-error-handler).687688Если длина строки известна, используйте [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize).689690Изменено в версии 3.6: Теперь используется [обработчик ошибок файловой системы](https://python-all.ru/3.16/glossary.html#term-filesystem-encoding-and-error-handler).691692#### `PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)`693694*Возвращаемое значение: новая ссылка.*695696*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*697698Кодирует объект 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` может содержать нулевые байты.699700Если требуется закодировать строку в текущую кодировку локали, используйте [`PyUnicode_EncodeLocale()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_EncodeLocale).701702> **См. также**703>704> Функция [`Py_EncodeLocale()`](https://python-all.ru/3.16/c-api/sys.html#c.Py_EncodeLocale).705706Добавлено в версии 3.2.707708Изменено в версии 3.6: Теперь используется [обработчик ошибок файловой системы](https://python-all.ru/3.16/glossary.html#term-filesystem-encoding-and-error-handler).709710### Поддержка wchar\_t711712`wchar_t` поддержка на платформах, которые её поддерживают:713714#### `PyObject *PyUnicode_FromWideChar(const wchar_t *wstr, Py_ssize_t size)`715716*Возвращаемое значение: новая ссылка.*717718*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*719720Создаёт объект Unicode из буфера `wchar_t` *wstr* заданного *размера*. Передача `-1` в качестве *размера* указывает, что функция должна сама вычислить длину с помощью `wcslen()`. В случае ошибки возвращает `NULL`.721722#### `Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *wstr, Py_ssize_t size)`723724*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*725726Копирует содержимое объекта Unicode в буфер `wchar_t` *wstr*. Копируется не более *size* `wchar_t` символов (исключая возможно завершающий нулевой символ). Возвращает количество скопированных `wchar_t` символов или `-1` в случае ошибки.727728Если *wstr* равно `NULL`, вместо этого возвращает *размер*, который потребуется для хранения всего *unicode*, включая завершающий нуль.729730Обратите внимание, что результирующая строка wchar\_t\* может быть как завершена нулевым символом, так и нет. Вызывающий код должен гарантировать, что строка wchar\_t\* завершается нулевым символом, если это требуется приложением. Кроме того, строка wchar\_t\* может содержать нулевые символы, что приведёт к усечению строки при использовании с большинством функций C.731732#### `wchar_t *PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)`733734*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*735736Преобразует объект Unicode в широкую строку. Результирующая строка всегда завершается нулевым символом. Если *size* не равно `NULL`, записывает количество широких символов (исключая завершающий нулевой символ) в *\*size*. Обратите внимание, что результирующая строка `wchar_t` может содержать нулевые символы, что приведёт к усечению строки при использовании с большинством функций C. Если *size* равно `NULL` и строка wchar\_t\* содержит нулевые символы, возбуждается [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError).737738В случае успеха возвращает буфер, выделенный функцией [`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), если выделение памяти не удалось.739740Добавлено в версии 3.2.741742Изменено в версии 3.7: Возбуждает [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError), если *size* равно `NULL` и строка wchar\_t\* содержит нулевые символы.743744## Встроенные кодеки745746Python предоставляет набор встроенных кодеков, написанных на C для скорости. Все эти кодеки могут использоваться напрямую через следующие функции.747748Многие из следующих API принимают два аргумента: encoding и errors, и их семантика совпадает с семантикой соответствующих аргументов встроенного конструктора строк [`str()`](https://python-all.ru/3.16/library/stdtypes.html#str).749750Установка 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).751752Обработка ошибок задаётся параметром errors, который также может быть установлен в `NULL`, что означает использование обработки по умолчанию, определённой для кодека. По умолчанию для всех встроенных кодеков используется строгий режим (возбуждается [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError)).753754Все кодеки используют схожий интерфейс. Для простоты документированы только отличия от приведённого ниже общего описания.755756### Общие кодеки757758Предоставляется следующий макрос:759760#### `Py_UNICODE_REPLACEMENT_CHARACTER`761762Кодовая точка Unicode `U+FFFD` (замещающий символ).763764Этот символ Unicode используется в качестве замещающего при декодировании, если аргумент *errors* установлен в «replace».765766Это общие API кодеков:767768#### `PyObject *PyUnicode_Decode(const char *str, Py_ssize_t size, const char *encoding, const char *errors)`769770*Возвращаемое значение: новая ссылка.*771772*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*773774Создаёт объект Unicode путём декодирования *size* байт закодированной строки *str*. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры встроенной функции [`str()`](https://python-all.ru/3.16/library/stdtypes.html#str). Используемый кодек ищется с помощью реестра кодеков Python. Возвращает `NULL`, если кодек возбудил исключение.775776#### `PyObject *PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)`777778*Возвращаемое значение: новая ссылка.*779780*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*781782Кодирует объект Unicode и возвращает результат в виде объекта bytes. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода [`encode()`](https://python-all.ru/3.16/library/stdtypes.html#str.encode) объекта Unicode. Используемый кодек ищется с помощью реестра кодеков Python. Возвращает `NULL`, если кодек возбудил исключение.783784### Кодеки UTF-8785786Это API кодеков UTF-8:787788#### `PyObject *PyUnicode_DecodeUTF8(const char *str, Py_ssize_t size, const char *errors)`789790*Возвращаемое значение: новая ссылка.*791792*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*793794Создаёт объект Unicode, декодируя *size* байтов UTF-8-закодированной строки *str*. Возвращает `NULL`, если кодек вызвал исключение.795796#### `PyObject *PyUnicode_DecodeUTF8Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`797798*Возвращаемое значение: новая ссылка.*799800*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*801802Если *consumed* равно `NULL`, ведёт себя как [`PyUnicode_DecodeUTF8()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DecodeUTF8). Если *consumed* не равно `NULL`, неполные конечные последовательности байтов UTF-8 не будут считаться ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.803804#### `PyObject *PyUnicode_AsUTF8String(PyObject *unicode)`805806*Возвращаемое значение: новая ссылка.*807808*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*809810Кодирует объект Unicode в UTF-8 и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.811812Функция завершается ошибкой, если строка содержит суррогатные кодовые точки (`U+D800` - `U+DFFF`).813814#### `const char *PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)`815816*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.10.*817818Возвращает указатель на UTF-8-кодировку объекта Unicode и сохраняет размер закодированного представления (в байтах) в *size*. Аргумент *size* может быть `NULL`; в этом случае размер не сохраняется. Возвращаемый буфер всегда содержит дополнительный нулевой байт в конце (не включён в *size*), независимо от наличия других нулевых кодовых точек.819820При ошибке устанавливает исключение, устанавливает *size* в `-1` (если он не NULL) и возвращает `NULL`.821822Функция завершается ошибкой, если строка содержит суррогатные кодовые точки (`U+D800` - `U+DFFF`).823824Это кеширует UTF-8-представление строки в объекте Unicode, и последующие вызовы будут возвращать указатель на тот же буфер. Вызывающий не отвечает за освобождение буфера. Буфер освобождается, а указатели на него становятся недействительными, когда объект Unicode удаляется сборщиком мусора.825826Добавлено в версии 3.3.827828Изменено в версии 3.7: Тип возвращаемого значения теперь `const char *`, а не `char *`.829830Изменено в версии 3.10: Эта функция является частью [ограниченного API](https://python-all.ru/3.16/c-api/stable.html#limited-c-api).831832#### `const char *PyUnicode_AsUTF8(PyObject *unicode)`833834Как [`PyUnicode_AsUTF8AndSize()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_AsUTF8AndSize), но не сохраняет размер.835836> **Предупреждение**837>838> Эта функция не имеет специального поведения для [нулевых символов](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) вместо этого.839840Добавлено в версии 3.3.841842Изменено в версии 3.7: Тип возвращаемого значения теперь `const char *`, а не `char *`.843844### Кодеки UTF-32845846Это API кодеков UTF-32:847848#### `PyObject *PyUnicode_DecodeUTF32(const char *str, Py_ssize_t size, const char *errors, int *byteorder)`849850*Возвращаемое значение: новая ссылка.*851852*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*853854Декодирует *size* байтов из буферной строки, закодированной в UTF-32, и возвращает соответствующий объект Unicode. *errors* (если не `NULL`) определяет обработку ошибок. По умолчанию – «strict».855856Если *byteorder* не равно `NULL`, декодер начинает декодирование, используя заданный порядок байтов:857858```c859*byteorder == -1: little endian860*byteorder == 0:  native order861*byteorder == 1:  big endian862```863864Если `*byteorder` равен нулю и первые четыре байта входных данных являются маркером порядка байтов (BOM), декодер переключается на этот порядок байтов, и BOM не копируется в результирующую строку Unicode. Если `*byteorder` равно `-1` или `1`, любой маркер порядка байтов копируется в выходные данные.865866После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных.867868Если *byteorder* равно `NULL`, кодек запускается в режиме собственного порядка байтов.869870Возвращает `NULL`, если кодек вызвал исключение.871872#### `PyObject *PyUnicode_DecodeUTF32Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)`873874*Возвращаемое значение: новая ссылка.*875876*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*877878Если *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*.879880#### `PyObject *PyUnicode_AsUTF32String(PyObject *unicode)`881882*Возвращаемое значение: новая ссылка.*883884*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*885886Возвращает байтовую строку Python в кодировке UTF-32 в собственном порядке байтов. Строка всегда начинается с метки BOM. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.887888### Кодеки UTF-32889890Это API кодеков UTF-32:891892#### `PyObject *PyUnicode_DecodeUTF32(const char *str, Py_ssize_t size, const char *errors, int *byteorder)`893894*Возвращаемое значение: новая ссылка.*895896*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*897898Декодирует *size* байтов из строки буфера, закодированной в UTF-16, и возвращает соответствующий объект Unicode. *errors* (если не `NULL`) определяет обработку ошибок. По умолчанию используется «strict».899900Если *byteorder* не равно `NULL`, декодер начинает декодирование с указанным порядком байтов:901902```c903*byteorder == -1: little endian904*byteorder == 0:  native order905*byteorder == 1:  big endian906```907908Если `*byteorder` равен нулю и первые два байта входных данных являются меткой порядка байтов (BOM), декодер переключается на этот порядок байтов, а BOM не копируется в результирующую строку Unicode. Если `*byteorder` равен `-1` или `1`, любая метка порядка байтов копируется в выходные данные (что приведёт к символу `\ufeff` или `\ufffe`).909910После завершения `*byteorder` устанавливается в текущий порядок байтов в конце входных данных.911912Если *byteorder* равен `NULL`, кодек запускается в режиме собственного порядка байтов.913914Возвращает `NULL`, если кодек вызвал исключение.915916#### `PyObject *PyUnicode_DecodeUTF16Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)`917918*Возвращаемое значение: новая ссылка.*919920*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*921922Если *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*.923924#### `PyObject *PyUnicode_AsUTF16String(PyObject *unicode)`925926*Возвращаемое значение: новая ссылка.*927928*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*929930Возвращает байтовую строку Python в кодировке UTF-16 в собственном порядке байтов. Строка всегда начинается с метки BOM. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.931932### Кодеки UTF-7933934Это API кодеков UTF-7:935936#### `PyObject *PyUnicode_DecodeUTF7(const char *str, Py_ssize_t size, const char *errors)`937938*Возвращаемое значение: новая ссылка.*939940*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*941942Создаёт объект Unicode путём декодирования *size* байтов строки, закодированной в UTF-7, *str*. Возвращает `NULL`, если кодек вызвал исключение.943944#### `PyObject *PyUnicode_DecodeUTF7Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`945946*Возвращаемое значение: новая ссылка.*947948*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*949950Если *consumed* равен `NULL`, ведёт себя как [`PyUnicode_DecodeUTF7()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DecodeUTF7). Если *consumed* не равен `NULL`, хвостовые неполные секции base-64 UTF-7 не будут рассматриваться как ошибка. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.951952### Кодеки Unicode-Escape953954Это API кодеков «Unicode Escape»:955956#### `PyObject *PyUnicode_DecodeUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)`957958*Возвращаемое значение: новая ссылка.*959960*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*961962Создаёт объект Unicode путём декодирования *size* байтов строки, закодированной в Unicode-Escape, *str*. Возвращает `NULL`, если кодек вызвал исключение.963964#### `PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)`965966*Возвращаемое значение: новая ссылка.*967968*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*969970Кодирует объект Unicode с помощью Unicode-Escape и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.971972### Кодеки Raw-Unicode-Escape973974Это API кодеков «Raw Unicode Escape»:975976#### `PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)`977978*Возвращаемое значение: новая ссылка.*979980*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*981982Создаёт объект Unicode путём декодирования *size* байтов строки, закодированной в Raw-Unicode-Escape, *str*. Возвращает `NULL`, если кодек вызвал исключение.983984#### `PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)`985986*Возвращаемое значение: новая ссылка.*987988*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*989990Кодирует объект Unicode с помощью Raw-Unicode-Escape и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.991992### Кодеки Latin-1993994Это API кодеков Latin-1: Latin-1 соответствует первым 256 кодовым позициям Unicode, и только они принимаются кодеками при кодировании.995996#### `PyObject *PyUnicode_DecodeLatin1(const char *str, Py_ssize_t size, const char *errors)`997998*Возвращаемое значение: новая ссылка.*9991000*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*10011002Создаёт объект Unicode путём декодирования *size* байтов строки *str*, закодированной в Latin-1. Возвращает `NULL`, если кодек выбросил исключение.10031004#### `PyObject *PyUnicode_AsLatin1String(PyObject *unicode)`10051006*Возвращаемое значение: новая ссылка.*10071008*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*10091010Кодирует объект Unicode с помощью Latin-1 и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает `NULL`, если кодек выбросил исключение.10111012### Кодеки ASCII10131014Это API кодеков ASCII. Принимаются только 7-битные данные ASCII. Все остальные коды вызывают ошибки.10151016#### `PyObject *PyUnicode_DecodeASCII(const char *str, Py_ssize_t size, const char *errors)`10171018*Возвращаемое значение: новая ссылка.*10191020*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*10211022Создаёт объект Unicode путём декодирования *size* байтов строки *str*, закодированной в ASCII. Возвращает `NULL`, если кодек выбросил исключение.10231024#### `PyObject *PyUnicode_AsASCIIString(PyObject *unicode)`10251026*Возвращаемое значение: новая ссылка.*10271028*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*10291030Кодирует объект Unicode с помощью ASCII и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает `NULL`, если кодек выбросил исключение.10311032### Кодеки с таблицей символов10331034Этот кодек особенный тем, что его можно использовать для реализации множества различных кодеков (именно так и были получены большинство стандартных кодеков, входящих в пакет `encodings`). Кодек использует отображения для кодирования и декодирования символов. Предоставляемые объекты отображения должны поддерживать интерфейс отображения [`__getitem__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__getitem__); словари и последовательности прекрасно работают.10351036Это API кодеков отображения:10371038#### `PyObject *PyUnicode_DecodeCharmap(const char *str, Py_ssize_t length, PyObject *mapping, const char *errors)`10391040*Возвращаемое значение: новая ссылка.*10411042*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*10431044Создаёт объект Unicode путём декодирования *size* байтов закодированной строки *str* с использованием заданного объекта *mapping*. Возвращает `NULL`, если кодек выбросил исключение.10451046Если *mapping* равен `NULL`, будет применяться декодирование Latin-1. В противном случае *mapping* должен отображать порядковые номера байтов (целые числа в диапазоне от 0 до 255) в строки Unicode, целые числа (которые затем интерпретируются как кодовые позиции Unicode) или `None`. Неотображённые байты данных – те, которые вызывают [`LookupError`](https://python-all.ru/3.16/library/exceptions.html#LookupError), а также те, которые отображаются в `None`, `0xFFFE` или `'\ufffe'`, считаются неопределёнными отображениями и вызывают ошибку.10471048#### `PyObject *PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)`10491050*Возвращаемое значение: новая ссылка.*10511052*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*10531054Кодирует объект Unicode с использованием заданного объекта *mapping* и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает `NULL`, если кодек выбросил исключение.10551056Объект *mapping* должен отображать целые числа – кодовые позиции Unicode – в объекты bytes, целые числа в диапазоне от 0 до 255 или `None`. Неотображённые кодовые позиции символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.16/library/exceptions.html#LookupError)), а также отображённые в `None` считаются «неопределённым отображением» и вызывают ошибку.10571058Следующее API кодека особенное тем, что отображает Unicode в Unicode.10591060#### `PyObject *PyUnicode_Translate(PyObject *unicode, PyObject *table, const char *errors)`10611062*Возвращаемое значение: новая ссылка.*10631064*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*10651066Преобразует строку, применяя к ней таблицу отображения символов, и возвращает результирующий объект Unicode. Возвращает `NULL`, если кодек выбросил исключение.10671068Таблица отображения должна отображать целые числа – кодовые позиции Unicode – в целые числа – кодовые позиции Unicode – или в `None` (вызывает удаление символа).10691070Таблицы отображения должны лишь предоставлять интерфейс [`__getitem__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__getitem__); словари и последовательности работают хорошо. Неотображённые кодовые позиции символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.16/library/exceptions.html#LookupError)) остаются нетронутыми и копируются как есть.10711072*errors* имеет обычное для кодеков значение. Он может быть `NULL`, что означает использование обработки ошибок по умолчанию.10731074### Кодеки MBCS для Windows10751076Это API кодеков MBCS. В настоящее время они доступны только в Windows и используют преобразователи Win32 MBCS для выполнения преобразований. Обратите внимание, что MBCS (или DBCS) – это класс кодировок, а не одна конкретная. Целевая кодировка определяется пользовательскими настройками на машине, где выполняется кодек.10771078#### `PyObject *PyUnicode_DecodeMBCS(const char *str, Py_ssize_t size, const char *errors)`10791080*Возвращаемое значение: новая ссылка.*10811082*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) в Windows начиная с версии 3.7.*10831084Создаёт объект Unicode путём декодирования *size* байтов строки *str*, закодированной в MBCS. Возвращает `NULL`, если кодек выбросил исключение.10851086#### `PyObject *PyUnicode_DecodeMBCSStateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`10871088*Возвращаемое значение: новая ссылка.*10891090*Часть [стабильного ABI](https://python-all.ru/3.16/c-api/stable.html#stable) на Windows с версии 3.7.*10911092Если *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*.10931094#### `PyObject *PyUnicode_DecodeCodePageStateful(int code_page, const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`10951096*Возвращаемое значение: новая ссылка.*10971098*Часть [стабильного ABI](https://python-all.ru/3.16/c-api/stable.html#stable) на Windows с версии 3.7.*10991100Аналогично [`PyUnicode_DecodeMBCSStateful()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_DecodeMBCSStateful), но использует кодовую страницу, указанную в *code\_page*.11011102#### `PyObject *PyUnicode_AsMBCSString(PyObject *unicode)`11031104*Возвращаемое значение: новая ссылка.*11051106*Часть [стабильного ABI](https://python-all.ru/3.16/c-api/stable.html#stable) на Windows с версии 3.7.*11071108Кодирует объект Unicode с помощью MBCS и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.11091110#### `PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)`11111112*Возвращаемое значение: новая ссылка.*11131114*Часть [стабильного ABI](https://python-all.ru/3.16/c-api/stable.html#stable) на Windows с версии 3.7.*11151116Кодирует объект Unicode с помощью указанной кодовой страницы и возвращает объект bytes. Возвращает `NULL`, если кодек вызвал исключение. Используйте кодовую страницу `CP_ACP` для получения кодировщика MBCS.11171118Добавлено в версии 3.3.11191120## Методы и слот-функции11211122Следующие API могут обрабатывать объекты Unicode и строки на входе (в описаниях мы называем их строками) и возвращают объекты Unicode или целые числа по необходимости.11231124Все они возвращают `NULL` или `-1` в случае возникновения исключения.11251126#### `PyObject *PyUnicode_Concat(PyObject *left, PyObject *right)`11271128*Возвращаемое значение: новая ссылка.*11291130*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*11311132Объединяет две строки, возвращая новую строку Unicode.11331134#### `PyObject *PyUnicode_Split(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)`11351136*Возвращаемое значение: новая ссылка.*11371138*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*11391140Разделяет строку, возвращая список строк Unicode. Если *sep* равно `NULL`, разделение происходит по всем пробельным подстрокам. В противном случае разделение происходит по указанному разделителю. Будет выполнено не более *maxsplit* разбиений. Если значение отрицательное, ограничение не задано. Разделители не включаются в результирующий список.11411142При ошибке возвращает `NULL` с установленным исключением.11431144Эквивалентно [`str.split()`](https://python-all.ru/3.16/library/stdtypes.html#str.split).11451146#### `PyObject *PyUnicode_RSplit(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)`11471148*Возвращаемое значение: новая ссылка.*11491150*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*11511152Аналогично [`PyUnicode_Split()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_Split), но разделение начинается с конца строки.11531154При ошибке возвращает `NULL` с установленным исключением.11551156Эквивалентно [`str.rsplit()`](https://python-all.ru/3.16/library/stdtypes.html#str.rsplit).11571158#### `PyObject *PyUnicode_Splitlines(PyObject *unicode, int keepends)`11591160*Возвращаемое значение: новая ссылка.*11611162*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*11631164Разделяет строку Unicode по символам конца строки, возвращая список строк Unicode. CRLF считается одним разрывом строки. Если *keepends* равно `0`, символы конца строки не включаются в результирующие строки.11651166#### `PyObject *PyUnicode_Partition(PyObject *unicode, PyObject *sep)`11671168*Возвращаемое значение: новая ссылка.*11691170*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*11711172Разделяет строку Unicode по первому вхождению *sep* и возвращает кортеж из трёх элементов: часть до разделителя, сам разделитель и часть после разделителя. Если разделитель не найден, возвращает кортеж из трёх элементов: саму строку, а затем две пустые строки.11731174*sep* не должен быть пустым.11751176При ошибке возвращает `NULL` с установленным исключением.11771178Эквивалентно [`str.partition()`](https://python-all.ru/3.16/library/stdtypes.html#str.partition).11791180#### `PyObject *PyUnicode_RPartition(PyObject *unicode, PyObject *sep)`11811182*Возвращаемое значение: новая ссылка.*11831184*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*11851186Аналогично [`PyUnicode_Partition()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_Partition), но разделяет строку Unicode по последнему вхождению *sep*. Если разделитель не найден, возвращает кортеж из трёх элементов: две пустые строки, а затем сама строка.11871188*sep* не должен быть пустым.11891190При ошибке возвращает `NULL` с установленным исключением.11911192Эквивалентно [`str.rpartition()`](https://python-all.ru/3.16/library/stdtypes.html#str.rpartition).11931194#### `PyObject *PyUnicode_Join(PyObject *separator, PyObject *seq)`11951196*Возвращаемое значение: новая ссылка.*11971198*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*11991200Объединяет последовательность строк, используя заданный *разделитель*, и возвращает полученную Unicode-строку.12011202#### `Py_ssize_t PyUnicode_Tailmatch(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)`12031204*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*12051206Возвращает `1`, если *substr* совпадает с `unicode[start:end]` на заданном хвосте (*direction* == `-1` означает проверку на совпадение с началом, *direction* == `1` – с концом), иначе `0`. Возвращает `-1`, если произошла ошибка.12071208#### `Py_ssize_t PyUnicode_Find(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)`12091210*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*12111212Возвращает первую позицию *substr* в `unicode[start:end]`, используя заданное *direction* (*direction* == `1` означает прямой поиск, *direction* == `-1` – обратный). Возвращаемое значение – индекс первого совпадения; значение `-1` означает, что совпадений не найдено, а `-2` – что произошла ошибка и было установлено исключение.12131214#### `Py_ssize_t PyUnicode_FindChar(PyObject *unicode, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)`12151216*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*12171218Возвращает первую позицию символа *ch* в `unicode[start:end]`, используя заданное *direction* (*direction* == `1` означает прямой поиск, *direction* == `-1` – обратный). Возвращаемое значение – индекс первого совпадения; значение `-1` означает, что совпадений не найдено, а `-2` – что произошла ошибка и было установлено исключение.12191220Добавлено в версии 3.3.12211222Изменено в версии 3.7: *start* и *end* теперь скорректированы, чтобы вести себя как `unicode[start:end]`.12231224#### `Py_ssize_t PyUnicode_Count(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end)`12251226*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*12271228Возвращает количество неперекрывающихся вхождений *substr* в `unicode[start:end]`. Возвращает `-1`, если произошла ошибка.12291230#### `PyObject *PyUnicode_Replace(PyObject *unicode, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)`12311232*Возвращаемое значение: новая ссылка.*12331234*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*12351236Заменяет не более *maxcount* вхождений *substr* в *unicode* на *replstr* и возвращает полученный Unicode-объект. *maxcount* == `-1` означает заменить все вхождения.12371238#### `int PyUnicode_Compare(PyObject *left, PyObject *right)`12391240*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*12411242Сравнивает две строки и возвращает `-1`, `0`, `1` для случаев меньше, равно и больше соответственно.12431244Эта функция возвращает `-1` при ошибке, поэтому для проверки на ошибки следует вызывать [`PyErr_Occurred()`](https://python-all.ru/3.16/c-api/exceptions.html#c.PyErr_Occurred).12451246> **См. также**1247>1248> Функция [`PyUnicode_Equal()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_Equal).12491250#### `int PyUnicode_Equal(PyObject *a, PyObject *b)`12511252*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.14.*12531254Проверяет, равны ли две строки:12551256- Возвращает `1`, если *a* равно *b*.1257- Возвращает `0`, если *a* не равно *b*.1258- Устанавливает исключение [`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).12591260Функция всегда выполняется успешно, если *a* и *b* являются объектами [`str`](https://python-all.ru/3.16/library/stdtypes.html#str).12611262Функция работает для подклассов [`str`](https://python-all.ru/3.16/library/stdtypes.html#str), но не учитывает пользовательский метод `__eq__()`.12631264> **См. также**1265>1266> Функция [`PyUnicode_Compare()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_Compare).12671268Добавлено в версии 3.14.12691270#### `int PyUnicode_EqualToUTF8AndSize(PyObject *unicode, const char *string, Py_ssize_t size)`12711272*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable), начиная с версии 3.13.*12731274Сравнивает Unicode-объект с буфером символов, который интерпретируется как закодированный в UTF-8 или ASCII, и возвращает true (`1`), если они равны, или false (`0`) в противном случае. Если Unicode-объект содержит суррогатные кодовые точки (`U+D800` - `U+DFFF`) или C-строка не является корректным UTF-8, возвращается false (`0`).12751276Эта функция не вызывает исключений.12771278Добавлено в версии 3.13.12791280#### `int PyUnicode_EqualToUTF8(PyObject *unicode, const char *string)`12811282*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable), начиная с версии 3.13.*12831284Аналогично [`PyUnicode_EqualToUTF8AndSize()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_EqualToUTF8AndSize), но длину *string* вычисляет с помощью `strlen()`. Если Unicode-объект содержит нулевые символы, возвращается false (`0`).12851286Добавлено в версии 3.13.12871288#### `int PyUnicode_CompareWithASCIIString(PyObject *unicode, const char *string)`12891290*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*12911292Сравнивает Unicode-объект *unicode* со строкой *string* и возвращает `-1`, `0`, `1` для случаев меньше, равно и больше соответственно. Рекомендуется передавать только ASCII-строки, но функция интерпретирует входную строку как ISO-8859-1, если она содержит не-ASCII символы.12931294Эта функция не вызывает исключений.12951296#### `PyObject *PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)`12971298*Возвращаемое значение: новая ссылка.*12991300*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*13011302Сравнивает две строки Unicode и возвращает одно из следующих значений:13031304- `NULL` в случае, если возникло исключение1305- [`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) для успешных сравнений1306- [`Py_NotImplemented`](https://python-all.ru/3.16/c-api/object.html#c.Py_NotImplemented) в случае, если комбинация типов неизвестна13071308Возможные значения для *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).13091310#### `PyObject *PyUnicode_Format(PyObject *format, PyObject *args)`13111312*Возвращаемое значение: новая ссылка.*13131314*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*13151316Возвращает новый строковый объект из *format* и *args*; это аналог `format % args`.13171318#### `int PyUnicode_Contains(PyObject *unicode, PyObject *substr)`13191320*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*13211322Проверяет, содержится ли *substr* в *unicode*, и возвращает true или false соответственно.13231324*substr* должен приводиться к строке Unicode из одного элемента. `-1` возвращается в случае ошибки.13251326#### `void PyUnicode_InternInPlace(PyObject **p_unicode)`13271328*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*13291330Интернирует аргумент \*[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 без изменений и интернирует её.13311332(Пояснение: хотя здесь много говорится о ссылках, считайте эту функцию нейтральной по отношению к ссылкам. Вы должны владеть объектом, который передаёте; после вызова вы больше не владеете переданной ссылкой, но приобретаете новую ссылку на результат.)13331334Эта функция никогда не вызывает исключение. При ошибке она оставляет свой аргумент без изменений, не интернируя его.13351336Экземпляры подклассов [`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)) должно быть истинно. Если это не так, то – как и при любой другой ошибке – аргумент остаётся без изменений.13371338Обратите внимание, что интернированные строки не являются «бессмертными». Вы должны сохранять ссылку на результат, чтобы получить выгоду от интернирования.13391340#### `PyObject *PyUnicode_InternFromString(const char *str)`13411342*Возвращаемое значение: новая ссылка.*13431344*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*13451346Комбинация [`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), предназначенная для статически выделенных строк.13471348Возвращает новую («владение») ссылку либо на новый интернированный объект строки Unicode, либо на ранее интернированный строковый объект с тем же значением.13491350Python может сохранять ссылку на результат или сделать его [бессмертным](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) напрямую.13511352#### `unsigned int PyUnicode_CHECK_INTERNED(PyObject *str)`13531354Возвращает ненулевое значение, если *str* интернирована, и ноль в противном случае. Аргумент *str* должен быть строкой; это не проверяется. Эта функция всегда завершается успешно.13551356**Особенности реализации CPython:** Ненулевое возвращаемое значение может содержать дополнительную информацию о *том, как* строка интернирована. Значение таких ненулевых результатов, а также детали интернирования каждой конкретной строки могут меняться между версиями CPython.13571358## PyUnicodeWriter13591360API [`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).13611362Добавлено в версии 3.14.13631364#### `type PyUnicodeWriter`13651366Экземпляр средства записи Unicode.13671368Экземпляр должен быть уничтожен с помощью [`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) в случае ошибки.13691370#### `PyUnicodeWriter *PyUnicodeWriter_Create(Py_ssize_t length)`13711372Создаёт экземпляр средства записи Unicode.13731374*length* должен быть больше или равен `0`.13751376Если *length* больше `0`, предварительно выделяет внутренний буфер размером *length* символов.13771378Устанавливает исключение и возвращает `NULL` в случае ошибки.13791380#### `PyObject *PyUnicodeWriter_Finish(PyUnicodeWriter *writer)`13811382Возвращает итоговый объект [`str`](https://python-all.ru/3.16/library/stdtypes.html#str) и уничтожает экземпляр объекта записи.13831384Устанавливает исключение и возвращает `NULL` в случае ошибки.13851386После этого вызова экземпляр объекта записи становится недействительным.13871388#### `void PyUnicodeWriter_Discard(PyUnicodeWriter *writer)`13891390Отбрасывает внутренний буфер Unicode и уничтожает экземпляр объекта записи.13911392Если *writer* равен `NULL`, операция не выполняется.13931394После этого вызова экземпляр объекта записи становится недействительным.13951396#### `int PyUnicodeWriter_WriteChar(PyUnicodeWriter *writer, Py_UCS4 ch)`13971398Записывает один символ Unicode *ch* в *объект записи*.13991400При успехе возвращает `0`. При ошибке устанавливает исключение, оставляет объект записи без изменений и возвращает `-1`.14011402#### `int PyUnicodeWriter_WriteUTF8(PyUnicodeWriter *writer, const char *str, Py_ssize_t size)`14031404Декодирует строку *str* из UTF-8 в строгом режиме и записывает результат в *объект записи*.14051406*size* – длина строки в байтах. Если *size* равно `-1`, вызывается `strlen(str)` для получения длины строки.14071408При успехе возвращает `0`. При ошибке устанавливает исключение, оставляет объект записи без изменений и возвращает `-1`.14091410См. также [`PyUnicodeWriter_DecodeUTF8Stateful()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicodeWriter_DecodeUTF8Stateful).14111412#### `int PyUnicodeWriter_WriteASCII(PyUnicodeWriter *writer, const char *str, Py_ssize_t size)`14131414Записывает строку ASCII *str* в *объект записи*.14151416*size* – длина строки в байтах. Если *size* равно `-1`, вызывается `strlen(str)` для получения длины строки.14171418*str* должен содержать только символы ASCII. Поведение не определено, если *str* содержит не-ASCII символы.14191420При успехе возвращает `0`. При ошибке устанавливает исключение, оставляет объект записи без изменений и возвращает `-1`.14211422#### `int PyUnicodeWriter_WriteWideChar(PyUnicodeWriter *writer, const wchar_t *str, Py_ssize_t size)`14231424Записывает широкую строку *str* в *объект записи*.14251426*size* – количество широких символов. Если *size* равно `-1`, вызывается `wcslen(str)` для получения длины строки.14271428При успехе возвращает `0`. При ошибке устанавливает исключение, оставляет объект записи без изменений и возвращает `-1`.14291430#### `int PyUnicodeWriter_WriteUCS4(PyUnicodeWriter *writer, const Py_UCS4 *str, Py_ssize_t size)`14311432Записывает строку UCS4 *str* в *объект записи*.14331434*size* – количество символов UCS4.14351436При успехе возвращает `0`. При ошибке устанавливает исключение, оставляет объект записи без изменений и возвращает `-1`.14371438#### `int PyUnicodeWriter_WriteStr(PyUnicodeWriter *writer, PyObject *obj)`14391440Вызывает [`PyObject_Str()`](https://python-all.ru/3.16/c-api/object.html#c.PyObject_Str) для *obj* и записывает результат в *объект записи*.14411442При успехе возвращает `0`. При ошибке устанавливает исключение, оставляет объект записи без изменений и возвращает `-1`.14431444Чтобы записать подкласс [`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) для получения исходной строки.14451446#### `int PyUnicodeWriter_WriteRepr(PyUnicodeWriter *writer, PyObject *obj)`14471448Вызывает [`PyObject_Repr()`](https://python-all.ru/3.16/c-api/object.html#c.PyObject_Repr) для *obj* и записывает результат в *объект записи*.14491450Если *obj* равно `NULL`, записывает строку `"<NULL>"` в *объект записи*.14511452В случае успеха возвращает `0`. В случае ошибки устанавливает исключение, оставляет writer без изменений и возвращает `-1`.14531454Изменено в версии 3.14.4: Добавлена поддержка `NULL`.14551456#### `int PyUnicodeWriter_WriteSubstring(PyUnicodeWriter *writer, PyObject *str, Py_ssize_t start, Py_ssize_t end)`14571458Записывает подстроку `str[start:end]` в *writer*.14591460*str* должен быть объектом [`str`](https://python-all.ru/3.16/library/stdtypes.html#str) Python. *start* должен быть больше или равен 0 и меньше или равен *end*. *end* должен быть меньше или равен длине *str*.14611462В случае успеха возвращает `0`. В случае ошибки устанавливает исключение, оставляет writer без изменений и возвращает `-1`.14631464#### `int PyUnicodeWriter_Format(PyUnicodeWriter *writer, const char *format, ...)`14651466Аналогично [`PyUnicode_FromFormat()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_FromFormat), но записывает вывод напрямую в *writer*.14671468В случае успеха возвращает `0`. В случае ошибки устанавливает исключение, оставляет writer без изменений и возвращает `-1`.14691470#### `int PyUnicodeWriter_DecodeUTF8Stateful(PyUnicodeWriter *writer, const char *string, Py_ssize_t length, const char *errors, Py_ssize_t *consumed)`14711472Декодирует строку *str* из UTF-8 с обработчиком ошибок *errors* и записывает вывод в *writer*.14731474*size* – длина строки в байтах. Если *size* равно `-1`, вызывается `strlen(str)` для получения длины строки.14751476*errors* – это имя [обработчика ошибок](https://python-all.ru/3.16/library/codecs.html#error-handlers), например `"replace"`. Если *errors* равно `NULL`, используется строгий обработчик ошибок.14771478Если *consumed* не равно `NULL`, *\*consumed* устанавливается в количество декодированных байтов в случае успеха. Если *consumed* равно `NULL`, завершающие неполные последовательности байтов UTF-8 рассматриваются как ошибка.14791480В случае успеха возвращает `0`. В случае ошибки устанавливает исключение, оставляет writer без изменений и возвращает `-1`.14811482См. также [`PyUnicodeWriter_WriteUTF8()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicodeWriter_WriteUTF8).14831484## Устаревший API14851486Следующий API устарел.14871488#### `type Py_UNICODE`14891490Это typedef для `wchar_t`, который является 16-битным или 32-битным типом в зависимости от платформы. Вместо этого используйте напрямую `wchar_t`.14911492Изменено в версии 3.3: В предыдущих версиях это был 16-битный или 32-битный тип в зависимости от того, была ли выбрана «узкая» или «широкая» версия Unicode Python при сборке.14931494Устарело с версии 3.13, удалено в версии 3.16.14951496#### `int PyUnicode_READY(PyObject *unicode)`14971498Ничего не делает и возвращает `0`. Этот API сохранён только для обратной совместимости, но нет планов его удалять.14991500Добавлено в версии 3.3.15011502Устарело с версии 3.10: Этот API ничего не делает с Python 3.12. Ранее его нужно было вызывать для каждой строки, созданной с помощью старого API (`PyUnicode_FromUnicode()` или аналогичного).15031504#### `unsigned int PyUnicode_IS_READY(PyObject *unicode)`15051506Ничего не делает и возвращает `1`. Этот API сохранён только для обратной совместимости, но нет планов его удалять.15071508Добавлено в версии 3.3.15091510Устарело с версии 3.14: Этот API ничего не делает с Python 3.12. Ранее его можно было вызывать для проверки, необходимо ли [`PyUnicode_READY()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_READY).1511