unicode.md

1> **Источник:** https://python-all.ru/3.10/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.10/c-api/unicode.html) в Python 3.3, объекты Unicode внутри используют различные представления, чтобы обеспечить обработку полного диапазона символов Unicode, оставаясь при этом эффективными по памяти. Существуют особые случаи для строк, где все кодовые точки находятся ниже 128, 256 или 65536; в противном случае кодовые точки должны быть ниже 1114112 (то есть полного диапазона Unicode).1213Представления `Py_UNICODE*` и UTF-8 создаются по требованию и кэшируются в объекте Unicode. Представление `Py_UNICODE*` устарело и неэффективно.1415Из-за перехода между старыми и новыми API объекты Unicode могут внутренне находиться в двух состояниях в зависимости от того, как они были созданы:1617- «канонические» объекты Unicode – это все объекты, созданные не устаревшим Unicode API. Они используют наиболее эффективное представление, допускаемое реализацией.18- «Унаследованные» объекты Unicode создаются через один из устаревших API (обычно [`PyUnicode_FromUnicode()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_FromUnicode)) и содержат только представление `Py_UNICODE*`; перед вызовом любого другого API необходимо вызвать [`PyUnicode_READY()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_READY).1920> **Примечание**21>22> «Унаследованный» объект Unicode будет удалён в Python 3.12 вместе с устаревшими API. Все объекты Unicode станут «каноническими» с этого момента. Подробнее см. [**PEP 623**](https://python-all.ru/3.10/c-api/unicode.html).2324### Тип Unicode2526Это основные типы объектов Unicode, используемые в реализации Unicode в Python:2728#### `type Py_UCS4`2930#### `type Py_UCS2`3132#### `type Py_UCS1`3334*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*3536Эти типы являются псевдонимами для беззнаковых целочисленных типов, достаточно широких для хранения символов размером 32, 16 и 8 бит соответственно. При работе с отдельными символами Unicode используйте [`Py_UCS4`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UCS4).3738Новое в версии 3.3.3940#### `type Py_UNICODE`4142Это typedef для `wchar_t`, 16-битный или 32-битный тип в зависимости от платформы.4344Изменено в версии 3.3: В предыдущих версиях это был 16-битный или 32-битный тип в зависимости от того, была ли выбрана «узкая» или «широкая» версия Unicode Python при сборке.4546#### `type PyASCIIObject`4748#### `type PyCompactUnicodeObject`4950#### `type PyUnicodeObject`5152Эти подтипы [`PyObject`](https://python-all.ru/3.10/c-api/structures.html#c.PyObject) представляют объект Unicode в Python. В почти всех случаях их не следует использовать напрямую, так как все функции API, работающие с объектами Unicode, принимают и возвращают указатели [`PyObject`](https://python-all.ru/3.10/c-api/structures.html#c.PyObject).5354Новое в версии 3.3.5556#### `PyTypeObject PyUnicode_Type`5758*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*5960Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.10/c-api/type.html#c.PyTypeObject) представляет тип Unicode в Python. Он доступен коду Python как `str`.6162Следующие API на самом деле являются макросами C и могут использоваться для быстрых проверок и доступа к внутренним данным Unicode объектов только для чтения:6364#### `int PyUnicode_Check(PyObject *o)`6566Возвращает true, если объект *o* является объектом Unicode или экземпляром подтипа Unicode. Эта функция всегда выполняется успешно.6768#### `int PyUnicode_CheckExact(PyObject *o)`6970Возвращает true, если объект *o* является объектом Unicode, но не экземпляром подтипа. Эта функция всегда выполняется успешно.7172#### `int PyUnicode_READY(PyObject *o)`7374Убедитесь, что строковый объект *o* находится в «каноническом» представлении. Это необходимо перед использованием любых макросов доступа, описанных ниже.7576Возвращает `0` при успехе и `-1` с установленным исключением при неудаче, что в частности происходит при неудаче выделения памяти.7778Новое в версии 3.3.7980Устарело с версии 3.10, будет удалено в версии 3.12: Этот API будет удалён вместе с [`PyUnicode_FromUnicode()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_FromUnicode).8182#### `Py_ssize_t PyUnicode_GET_LENGTH(PyObject *o)`8384Возвращает длину строки Unicode в кодовых точках. *o* должен быть объектом Unicode в «каноническом» представлении (не проверяется).8586Новое в версии 3.3.8788#### `Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *o)`8990#### `Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *o)`9192#### `Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *o)`9394Возвращает указатель на каноническое представление, приведённое к целочисленным типам UCS1, UCS2 или UCS4 для прямого доступа к символам. Не выполняется проверок, имеет ли каноническое представление правильный размер символа; используйте [`PyUnicode_KIND()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_KIND) для выбора правильного макроса. Убедитесь, что [`PyUnicode_READY()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_READY) был вызван перед доступом к этому.9596Новое в версии 3.3.9798#### `PyUnicode_WCHAR_KIND`99100#### `PyUnicode_1BYTE_KIND`101102#### `PyUnicode_2BYTE_KIND`103104#### `PyUnicode_4BYTE_KIND`105106Возвращает значения макроса [`PyUnicode_KIND()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_KIND).107108Новое в версии 3.3.109110Устарело с версии 3.10, будет удалено в версии 3.12: `PyUnicode_WCHAR_KIND` устарел.111112#### `unsigned int PyUnicode_KIND(PyObject *o)`113114Возвращает одну из констант PyUnicode kind (см. выше), которые показывают, сколько байт на символ использует этот объект Unicode для хранения данных. *o* должен быть объектом Unicode в «каноническом» представлении (не проверяется).115116Новое в версии 3.3.117118#### `void *PyUnicode_DATA(PyObject *o)`119120Возвращает указатель void на необработанный буфер Unicode. *o* должен быть объектом Unicode в «каноническом» представлении (не проверяется).121122Новое в версии 3.3.123124#### `void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)`125126Записывает в каноническое представление *data* (полученное с помощью [`PyUnicode_DATA()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_DATA)). Этот макрос не выполняет никаких проверок корректности и предназначен для использования в циклах. Вызывающий код должен кэшировать значение *kind* и указатель *data*, полученные из других вызовов макросов. *index* – это индекс в строке (начиная с 0), а *value* – новое значение кодовой точки, которое должно быть записано в эту позицию.127128Новое в версии 3.3.129130#### `Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)`131132Читает кодовую точку из канонического представления *data* (полученного с помощью [`PyUnicode_DATA()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_DATA)). Никаких проверок или вызовов готовности не выполняется.133134Новое в версии 3.3.135136#### `Py_UCS4 PyUnicode_READ_CHAR(PyObject *o, Py_ssize_t index)`137138Читает символ из объекта Unicode *o*, который должен находиться в «каноническом» представлении. Это менее эффективно, чем [`PyUnicode_READ()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_READ) при многократных последовательных чтениях.139140Новое в версии 3.3.141142#### `PyUnicode_MAX_CHAR_VALUE(o)`143144Возвращает максимальную кодовую точку, подходящую для создания другой строки на основе *o*, который должен быть в «каноническом» представлении. Это всегда приблизительное значение, но более эффективно, чем итерация по строке.145146Новое в версии 3.3.147148#### `Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)`149150Возвращает размер устаревшего представления [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE) в кодовых единицах (суррогатные пары считаются за 2 единицы). *o* должен быть объектом Unicode (не проверяется).151152Устарело с версии 3.3, будет удалено в версии 3.12: Часть старого API Unicode, переходите на использование [`PyUnicode_GET_LENGTH()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_GET_LENGTH).153154#### `Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)`155156Возвращает размер устаревшего представления [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE) в байтах. *o* должен быть объектом Unicode (не проверяется).157158Устарело с версии 3.3, будет удалено в версии 3.12: Часть старого API Unicode, переходите на использование [`PyUnicode_GET_LENGTH()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_GET_LENGTH).159160#### `Py_UNICODE *PyUnicode_AS_UNICODE(PyObject *o)`161162#### `const char *PyUnicode_AS_DATA(PyObject *o)`163164Возвращает указатель на представление [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE) объекта. Возвращаемый буфер всегда завершается дополнительной нулевой кодовой точкой. Он также может содержать встроенные нулевые кодовые точки, что приведет к усечению строки при использовании в большинстве функций C. Форма `AS_DATA` приводит указатель к `const char*`. Аргумент *o* должен быть объектом Unicode (не проверяется).165166Изменено в версии 3.3: Этот макрос теперь неэффективен, так как во многих случаях представление [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE) не существует и его необходимо создавать, а также может завершиться ошибкой (возвращать `NULL` с установленным исключением). Попробуйте переписать код с использованием новых макросов `PyUnicode_nBYTE_DATA()` или используйте [`PyUnicode_WRITE()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_WRITE) или [`PyUnicode_READ()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_READ).167168Устарело с версии 3.3, будет удалено в версии 3.12: Часть старого API Unicode, переходите на использование семейства макросов `PyUnicode_nBYTE_DATA()`.169170#### `int PyUnicode_IsIdentifier(PyObject *o)`171172*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*173174Возвращает `1`, если строка является допустимым идентификатором в соответствии с определением языка, раздел [Идентификаторы и ключевые слова](https://python-all.ru/3.10/reference/lexical_analysis.html#identifiers). В противном случае возвращает `0`.175176Изменено в версии 3.9: Функция больше не вызывает [`Py_FatalError()`](https://python-all.ru/3.10/c-api/sys.html#c.Py_FatalError), если строка не готова.177178### Свойства символов Unicode179180Unicode предоставляет множество различных свойств символов. Наиболее востребованные из них доступны через следующие макросы, которые сопоставляются с функциями на C в зависимости от конфигурации Python.181182#### `int Py_UNICODE_ISSPACE(Py_UCS4 ch)`183184Возвращает `1` или `0` в зависимости от того, является ли *ch* пробельным символом.185186#### `int Py_UNICODE_ISLOWER(Py_UCS4 ch)`187188Возвращает `1` или `0` в зависимости от того, является ли *ch* символом в нижнем регистре.189190#### `int Py_UNICODE_ISUPPER(Py_UCS4 ch)`191192Возвращает `1` или `0` в зависимости от того, является ли *ch* символом в верхнем регистре.193194#### `int Py_UNICODE_ISTITLE(Py_UCS4 ch)`195196Возвращает `1` или `0` в зависимости от того, является ли *ch* символом в регистре заголовка (titlecase).197198#### `int Py_UNICODE_ISLINEBREAK(Py_UCS4 ch)`199200Возвращает `1` или `0` в зависимости от того, является ли *ch* символом разрыва строки.201202#### `int Py_UNICODE_ISDECIMAL(Py_UCS4 ch)`203204Возвращает `1` или `0` в зависимости от того, является ли *ch* десятичным символом.205206#### `int Py_UNICODE_ISDIGIT(Py_UCS4 ch)`207208Возвращает `1` или `0` в зависимости от того, является ли *ch* цифровым символом.209210#### `int Py_UNICODE_ISNUMERIC(Py_UCS4 ch)`211212Возвращает `1` или `0` в зависимости от того, является ли *ch* числовым символом.213214#### `int Py_UNICODE_ISALPHA(Py_UCS4 ch)`215216Возвращает `1` или `0` в зависимости от того, является ли *ch* буквенным символом.217218#### `int Py_UNICODE_ISALNUM(Py_UCS4 ch)`219220Возвращает `1` или `0` в зависимости от того, является ли *ch* буквенно-цифровым символом.221222#### `int Py_UNICODE_ISPRINTABLE(Py_UCS4 ch)`223224Возвращает `1` или `0` в зависимости от того, является ли *ch* печатным символом. Непечатные символы – это те, которые определены в базе данных Unicode как «Other» или «Separator», за исключением пробела ASCII (0x20), который считается печатным. (Обратите внимание, что печатные символы в этом контексте – это те, которые не должны экранироваться при вызове [`repr()`](https://python-all.ru/3.10/library/functions.html#repr) для строки. Это не влияет на обработку строк, записываемых в [`sys.stdout`](https://python-all.ru/3.10/library/sys.html#sys.stdout) или [`sys.stderr`](https://python-all.ru/3.10/library/sys.html#sys.stderr).)225226Эти API можно использовать для быстрых прямых преобразований символов:227228#### `Py_UCS4 Py_UNICODE_TOLOWER(Py_UCS4 ch)`229230Возвращает символ *ch*, преобразованный в нижний регистр.231232Устарело с версии 3.3: Эта функция использует простые отображения регистра.233234#### `Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4 ch)`235236Возвращает символ *ch*, преобразованный в верхний регистр.237238Устарело с версии 3.3: Эта функция использует простые отображения регистра.239240#### `Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4 ch)`241242Возвращает символ *ch*, приведённый к регистру заголовка.243244Устарело с версии 3.3: Эта функция использует простые отображения регистра.245246#### `int Py_UNICODE_TODECIMAL(Py_UCS4 ch)`247248Возвращает символ *ch*, преобразованный в десятичное положительное целое. Возвращает `-1`, если это невозможно. Этот макрос не вызывает исключений.249250#### `int Py_UNICODE_TODIGIT(Py_UCS4 ch)`251252Возвращает символ *ch*, преобразованный в целое однозначное число. Возвращает `-1`, если это невозможно. Этот макрос не вызывает исключений.253254#### `double Py_UNICODE_TONUMERIC(Py_UCS4 ch)`255256Возвращает символ *ch*, преобразованный в double. Возвращает `-1.0`, если это невозможно. Этот макрос не вызывает исключений.257258Эти API можно использовать для работы с суррогатами:259260#### `Py_UNICODE_IS_SURROGATE(ch)`261262Проверяет, является ли *ch* суррогатом (`0xD800 <= ch <= 0xDFFF`).263264#### `Py_UNICODE_IS_HIGH_SURROGATE(ch)`265266Проверяет, является ли *ch* старшим суррогатом (`0xD800 <= ch <= 0xDBFF`).267268#### `Py_UNICODE_IS_LOW_SURROGATE(ch)`269270Проверяет, является ли *ch* младшим суррогатом (`0xDC00 <= ch <= 0xDFFF`).271272#### `Py_UNICODE_JOIN_SURROGATES(high, low)`273274Объединяет два суррогатных символа и возвращает одно значение Py\_UCS4. *high* и *low* – это соответственно старший и младший суррогаты в суррогатной паре.275276### Создание строк Unicode и доступ к ним277278Для создания объектов Unicode и доступа к их базовым свойствам последовательности используйте следующие API:279280#### `PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)`281282*Возвращаемое значение: новая ссылка.*283284Создаёт новый объект Unicode. *maxchar* должен быть истинным максимальным кодом, который будет помещён в строку. В качестве приближения его можно округлить до ближайшего значения из последовательности 127, 255, 65535, 1114111.285286Это рекомендуемый способ выделения нового объекта Unicode. Объекты, созданные с помощью этой функции, не подлежат изменению размера.287288Новое в версии 3.3.289290#### `PyObject *PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)`291292*Возвращаемое значение: новая ссылка.*293294Создаёт новый объект Unicode с заданным *видом* (возможные значения: [`PyUnicode_1BYTE_KIND`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_1BYTE_KIND) и т.д., возвращаемые [`PyUnicode_KIND()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_KIND)). *Буфер* должен указывать на массив из *size* единиц по 1, 2 или 4 байта на символ, в зависимости от вида.295296Новое в версии 3.3.297298#### `PyObject *PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)`299300*Возвращаемое значение: новая ссылка.*301302*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*303304Создаёт объект Unicode из буфера символов *u*. Байты будут интерпретироваться как закодированные в UTF-8. Буфер копируется в новый объект. Если буфер не равен `NULL`, возвращаемое значение может быть разделяемым объектом, т.е. изменение данных не допускается.305306Если *u* равен `NULL`, эта функция ведёт себя как [`PyUnicode_FromUnicode()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_FromUnicode) с буфером, установленным в `NULL`. Такое использование устарело в пользу [`PyUnicode_New()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_New) и будет удалено в Python 3.12.307308#### `PyObject *PyUnicode_FromString(const char *u)`309310*Возвращаемое значение: новая ссылка.*311312*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*313314Создаёт объект Unicode из UTF-8-закодированного нуль-терминированного буфера символов *u*.315316#### `PyObject *PyUnicode_FromFormat(const char *format, ...)`317318*Возвращаемое значение: новая ссылка.*319320*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*321322Принимает строку формата в стиле C `printf()` *format* и переменное число аргументов, вычисляет размер результирующей строки Python Unicode и возвращает строку со вставленными отформатированными значениями. Переменные аргументы должны быть типами C и должны точно соответствовать символам формата в строке *format*, закодированной в ASCII. Допускаются следующие символы формата:323324| Символы формата | Тип | Описание |325| --- | --- | --- |326| `%%` | *н/д* | Буквальный символ %. |327| `%c` | int | Один символ, представленный как C int. |328| `%d` | int | Эквивалентно `printf("%d")`. [1](https://python-all.ru/3.10/c-api/unicode.html#id14) |329| `%u` | unsigned int | Эквивалентно `printf("%u")`. [1](https://python-all.ru/3.10/c-api/unicode.html#id14) |330| `%ld` | long | Эквивалентно `printf("%ld")`. [1](https://python-all.ru/3.10/c-api/unicode.html#id14) |331| `%li` | long | Эквивалентно `printf("%li")`. [1](https://python-all.ru/3.10/c-api/unicode.html#id14) |332| `%lu` | unsigned long | Эквивалентно `printf("%lu")`. [1](https://python-all.ru/3.10/c-api/unicode.html#id14) |333| `%lld` | long long | Эквивалентно `printf("%lld")`. [1](https://python-all.ru/3.10/c-api/unicode.html#id14) |334| `%lli` | long long | Эквивалентно `printf("%lli")`. [1](https://python-all.ru/3.10/c-api/unicode.html#id14) |335| `%llu` | unsigned long long | Эквивалентно `printf("%llu")`. [1](https://python-all.ru/3.10/c-api/unicode.html#id14) |336| `%zd` | [`Py_ssize_t`](https://python-all.ru/3.10/c-api/intro.html#c.Py_ssize_t) | Эквивалентно `printf("%zd")`. [1](https://python-all.ru/3.10/c-api/unicode.html#id14) |337| `%zi` | [`Py_ssize_t`](https://python-all.ru/3.10/c-api/intro.html#c.Py_ssize_t) | Эквивалентно `printf("%zi")`. [1](https://python-all.ru/3.10/c-api/unicode.html#id14) |338| `%zu` | size\_t | Эквивалентно `printf("%zu")`. [1](https://python-all.ru/3.10/c-api/unicode.html#id14) |339| `%i` | int | Эквивалентно `printf("%i")`. [1](https://python-all.ru/3.10/c-api/unicode.html#id14) |340| `%x` | int | Эквивалентно `printf("%x")`. [1](https://python-all.ru/3.10/c-api/unicode.html#id14) |341| `%s` | const char\* | Нуль-терминированный массив символов C. |342| `%p` | const void\* | Шестнадцатеричное представление указателя C. В основном эквивалентно `printf("%p")`, за исключением того, что гарантированно начинается с литерала `0x` независимо от того, что возвращает `printf` на данной платформе. |343| `%A` | PyObject\* | Результат вызова [`ascii()`](https://python-all.ru/3.10/library/functions.html#ascii). |344| `%U` | PyObject\* | Объект Unicode. |345| `%V` | PyObject\*, const char\* | Объект Unicode (который может быть `NULL`) и завершающийся нулём символьный массив C в качестве второго параметра (который будет использоваться, если первый параметр равен `NULL`). |346| `%S` | PyObject\* | Результат вызова [`PyObject_Str()`](https://python-all.ru/3.10/c-api/object.html#c.PyObject_Str). |347| `%R` | PyObject\* | Результат вызова [`PyObject_Repr()`](https://python-all.ru/3.10/c-api/object.html#c.PyObject_Repr). |348349Нераспознанный символ формата приводит к тому, что вся оставшаяся строка формата копируется как есть в результирующую строку, а все лишние аргументы отбрасываются.350351> **Примечание**352>353> Единицей форматирования ширины является количество символов, а не байтов. Единицей форматирования точности является количество байтов для `"%s"` и `"%V"` (если аргумент `PyObject*` равен `NULL`) и количество символов для `"%A"`, `"%U"`, `"%S"`, `"%R"` и `"%V"` (если аргумент `PyObject*` не равен `NULL`).354355**1([1](https://python-all.ru/3.10/c-api/unicode.html#id1),[2](https://python-all.ru/3.10/c-api/unicode.html#id2),[3](https://python-all.ru/3.10/c-api/unicode.html#id3),[4](https://python-all.ru/3.10/c-api/unicode.html#id4),[5](https://python-all.ru/3.10/c-api/unicode.html#id5),[6](https://python-all.ru/3.10/c-api/unicode.html#id6),[7](https://python-all.ru/3.10/c-api/unicode.html#id7),[8](https://python-all.ru/3.10/c-api/unicode.html#id8),[9](https://python-all.ru/3.10/c-api/unicode.html#id9),[10](https://python-all.ru/3.10/c-api/unicode.html#id10),[11](https://python-all.ru/3.10/c-api/unicode.html#id11),[12](https://python-all.ru/3.10/c-api/unicode.html#id12),[13](https://python-all.ru/3.10/c-api/unicode.html#id13))**356357Для спецификаторов целых чисел (d, u, ld, li, lu, lld, lli, llu, zd, zi, zu, i, x): флаг преобразования 0 действует, даже если задана точность.358359Изменено в версии 3.2: Добавлена поддержка `"%lld"` и `"%llu"`.360361Изменено в версии 3.3: Добавлена поддержка `"%li"`, `"%lli"` и `"%zi"`.362363Изменено в версии 3.4: Добавлена поддержка форматтеров ширины и точности для `"%s"`, `"%A"`, `"%U"`, `"%V"`, `"%S"`, `"%R"`.364365#### `PyObject *PyUnicode_FromFormatV(const char *format, va_list vargs)`366367*Возвращаемое значение: новая ссылка.*368369*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*370371Идентично [`PyUnicode_FromFormat()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_FromFormat), за исключением того, что принимает ровно два аргумента.372373#### `PyObject *PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)`374375*Возвращаемое значение: новая ссылка.*376377*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*378379Декодирует закодированный объект *obj* в объект Unicode.380381[`bytes`](https://python-all.ru/3.10/library/stdtypes.html#bytes), [`bytearray`](https://python-all.ru/3.10/library/stdtypes.html#bytearray) и другие [объекты, подобные байтовым строкам](https://python-all.ru/3.10/glossary.html#term-bytes-like-object) декодируются в соответствии с заданной *encoding* и с использованием обработки ошибок, определённой *errors*. Оба параметра могут быть `NULL`, чтобы интерфейс использовал значения по умолчанию (см. [Встроенные кодеки](https://python-all.ru/3.10/c-api/unicode.html#builtincodecs) для подробностей).382383Все остальные объекты, включая объекты Unicode, приводят к установке [`TypeError`](https://python-all.ru/3.10/library/exceptions.html#TypeError).384385API возвращает `NULL` в случае ошибки. Вызывающий отвечает за уменьшение счётчика ссылок (decref) возвращённых объектов.386387#### `Py_ssize_t PyUnicode_GetLength(PyObject *unicode)`388389*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) начиная с версии 3.7.*390391Возвращает длину объекта Unicode в кодовых точках.392393Новое в версии 3.3.394395#### `Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t from_start, Py_ssize_t how_many)`396397Копирует символы из одного объекта Unicode в другой. При необходимости выполняет преобразование символов и, если возможно, использует `memcpy()`. Возвращает `-1` и устанавливает исключение при ошибке, в противном случае возвращает количество скопированных символов.398399Новое в версии 3.3.400401#### `Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)`402403Заполняет строку символом: записывает *fill\_char* в `unicode[start:start+length]`.404405Завершается ошибкой, если *fill\_char* больше максимального символа строки или если у строки больше одной ссылки.406407Возвращает количество записанных символов или `-1` и возбуждает исключение при ошибке.408409Новое в версии 3.3.410411#### `int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)`412413*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) начиная с версии 3.7.*414415Записывает символ в строку. Строка должна быть создана с помощью [`PyUnicode_New()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_New). Поскольку строки Unicode считаются неизменяемыми, строка не должна быть общей или уже хэшированной.416417Эта функция проверяет, что *unicode* является объектом Unicode, индекс не выходит за границы, и объект можно безопасно изменять (т.е. его счётчик ссылок равен единице).418419Новое в версии 3.3.420421#### `Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)`422423*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) начиная с версии 3.7.*424425Читает символ из строки. Эта функция проверяет, что *unicode* является объектом Unicode и индекс не выходит за границы, в отличие от макроса [`PyUnicode_READ_CHAR()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_READ_CHAR).426427Новое в версии 3.3.428429#### `PyObject *PyUnicode_Substring(PyObject *str, Py_ssize_t start, Py_ssize_t end)`430431*Возвращаемое значение: новая ссылка.*432433*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) начиная с версии 3.7.*434435Возвращает подстроку *str* от индекса символа *start* (включительно) до индекса символа *end* (исключительно). Отрицательные индексы не поддерживаются.436437Новое в версии 3.3.438439#### `Py_UCS4 *PyUnicode_AsUCS4(PyObject *u, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)`440441*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) начиная с версии 3.7.*442443Копирует строку *u* в буфер UCS4, включая нулевой символ, если *copy\_null* установлен. Возвращает `NULL` и устанавливает исключение при ошибке (в частности, [`SystemError`](https://python-all.ru/3.10/library/exceptions.html#SystemError), если *buflen* меньше длины *u*). В случае успеха возвращается *buffer*.444445Новое в версии 3.3.446447#### `Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *u)`448449*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) начиная с версии 3.7.*450451Копирует строку *u* в новый буфер UCS4, выделяемый с помощью [`PyMem_Malloc()`](https://python-all.ru/3.10/c-api/memory.html#c.PyMem_Malloc). Если это не удаётся, возвращается `NULL` с установленным [`MemoryError`](https://python-all.ru/3.10/library/exceptions.html#MemoryError). Возвращаемый буфер всегда содержит дополнительный нулевой кодовый элемент.452453Новое в версии 3.3.454455### Устаревшие API Py\_UNICODE456457Устарело с версии 3.3, будет удалено в версии 3.12.458459Эти функции API устарели с реализацией [**PEP 393**](https://python-all.ru/3.10/c-api/unicode.html). Модули-расширения могут продолжать их использовать, поскольку они не будут удалены в Python 3.x, но следует учитывать, что их использование теперь может приводить к снижению производительности и увеличению потребления памяти.460461#### `PyObject *PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)`462463*Возвращаемое значение: новая ссылка.*464465Создаёт объект Unicode из буфера Py\_UNICODE *u* заданного размера. *u* может быть `NULL`, что делает содержимое неопределённым. Пользователь отвечает за заполнение необходимых данных. Буфер копируется в новый объект.466467Если буфер не равен `NULL`, возвращаемое значение может быть разделяемым объектом. Поэтому изменение полученного объекта Unicode разрешено только тогда, когда *u* равен `NULL`.468469Если буфер равен `NULL`, [`PyUnicode_READY()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_READY) должен быть вызван после заполнения содержимого строки, перед использованием любых макросов доступа, таких как [`PyUnicode_KIND()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_KIND).470471Устарело с версии 3.3, будет удалено в версии 3.12: Часть старого стиля Unicode API, перейдите на использование [`PyUnicode_FromKindAndData()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_FromKindAndData), [`PyUnicode_FromWideChar()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_FromWideChar) или [`PyUnicode_New()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_New).472473#### `Py_UNICODE *PyUnicode_AsUnicode(PyObject *unicode)`474475Возвращает указатель только для чтения на внутренний [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE) буфер объекта Unicode или `NULL` в случае ошибки. При этом создаётся `Py_UNICODE*` представление объекта, если оно ещё не доступно. Буфер всегда завершается дополнительным нулевым кодовым элементом. Обратите внимание, что результирующая строка [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE) может также содержать встроенные нулевые кодовые элементы, что приведёт к усечению строки при использовании в большинстве функций C.476477Устарело с версии 3.3, будет удалено в версии 3.12: Часть старого стиля Unicode API, перейдите на использование [`PyUnicode_AsUCS4()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsUCS4), [`PyUnicode_AsWideChar()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsWideChar), [`PyUnicode_ReadChar()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_ReadChar) или аналогичных новых API.478479#### `PyObject *PyUnicode_TransformDecimalToASCII(Py_UNICODE *s, Py_ssize_t size)`480481*Возвращаемое значение: новая ссылка.*482483Создаёт объект Unicode, заменяя все десятичные цифры в буфере [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE) указанного размера *size* на цифры ASCII 0–9 в соответствии с их десятичным значением. Возвращает `NULL` в случае возникновения исключения.484485Устарело с версии 3.3, будет удалено в версии 3.11: Часть устаревшего API [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`Py_UNICODE_TODECIMAL()`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE_TODECIMAL).486487#### `Py_UNICODE *PyUnicode_AsUnicodeAndSize(PyObject *unicode, Py_ssize_t *size)`488489Как и [`PyUnicode_AsUnicode()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsUnicode), но также сохраняет длину массива [`Py_UNICODE()`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE) (исключая дополнительный нулевой терминатор) в *size*. Обратите внимание, что результирующая строка `Py_UNICODE*` может содержать встроенные нулевые кодовые элементы, что приведёт к усечению строки при использовании в большинстве функций C.490491Новое в версии 3.3.492493Устарело с версии 3.3, будет удалено в версии 3.12: Часть старого стиля Unicode API, перейдите на использование [`PyUnicode_AsUCS4()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsUCS4), [`PyUnicode_AsWideChar()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsWideChar), [`PyUnicode_ReadChar()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_ReadChar) или аналогичных новых API.494495#### `Py_ssize_t PyUnicode_GetSize(PyObject *unicode)`496497*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*498499Возвращает размер устаревшего представления [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE), в кодовых единицах (суррогатные пары учитываются как 2 единицы).500501Устарело с версии 3.3, будет удалено в версии 3.12: Часть старого API Unicode, переходите на использование [`PyUnicode_GET_LENGTH()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_GET_LENGTH).502503#### `PyObject *PyUnicode_FromObject(PyObject *obj)`504505*Возвращаемое значение: новая ссылка.*506507*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*508509Копирует экземпляр подтипа Unicode в новый истинный объект Unicode, если это необходимо. Если *obj* уже является истинным объектом Unicode (не подтипом), возвращает ссылку с увеличенным счётчиком ссылок.510511Объекты, отличные от Unicode или его подтипов, вызывают [`TypeError`](https://python-all.ru/3.10/library/exceptions.html#TypeError).512513### Кодировка локали514515Текущую кодировку локали можно использовать для декодирования текста из операционной системы.516517#### `PyObject *PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t len, const char *errors)`518519*Возвращаемое значение: новая ссылка.*520521*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) начиная с версии 3.7.*522523Decode 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.10/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.524525Используйте [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize) для декодирования строки из `Py_FileSystemDefaultEncoding` (кодировка локали, полученная при запуске Python).526527Эта функция игнорирует [режим UTF-8 Python](https://python-all.ru/3.10/library/os.html#utf8-mode).528529> **См. также**530>531> Функция [`Py_DecodeLocale()`](https://python-all.ru/3.10/c-api/sys.html#c.Py_DecodeLocale).532533Новое в версии 3.3.534535Изменено в версии 3.7: Теперь функция также использует текущую кодировку локали для обработчика ошибок `surrogateescape`, за исключением Android. Ранее для `surrogateescape` использовался [`Py_DecodeLocale()`](https://python-all.ru/3.10/c-api/sys.html#c.Py_DecodeLocale), а для `strict` использовалась текущая кодировка локали.536537#### `PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors)`538539*Возвращаемое значение: новая ссылка.*540541*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) начиная с версии 3.7.*542543Аналогично [`PyUnicode_DecodeLocaleAndSize()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_DecodeLocaleAndSize), но длина строки вычисляется с помощью `strlen()`.544545Новое в версии 3.3.546547#### `PyObject *PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)`548549*Возвращаемое значение: новая ссылка.*550551*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) начиная с версии 3.7.*552553Encode 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.10/c-api/unicode.html)). The encoder uses `"strict"` error handler if *errors* is `NULL`. Return a [`bytes`](https://python-all.ru/3.10/library/stdtypes.html#bytes) object. *unicode* cannot contain embedded null characters.554555Используйте [`PyUnicode_EncodeFSDefault()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_EncodeFSDefault) для кодирования строки в `Py_FileSystemDefaultEncoding` (кодировка локали, полученная при запуске Python).556557Эта функция игнорирует [режим UTF-8 Python](https://python-all.ru/3.10/library/os.html#utf8-mode).558559> **См. также**560>561> Функция [`Py_EncodeLocale()`](https://python-all.ru/3.10/c-api/sys.html#c.Py_EncodeLocale).562563Новое в версии 3.3.564565Изменено в версии 3.7: Теперь функция также использует текущую кодировку локали для обработчика ошибок `surrogateescape`, за исключением Android. Ранее для `surrogateescape` использовался [`Py_EncodeLocale()`](https://python-all.ru/3.10/c-api/sys.html#c.Py_EncodeLocale), а для `strict` использовалась текущая кодировка локали.566567### Кодировка файловой системы568569Для кодирования и декодирования имён файлов и других строк окружения в качестве кодировки следует использовать `Py_FileSystemDefaultEncoding`, а в качестве обработчика ошибок – `Py_FileSystemDefaultEncodeErrors` ([**PEP 383**](https://python-all.ru/3.10/c-api/unicode.html) и [**PEP 529**](https://python-all.ru/3.10/c-api/unicode.html)). Для кодирования имён файлов в [`bytes`](https://python-all.ru/3.10/library/stdtypes.html#bytes) при разборе аргументов следует использовать преобразователь `"O&"`, передавая [`PyUnicode_FSConverter()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_FSConverter) в качестве функции преобразования:570571#### `int PyUnicode_FSConverter(PyObject *obj, void *result)`572573*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*574575Конвертер ParseTuple: кодирует объекты [`str`](https://python-all.ru/3.10/library/stdtypes.html#str) – полученные напрямую или через интерфейс [`os.PathLike`](https://python-all.ru/3.10/library/os.html#os.PathLike) – в [`bytes`](https://python-all.ru/3.10/library/stdtypes.html#bytes) с помощью [`PyUnicode_EncodeFSDefault()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_EncodeFSDefault); объекты [`bytes`](https://python-all.ru/3.10/library/stdtypes.html#bytes) выводятся как есть. *result* должен быть `PyBytesObject*`, который необходимо освободить, когда он больше не используется.576577Новое в версии 3.1.578579Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.10/glossary.html#term-path-like-object).580581Для декодирования имен файлов в [`str`](https://python-all.ru/3.10/library/stdtypes.html#str) во время разбора аргументов следует использовать конвертер `"O&"`, передавая [`PyUnicode_FSDecoder()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_FSDecoder) в качестве функции преобразования:582583#### `int PyUnicode_FSDecoder(PyObject *obj, void *result)`584585*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*586587Конвертер ParseTuple: декодирует объекты [`bytes`](https://python-all.ru/3.10/library/stdtypes.html#bytes) – полученные либо напрямую, либо косвенно через интерфейс [`os.PathLike`](https://python-all.ru/3.10/library/os.html#os.PathLike) – в [`str`](https://python-all.ru/3.10/library/stdtypes.html#str) с помощью [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize); объекты [`str`](https://python-all.ru/3.10/library/stdtypes.html#str) выводятся как есть. *result* должен быть `PyUnicodeObject*`, который необходимо освободить, когда он больше не используется.588589Новое в версии 3.2.590591Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.10/glossary.html#term-path-like-object).592593#### `PyObject *PyUnicode_DecodeFSDefaultAndSize(const char *s, Py_ssize_t size)`594595*Возвращаемое значение: новая ссылка.*596597*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*598599Декодирует строку из [кодировки файловой системы и обработчика ошибок](https://python-all.ru/3.10/glossary.html#term-filesystem-encoding-and-error-handler).600601Если `Py_FileSystemDefaultEncoding` не задана, используется кодировка локали.602603`Py_FileSystemDefaultEncoding` инициализируется при запуске из кодировки локали и не может быть изменена позднее. Если требуется декодировать строку из текущей кодировки локали, используйте [`PyUnicode_DecodeLocaleAndSize()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_DecodeLocaleAndSize).604605> **См. также**606>607> Функция [`Py_DecodeLocale()`](https://python-all.ru/3.10/c-api/sys.html#c.Py_DecodeLocale).608609Изменено в версии 3.6: Используйте обработчик ошибок `Py_FileSystemDefaultEncodeErrors`.610611#### `PyObject *PyUnicode_DecodeFSDefault(const char *s)`612613*Возвращаемое значение: новая ссылка.*614615*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*616617Декодирует строку, завершающуюся нулевым символом, из [кодировки файловой системы и обработчика ошибок](https://python-all.ru/3.10/glossary.html#term-filesystem-encoding-and-error-handler).618619Если `Py_FileSystemDefaultEncoding` не задана, используется кодировка локали.620621Используйте [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize), если известна длина строки.622623Изменено в версии 3.6: Используйте обработчик ошибок `Py_FileSystemDefaultEncodeErrors`.624625#### `PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)`626627*Возвращаемое значение: новая ссылка.*628629*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*630631Кодирует объект Unicode в `Py_FileSystemDefaultEncoding` с обработчиком ошибок `Py_FileSystemDefaultEncodeErrors` и возвращает [`bytes`](https://python-all.ru/3.10/library/stdtypes.html#bytes). Обратите внимание, что результирующий объект [`bytes`](https://python-all.ru/3.10/library/stdtypes.html#bytes) может содержать нулевые байты.632633Если `Py_FileSystemDefaultEncoding` не задана, используется кодировка локали.634635`Py_FileSystemDefaultEncoding` инициализируется при запуске из кодировки локали и не может быть изменена позднее. Если требуется закодировать строку в текущую кодировку локали, используйте [`PyUnicode_EncodeLocale()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_EncodeLocale).636637> **См. также**638>639> Функция [`Py_EncodeLocale()`](https://python-all.ru/3.10/c-api/sys.html#c.Py_EncodeLocale).640641Новое в версии 3.2.642643Изменено в версии 3.6: Используйте обработчик ошибок `Py_FileSystemDefaultEncodeErrors`.644645### Поддержка wchar\_t646647`wchar_t` поддержка на платформах, которые её поддерживают:648649#### `PyObject *PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)`650651*Возвращаемое значение: новая ссылка.*652653*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*654655Создаёт объект Unicode из буфера `wchar_t` *w* указанного размера *size*. Передача `-1` в качестве *size* указывает, что функция должна сама вычислить длину, используя wcslen. Возвращает `NULL` в случае неудачи.656657#### `Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *w, Py_ssize_t size)`658659*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*660661Копирует содержимое объекта Unicode в буфер `wchar_t` *w*. Копируется не более *size* символов `wchar_t` (исключая возможный завершающий нулевой символ). Возвращает количество скопированных символов `wchar_t` или `-1` в случае ошибки. Обратите внимание, что результирующая строка `wchar_t*` может быть как завершена нулевым символом, так и нет. Вызывающий обязан убедиться, что строка `wchar_t*` завершена нулевым символом, если это требуется приложением. Кроме того, строка `wchar_t*` может содержать нулевые символы, что приведёт к усечению строки при использовании с большинством функций C.662663#### `wchar_t *PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)`664665*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) начиная с версии 3.7.*666667Преобразует объект Unicode в широкую символьную строку. Выходная строка всегда завершается нулевым символом. Если *size* не равно `NULL`, количество широких символов (исключая завершающий нулевой символ) записывается в *\*size*. Обратите внимание, что результирующая строка `wchar_t` может содержать нулевые символы, что приведёт к усечению строки при использовании с большинством функций C. Если *size* равно `NULL` и строка `wchar_t*` содержит нулевые символы, возбуждается [`ValueError`](https://python-all.ru/3.10/library/exceptions.html#ValueError).668669В случае успеха возвращает буфер, выделенный функцией `PyMem_Alloc()` (для освобождения используйте [`PyMem_Free()`](https://python-all.ru/3.10/c-api/memory.html#c.PyMem_Free)). При ошибке возвращает `NULL`, а *\*size* не определён. Возбуждает [`MemoryError`](https://python-all.ru/3.10/library/exceptions.html#MemoryError), если выделение памяти не удалось.670671Новое в версии 3.2.672673Изменено в версии 3.7: Возбуждает [`ValueError`](https://python-all.ru/3.10/library/exceptions.html#ValueError), если *size* равно `NULL` и строка `wchar_t*` содержит нулевые символы.674675## Встроенные кодеки676677Python предоставляет набор встроенных кодеков, написанных на C для скорости. Все эти кодеки могут использоваться напрямую через следующие функции.678679Многие из следующих API принимают два аргумента: encoding и errors, и их семантика совпадает с семантикой соответствующих аргументов встроенного конструктора строк [`str()`](https://python-all.ru/3.10/library/stdtypes.html#str).680681Установка кодировки в `NULL` приводит к использованию кодировки по умолчанию, которая является UTF-8. Системные вызовы файловой системы должны использовать [`PyUnicode_FSConverter()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_FSConverter) для кодирования имён файлов. Для этого внутри используется переменная `Py_FileSystemDefaultEncoding`. Эту переменную следует считать доступной только для чтения: в некоторых системах это будет указатель на статическую строку, в других – она будет изменяться во время выполнения (например, когда приложение вызывает setlocale).682683Обработка ошибок задаётся параметром errors, который также может быть установлен в `NULL`, что означает использование обработки по умолчанию, определённой для кодека. По умолчанию для всех встроенных кодеков используется строгий режим (возбуждается [`ValueError`](https://python-all.ru/3.10/library/exceptions.html#ValueError)).684685Все кодеки используют схожий интерфейс. Для простоты документированы только отличия от приведённого ниже общего описания.686687### Общие кодеки688689Это общие API кодеков:690691#### `PyObject *PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)`692693*Возвращаемое значение: новая ссылка.*694695*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*696697Создаёт объект Unicode путём декодирования *size* байтов закодированной строки *s*. *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры во встроенной функции [`str()`](https://python-all.ru/3.10/library/stdtypes.html#str). Используемый кодек находится с помощью реестра кодеков Python. Возвращает `NULL`, если кодек возбудил исключение.698699#### `PyObject *PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)`700701*Возвращаемое значение: новая ссылка.*702703*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*704705Кодирует объект Unicode и возвращает результат в виде объекта bytes. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода [`encode()`](https://python-all.ru/3.10/library/stdtypes.html#str.encode) объекта Unicode. Используемый кодек ищется с помощью реестра кодеков Python. Возвращает `NULL`, если кодек возбудил исключение.706707#### `PyObject *PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)`708709*Возвращаемое значение: новая ссылка.*710711Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE) *s* заданного *размера* и возвращает объект Python bytes. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода Unicode [`encode()`](https://python-all.ru/3.10/library/stdtypes.html#str.encode). Используемый кодек ищется по реестру кодеков Python. Возвращает `NULL`, если кодек выбросил исключение.712713Устарело с версии 3.3, будет удалено в версии 3.11: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsEncodedString).714715### Кодеки UTF-8716717Это API кодеков UTF-8:718719#### `PyObject *PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)`720721*Возвращаемое значение: новая ссылка.*722723*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*724725Создаёт объект Unicode, декодируя *size* байт строки *s* в кодировке UTF-8. Возвращает `NULL`, если кодек выбросил исключение.726727#### `PyObject *PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`728729*Возвращаемое значение: новая ссылка.*730731*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*732733Если *consumed* равно `NULL`, ведёт себя как [`PyUnicode_DecodeUTF8()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_DecodeUTF8). Если *consumed* не равно `NULL`, неполные конечные последовательности байтов UTF-8 не будут считаться ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.734735#### `PyObject *PyUnicode_AsUTF8String(PyObject *unicode)`736737*Возвращаемое значение: новая ссылка.*738739*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*740741Кодирует объект Unicode в UTF-8 и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.742743#### `const char *PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)`744745*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) начиная с версии 3.10.*746747Возвращает указатель на UTF-8-кодировку объекта Unicode и сохраняет размер закодированного представления (в байтах) в *size*. Аргумент *size* может быть `NULL`; в этом случае размер не сохраняется. Возвращаемый буфер всегда содержит дополнительный нулевой байт в конце (не включён в *size*), независимо от наличия других нулевых кодовых точек.748749В случае ошибки возвращается `NULL` с установленным исключением, а *size* не сохраняется.750751Это кеширует UTF-8-представление строки в объекте Unicode, и последующие вызовы будут возвращать указатель на тот же буфер. Вызывающий не отвечает за освобождение буфера. Буфер освобождается, а указатели на него становятся недействительными, когда объект Unicode удаляется сборщиком мусора.752753Новое в версии 3.3.754755Изменено в версии 3.7: Тип возвращаемого значения теперь `const char *` вместо `char *`.756757Изменено в версии 3.10: Эта функция является частью [ограниченного API](https://python-all.ru/3.10/c-api/stable.html#stable).758759#### `const char *PyUnicode_AsUTF8(PyObject *unicode)`760761Как [`PyUnicode_AsUTF8AndSize()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsUTF8AndSize), но не сохраняет размер.762763Новое в версии 3.3.764765Изменено в версии 3.7: Тип возвращаемого значения теперь `const char *` вместо `char *`.766767#### `PyObject *PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`768769*Возвращаемое значение: новая ссылка.*770771Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE) *s* заданного *размера* с использованием UTF-8 и возвращает объект Python bytes. Возвращает `NULL`, если кодек выбросил исключение.772773Устарело с версии 3.3, будет удалено в версии 3.11: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsUTF8String()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsUTF8String), [`PyUnicode_AsUTF8AndSize()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsUTF8AndSize) или [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsEncodedString).774775### Кодеки UTF-32776777Это API кодеков UTF-32:778779#### `PyObject *PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)`780781*Возвращаемое значение: новая ссылка.*782783*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*784785Декодирует *size* байтов из буферной строки, закодированной в UTF-32, и возвращает соответствующий объект Unicode. *errors* (если не `NULL`) определяет обработку ошибок. По умолчанию – «strict».786787Если *byteorder* не равно `NULL`, декодер начинает декодирование с указанным порядком байтов:788789```c790*byteorder == -1: little endian791*byteorder == 0:  native order792*byteorder == 1:  big endian793```794795Если `*byteorder` равен нулю и первые четыре байта входных данных являются маркером порядка байтов (BOM), декодер переключается на этот порядок байтов, и BOM не копируется в результирующую строку Unicode. Если `*byteorder` равно `-1` или `1`, любой маркер порядка байтов копируется в выходные данные.796797После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных.798799Если *byteorder* равен `NULL`, кодек запускается в режиме собственного порядка байтов.800801Возвращает `NULL`, если кодек вызвал исключение.802803#### `PyObject *PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)`804805*Возвращаемое значение: новая ссылка.*806807*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*808809Если *consumed* равно `NULL`, ведёт себя как [`PyUnicode_DecodeUTF32()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_DecodeUTF32). Если *consumed* не равно `NULL`, [`PyUnicode_DecodeUTF32Stateful()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_DecodeUTF32Stateful) не будет считать неполные конечные последовательности байтов UTF-32 (например, количество байтов, не делящееся на четыре) ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.810811#### `PyObject *PyUnicode_AsUTF32String(PyObject *unicode)`812813*Возвращаемое значение: новая ссылка.*814815*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*816817Возвращает байтовую строку Python в кодировке UTF-32 в собственном порядке байтов. Строка всегда начинается с метки BOM. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.818819#### `PyObject *PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)`820821*Возвращаемое значение: новая ссылка.*822823Возвращает объект Python bytes, содержащий значение Unicode-данных из *s*, закодированное в UTF-32. Вывод записывается в соответствии со следующим порядком байтов:824825```c826byteorder == -1: little endian827byteorder == 0:  native byte order (writes a BOM mark)828byteorder == 1:  big endian829```830831Если `0`, выходная строка всегда начинается с метки BOM Unicode (U+FEFF). В двух других режимах метка BOM не добавляется.832833Если `Py_UNICODE_WIDE` не определён, суррогатные пары будут выводиться как одна кодовая точка.834835Возвращает `NULL`, если кодек вызвал исключение.836837Устарело с версии 3.3, будет удалено в версии 3.11: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsUTF32String()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsUTF32String) или [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsEncodedString).838839### Кодеки UTF-32840841Это API кодеков UTF-32:842843#### `PyObject *PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)`844845*Возвращаемое значение: новая ссылка.*846847*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*848849Декодирует *size* байтов из строки буфера, закодированной в UTF-16, и возвращает соответствующий объект Unicode. *errors* (если не `NULL`) определяет обработку ошибок. По умолчанию используется «strict».850851Если *byteorder* не равно `NULL`, декодер начинает декодирование с указанным порядком байтов:852853```c854*byteorder == -1: little endian855*byteorder == 0:  native order856*byteorder == 1:  big endian857```858859Если `*byteorder` равен нулю и первые два байта входных данных являются меткой порядка байтов (BOM), декодер переключается на этот порядок байтов, а BOM не копируется в результирующую строку Unicode. Если `*byteorder` равен `-1` или `1`, любая метка порядка байтов копируется в выходные данные (что приведёт к символу `\ufeff` или `\ufffe`).860861После завершения `*byteorder` устанавливается в текущий порядок байтов в конце входных данных.862863Если *byteorder* равен `NULL`, кодек запускается в режиме собственного порядка байтов.864865Возвращает `NULL`, если кодек вызвал исключение.866867#### `PyObject *PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)`868869*Возвращаемое значение: новая ссылка.*870871*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*872873Если *consumed* равен `NULL`, ведёт себя как [`PyUnicode_DecodeUTF16()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_DecodeUTF16). Если *consumed* не равен `NULL`, [`PyUnicode_DecodeUTF16Stateful()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_DecodeUTF16Stateful) не будет рассматривать хвостовые неполные последовательности байтов UTF-16 (например, нечётное количество байтов или разбитую суррогатную пару) как ошибку. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.874875#### `PyObject *PyUnicode_AsUTF16String(PyObject *unicode)`876877*Возвращаемое значение: новая ссылка.*878879*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*880881Возвращает байтовую строку Python в кодировке UTF-16 в собственном порядке байтов. Строка всегда начинается с метки BOM. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.882883#### `PyObject *PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)`884885*Возвращаемое значение: новая ссылка.*886887Возвращает объект Python bytes, содержащий значение Unicode-данных из *s*, закодированное в UTF-16. Вывод записывается в соответствии со следующим порядком байтов:888889```c890byteorder == -1: little endian891byteorder == 0:  native byte order (writes a BOM mark)892byteorder == 1:  big endian893```894895Если `0`, выходная строка всегда начинается с метки BOM Unicode (U+FEFF). В двух других режимах метка BOM не добавляется.896897Если `Py_UNICODE_WIDE` определён, одно значение [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE) может быть представлено как суррогатная пара. Если не определён, каждое значение [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE) интерпретируется как символ UCS-2.898899Возвращает `NULL`, если кодек вызвал исключение.900901Устарело с версии 3.3, будет удалено в версии 3.11: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsUTF16String()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsUTF16String) или [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsEncodedString).902903### Кодеки UTF-7904905Это API кодеков UTF-7:906907#### `PyObject *PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)`908909*Возвращаемое значение: новая ссылка.*910911*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*912913Создаёт объект Unicode, декодируя *size* байт строки *s* в кодировке UTF-7. Возвращает `NULL`, если кодек выбросил исключение.914915#### `PyObject *PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`916917*Возвращаемое значение: новая ссылка.*918919*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*920921Если *consumed* равен `NULL`, ведёт себя как [`PyUnicode_DecodeUTF7()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_DecodeUTF7). Если *consumed* не равен `NULL`, хвостовые неполные секции base-64 UTF-7 не будут рассматриваться как ошибка. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.922923#### `PyObject *PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)`924925*Возвращаемое значение: новая ссылка.*926927Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE) указанного размера с помощью UTF-7 и возвращает объект Python bytes. Возвращает `NULL`, если кодек вызвал исключение.928929Если *base64SetO* не равно нулю, «Set O» (знаки препинания, не имеющие иного особого значения) будут закодированы в base-64. Если *base64WhiteSpace* не равно нулю, пробельные символы будут закодированы в base-64. Оба параметра установлены в ноль для кодека Python «utf-7».930931Устарело с версии 3.3, будет удалено в версии 3.11: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsEncodedString).932933### Кодеки Unicode-Escape934935Это API кодеков «Unicode Escape»:936937#### `PyObject *PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)`938939*Возвращаемое значение: новая ссылка.*940941*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*942943Создаёт объект Unicode, декодируя *size* байтов строки *s*, закодированной в Unicode-Escape. Возвращает `NULL`, если кодек вызвал исключение.944945#### `PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)`946947*Возвращаемое значение: новая ссылка.*948949*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*950951Кодирует объект Unicode с помощью Unicode-Escape и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.952953#### `PyObject *PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)`954955*Возвращаемое значение: новая ссылка.*956957Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE) указанного *size* с помощью Unicode-Escape и возвращает объект bytes. Возвращает `NULL`, если кодек вызвал исключение.958959Устарело с версии 3.3, будет удалено в версии 3.11: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsUnicodeEscapeString()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsUnicodeEscapeString).960961### Кодеки Raw-Unicode-Escape962963Это API кодеков «Raw Unicode Escape»:964965#### `PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)`966967*Возвращаемое значение: новая ссылка.*968969*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*970971Создаёт объект Unicode, декодируя *size* байтов строки *s*, закодированной в Raw-Unicode-Escape. Возвращает `NULL`, если кодек вызвал исключение.972973#### `PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)`974975*Возвращаемое значение: новая ссылка.*976977*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*978979Кодирует объект Unicode с помощью Raw-Unicode-Escape и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.980981#### `PyObject *PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)`982983*Возвращаемое значение: новая ссылка.*984985Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE) указанного *size* с помощью Raw-Unicode-Escape и возвращает объект bytes. Возвращает `NULL`, если кодек вызвал исключение.986987Устарело с версии 3.3, будет удалено в версии 3.11: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsRawUnicodeEscapeString()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsRawUnicodeEscapeString) или [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsEncodedString).988989### Кодеки Latin-1990991Это API кодеков Latin-1: Latin-1 соответствует первым 256 кодовым позициям Unicode, и только они принимаются кодеками при кодировании.992993#### `PyObject *PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)`994995*Возвращаемое значение: новая ссылка.*996997*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*998999Создаёт объект Unicode, декодируя *size* байтов строки *s*, закодированной в Latin-1. Возвращает `NULL`, если кодек вызвал исключение.10001001#### `PyObject *PyUnicode_AsLatin1String(PyObject *unicode)`10021003*Возвращаемое значение: новая ссылка.*10041005*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*10061007Кодирует объект Unicode с помощью Latin-1 и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает `NULL`, если кодек выбросил исключение.10081009#### `PyObject *PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`10101011*Возвращаемое значение: новая ссылка.*10121013Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE) указанного *size* с помощью Latin-1 и возвращает объект Python bytes. Возвращает `NULL`, если кодек вызвал исключение.10141015Устарело с версии 3.3, будет удалено в версии 3.11: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsLatin1String()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsLatin1String) или [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsEncodedString).10161017### Кодеки ASCII10181019Это API кодеков ASCII. Принимаются только 7-битные данные ASCII. Все остальные коды вызывают ошибки.10201021#### `PyObject *PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)`10221023*Возвращаемое значение: новая ссылка.*10241025*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*10261027Создаёт объект Unicode, декодируя *size* байтов строки *s*, закодированной в ASCII. Возвращает `NULL`, если кодек вызвал исключение.10281029#### `PyObject *PyUnicode_AsASCIIString(PyObject *unicode)`10301031*Возвращаемое значение: новая ссылка.*10321033*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*10341035Кодирует объект Unicode с помощью ASCII и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает `NULL`, если кодек выбросил исключение.10361037#### `PyObject *PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`10381039*Возвращаемое значение: новая ссылка.*10401041Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE) указанного *size* с помощью ASCII и возвращает объект Python bytes. Возвращает `NULL`, если кодек вызвал исключение.10421043Устарело с версии 3.3, будет удалено в версии 3.11: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsASCIIString()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsASCIIString) или [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsEncodedString).10441045### Кодеки с таблицей символов10461047Этот кодек особенный тем, что его можно использовать для реализации множества различных кодеков (именно так и были получены большинство стандартных кодеков, входящих в пакет `encodings`). Кодек использует отображения для кодирования и декодирования символов. Предоставляемые объекты отображения должны поддерживать интерфейс отображения `__getitem__()`; словари и последовательности прекрасно работают.10481049Это API кодеков отображения:10501051#### `PyObject *PyUnicode_DecodeCharmap(const char *data, Py_ssize_t size, PyObject *mapping, const char *errors)`10521053*Возвращаемое значение: новая ссылка.*10541055*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*10561057Создаёт объект Unicode, декодируя *size* байтов закодированной строки *s* с помощью указанного объекта *mapping*. Возвращает `NULL`, если кодек вызвал исключение.10581059Если *mapping* равен `NULL`, будет применяться декодирование Latin-1. В противном случае *mapping* должен отображать порядковые номера байтов (целые числа в диапазоне от 0 до 255) в строки Unicode, целые числа (которые затем интерпретируются как кодовые позиции Unicode) или `None`. Неотображённые байты данных – те, которые вызывают [`LookupError`](https://python-all.ru/3.10/library/exceptions.html#LookupError), а также те, которые отображаются в `None`, `0xFFFE` или `'\ufffe'`, считаются неопределёнными отображениями и вызывают ошибку.10601061#### `PyObject *PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)`10621063*Возвращаемое значение: новая ссылка.*10641065*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*10661067Кодирует объект Unicode с использованием заданного объекта *mapping* и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает `NULL`, если кодек выбросил исключение.10681069Объект *mapping* должен отображать целые числа – кодовые позиции Unicode – в объекты bytes, целые числа в диапазоне от 0 до 255 или `None`. Неотображённые кодовые позиции символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.10/library/exceptions.html#LookupError)), а также отображённые в `None` считаются «неопределённым отображением» и вызывают ошибку.10701071#### `PyObject *PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)`10721073*Возвращаемое значение: новая ссылка.*10741075Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE) заданного *размера* с помощью заданного объекта *mapping* и возвращает результат в виде объекта bytes. Возвращает `NULL`, если кодек вызвал исключение.10761077Устарело с версии 3.3, будет удалено в версии 3.11: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsCharmapString()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsCharmapString) или [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsEncodedString).10781079Следующее API кодека особенное тем, что отображает Unicode в Unicode.10801081#### `PyObject *PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)`10821083*Возвращаемое значение: новая ссылка.*10841085*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*10861087Преобразует строку, применяя к ней таблицу отображения символов, и возвращает результирующий объект Unicode. Возвращает `NULL`, если кодек выбросил исключение.10881089Таблица отображения должна отображать целые числа – кодовые позиции Unicode – в целые числа – кодовые позиции Unicode – или в `None` (вызывает удаление символа).10901091Таблицы отображения должны лишь предоставлять интерфейс `__getitem__()`; словари и последовательности работают хорошо. Неотображённые кодовые позиции символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.10/library/exceptions.html#LookupError)) остаются нетронутыми и копируются как есть.10921093*errors* имеет обычное для кодеков значение. Он может быть `NULL`, что означает использование обработки ошибок по умолчанию.10941095#### `PyObject *PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)`10961097*Возвращаемое значение: новая ссылка.*10981099Преобразует буфер [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE) заданного *размера*, применяя таблицу *mapping* символов, и возвращает результирующий объект Unicode. Возвращает `NULL`, когда кодек вызвал исключение.11001101Устарело с версии 3.3, будет удалено в версии 3.11: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_Translate()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_Translate). или [универсального API на основе кодеков](https://python-all.ru/3.10/c-api/codec.html#codec-registry)11021103### Кодеки MBCS для Windows11041105Это API кодеков MBCS. В настоящее время они доступны только в Windows и используют преобразователи Win32 MBCS для выполнения преобразований. Обратите внимание, что MBCS (или DBCS) – это класс кодировок, а не одна конкретная. Целевая кодировка определяется пользовательскими настройками на машине, где выполняется кодек.11061107#### `PyObject *PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)`11081109*Возвращаемое значение: новая ссылка.*11101111*Часть [стабильного ABI](https://python-all.ru/3.10/c-api/stable.html#stable) на Windows с версии 3.7.*11121113Создаёт объект Unicode, декодируя *size* байт строки *s*, закодированной в MBCS. Возвращает `NULL`, если кодек вызвал исключение.11141115#### `PyObject *PyUnicode_DecodeMBCSStateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`11161117*Возвращаемое значение: новая ссылка.*11181119*Часть [стабильного ABI](https://python-all.ru/3.10/c-api/stable.html#stable) на Windows с версии 3.7.*11201121Если *consumed* равно `NULL`, поведение аналогично [`PyUnicode_DecodeMBCS()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_DecodeMBCS). Если *consumed* не равно `NULL`, [`PyUnicode_DecodeMBCSStateful()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_DecodeMBCSStateful) не будет декодировать конечный ведущий байт, а количество декодированных байт будет сохранено в *consumed*.11221123#### `PyObject *PyUnicode_AsMBCSString(PyObject *unicode)`11241125*Возвращаемое значение: новая ссылка.*11261127*Часть [стабильного ABI](https://python-all.ru/3.10/c-api/stable.html#stable) на Windows с версии 3.7.*11281129Кодирует объект Unicode с помощью MBCS и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.11301131#### `PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)`11321133*Возвращаемое значение: новая ссылка.*11341135*Часть [стабильного ABI](https://python-all.ru/3.10/c-api/stable.html#stable) на Windows с версии 3.7.*11361137Кодирует объект Unicode с помощью указанной кодовой страницы и возвращает объект bytes. Возвращает `NULL`, если кодек вызвал исключение. Используйте кодовую страницу `CP_ACP` для получения кодировщика MBCS.11381139Новое в версии 3.3.11401141#### `PyObject *PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`11421143*Возвращаемое значение: новая ссылка.*11441145Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE) заданного *размера* с использованием MBCS и возвращает объект Python bytes. Возвращает `NULL`, если кодек вызвал исключение.11461147Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.10/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsMBCSString()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsMBCSString), [`PyUnicode_EncodeCodePage()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_EncodeCodePage) или [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_AsEncodedString).11481149### Методы и слоты11501151## Методы и слот-функции11521153Следующие API могут обрабатывать объекты Unicode и строки на входе (в описаниях мы называем их строками) и возвращают объекты Unicode или целые числа по необходимости.11541155Все они возвращают `NULL` или `-1` в случае возникновения исключения.11561157#### `PyObject *PyUnicode_Concat(PyObject *left, PyObject *right)`11581159*Возвращаемое значение: новая ссылка.*11601161*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*11621163Объединяет две строки, возвращая новую строку Unicode.11641165#### `PyObject *PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)`11661167*Возвращаемое значение: новая ссылка.*11681169*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*11701171Разделяет строку, возвращая список строк Unicode. Если *sep* равно `NULL`, разделение происходит по всем пробельным подстрокам. В противном случае разделение происходит по указанному разделителю. Будет выполнено не более *maxsplit* разбиений. Если значение отрицательное, ограничение не задано. Разделители не включаются в результирующий список.11721173#### `PyObject *PyUnicode_Splitlines(PyObject *s, int keepend)`11741175*Возвращаемое значение: новая ссылка.*11761177*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*11781179Разделяет строку Unicode по символам перевода строки и возвращает список строк Unicode. Последовательность CRLF считается одним переносом строки. Если *keepend* равен `0`, символы переноса строки не включаются в результирующие строки.11801181#### `PyObject *PyUnicode_Join(PyObject *separator, PyObject *seq)`11821183*Возвращаемое значение: новая ссылка.*11841185*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*11861187Объединяет последовательность строк, используя заданный *разделитель*, и возвращает полученную Unicode-строку.11881189#### `Py_ssize_t PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)`11901191*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*11921193Возвращает `1`, если *substr* совпадает с `str[start:end]` на заданном хвосте (*direction* == `-1` означает проверку на совпадение с началом, *direction* == `1` – с концом), иначе `0`. Возвращает `-1`, если произошла ошибка.11941195#### `Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)`11961197*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*11981199Возвращает первую позицию *substr* в `str[start:end]`, используя заданное *direction* (*direction* == `1` означает прямой поиск, *direction* == `-1` – обратный). Возвращаемое значение – индекс первого совпадения; значение `-1` означает, что совпадений не найдено, а `-2` – что произошла ошибка и было установлено исключение.12001201#### `Py_ssize_t PyUnicode_FindChar(PyObject *str, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)`12021203*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) начиная с версии 3.7.*12041205Возвращает первую позицию символа *ch* в `str[start:end]`, используя заданное *direction* (*direction* == `1` означает прямой поиск, *direction* == `-1` – обратный). Возвращаемое значение – индекс первого совпадения; значение `-1` означает, что совпадений не найдено, а `-2` – что произошла ошибка и было установлено исключение.12061207Новое в версии 3.3.12081209Изменено в версии 3.7: *start* и *end* теперь скорректированы, чтобы вести себя как `str[start:end]`.12101211#### `Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)`12121213*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*12141215Возвращает количество неперекрывающихся вхождений *substr* в `str[start:end]`. Возвращает `-1`, если произошла ошибка.12161217#### `PyObject *PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)`12181219*Возвращаемое значение: новая ссылка.*12201221*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*12221223Заменяет не более *maxcount* вхождений *substr* в *str* на *replstr* и возвращает результирующий объект Unicode. *maxcount* == `-1` означает замену всех вхождений.12241225#### `int PyUnicode_Compare(PyObject *left, PyObject *right)`12261227*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*12281229Сравнивает две строки и возвращает `-1`, `0`, `1` для случаев меньше, равно и больше соответственно.12301231Эта функция возвращает `-1` при ошибке, поэтому для проверки на ошибки следует вызывать [`PyErr_Occurred()`](https://python-all.ru/3.10/c-api/exceptions.html#c.PyErr_Occurred).12321233#### `int PyUnicode_CompareWithASCIIString(PyObject *uni, const char *string)`12341235*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*12361237Сравнивает объект Unicode *uni* со строкой *string* и возвращает `-1`, `0`, `1` для случаев меньше, равно и больше соответственно. Рекомендуется передавать только строки в кодировке ASCII, но функция интерпретирует входную строку как ISO-8859-1, если она содержит не-ASCII символы.12381239Эта функция не вызывает исключений.12401241#### `PyObject *PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)`12421243*Возвращаемое значение: новая ссылка.*12441245*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*12461247Сравнивает две строки Unicode и возвращает одно из следующих значений:12481249- `NULL` в случае, если возникло исключение1250- `Py_True` или `Py_False` для успешных сравнений1251- `Py_NotImplemented` в случае, если комбинация типов неизвестна12521253Возможные значения для *op*: `Py_GT`, `Py_GE`, `Py_EQ`, `Py_NE`, `Py_LT` и `Py_LE`.12541255#### `PyObject *PyUnicode_Format(PyObject *format, PyObject *args)`12561257*Возвращаемое значение: новая ссылка.*12581259*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*12601261Возвращает новый строковый объект из *format* и *args*; это аналог `format % args`.12621263#### `int PyUnicode_Contains(PyObject *container, PyObject *element)`12641265*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*12661267Проверяет, содержится ли *element* в *container*, и возвращает true или false соответственно.12681269*Элемент* должен приводиться к одноэлементной строке Unicode. `-1` возвращается при возникновении ошибки.12701271#### `void PyUnicode_InternInPlace(PyObject **string)`12721273*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*12741275Интернирует аргумент *\*string* на месте. Аргументом должен быть адрес переменной-указателя, указывающей на объект строки Unicode в Python. Если уже существует интернированная строка, совпадающая с *\*string*, то она заменяет *\*string* на неё (освобождая ссылку на старый строковый объект и создавая новую [сильную ссылку](https://python-all.ru/3.10/glossary.html#term-strong-reference) на интернированный строковый объект); в противном случае она оставляет *\*string* без изменений и интернирует его (создавая новую [сильную ссылку](https://python-all.ru/3.10/glossary.html#term-strong-reference)). (Пояснение: хотя много говорится о ссылках, считайте эту функцию нейтральной по отношению к ссылкам; вызывающий код владеет объектом после вызова тогда и только тогда, когда он владел им до вызова.)12761277#### `PyObject *PyUnicode_InternFromString(const char *v)`12781279*Возвращаемое значение: новая ссылка.*12801281*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*12821283Комбинация [`PyUnicode_FromString()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_FromString) и [`PyUnicode_InternInPlace()`](https://python-all.ru/3.10/c-api/unicode.html#c.PyUnicode_InternInPlace), возвращающая либо новый интернированный объект строки Unicode, либо новую («собственную») ссылку на ранее интернированный объект строки с тем же значением.1284