`unicode.md`

738 строк · 67.3 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.2/c-api/unicode.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты Unicode и кодеки89## Объекты Unicode1011### Тип Unicode1213Это основные типы объектов Unicode, используемые в реализации Unicode в Python:1415**`Py_UNICODE`**1617Этот тип представляет тип хранения, который используется внутри Python в качестве основы для хранения порядковых номеров символов Unicode. В стандартной сборке Python используется 16-битный тип для [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE), и значения Unicode хранятся внутри в UCS2. Также возможна сборка Python с UCS4 (большинство современных дистрибутивов Linux поставляются с UCS4-сборками Python). В таких сборках используется 32-битный тип для [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE), и данные Unicode хранятся внутри в UCS4. На платформах, где `wchar_t` доступен и совместим с выбранным вариантом сборки Unicode Python, [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) является псевдонимом typedef для `wchar_t` для улучшения совместимости с нативной платформой. На всех остальных платформах [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) является псевдонимом typedef для `unsigned short` (UCS2) или `unsigned long` (UCS4).1819Обратите внимание, что сборки Python с UCS2 и UCS4 не являются двоично совместимыми. Учитывайте это при написании расширений или интерфейсов.2021**`PyUnicodeObject`**2223Этот подтип [`PyObject`](https://python-all.ru/3.2/c-api/structures.html#PyObject) представляет объект Unicode в Python.2425**[PyTypeObject](https://python-all.ru/3.2/c-api/type.html#PyTypeObject) `PyUnicode_Type`**2627Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.2/c-api/type.html#PyTypeObject) представляет тип Unicode в Python. Он доступен в коде Python как `str`.2829Следующие API на самом деле являются макросами C и могут использоваться для быстрых проверок и доступа к внутренним данным Unicode объектов только для чтения:3031#### `int PyUnicode_Check(PyObject *o)`3233Возвращает true, если объект *o* является объектом Unicode или экземпляром подтипа Unicode.3435#### `int PyUnicode_CheckExact(PyObject *o)`3637Возвращает true, если объект *o* является объектом Unicode, но не экземпляром подтипа.3839#### `Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)`4041Возвращает размер объекта. *o* должен быть [`PyUnicodeObject`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicodeObject) (не проверяется).4243#### `Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)`4445Возвращает размер внутреннего буфера объекта в байтах. *o* должен быть [`PyUnicodeObject`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicodeObject) (не проверяется).4647#### `Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)`4849Возвращает указатель на внутренний буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) объекта. *o* должен быть [`PyUnicodeObject`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicodeObject) (не проверяется).5051#### `const char* PyUnicode_AS_DATA(PyObject *o)`5253Возвращает указатель на внутренний буфер объекта. *o* должен быть [`PyUnicodeObject`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicodeObject) (не проверяется).5455#### `int PyUnicode_ClearFreeList()`5657Очищает список свободных элементов. Возвращает общее количество освобождённых элементов.5859### Свойства символов Unicode6061Unicode предоставляет множество различных свойств символов. Наиболее востребованные из них доступны через следующие макросы, которые сопоставляются с функциями на C в зависимости от конфигурации Python.6263#### `int Py_UNICODE_ISSPACE(Py_UNICODE ch)`6465Возвращает 1 или 0 в зависимости от того, является ли *ch* пробельным символом.6667#### `int Py_UNICODE_ISLOWER(Py_UNICODE ch)`6869Возвращает 1 или 0 в зависимости от того, является ли *ch* символом нижнего регистра.7071#### `int Py_UNICODE_ISUPPER(Py_UNICODE ch)`7273Возвращает 1 или 0 в зависимости от того, является ли *ch* символом верхнего регистра.7475#### `int Py_UNICODE_ISTITLE(Py_UNICODE ch)`7677Возвращает 1 или 0 в зависимости от того, является ли *ch* символом в регистре заголовка.7879#### `int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)`8081Возвращает 1 или 0 в зависимости от того, является ли *ch* символом разрыва строки.8283#### `int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)`8485Возвращает 1 или 0 в зависимости от того, является ли *ch* десятичной цифрой.8687#### `int Py_UNICODE_ISDIGIT(Py_UNICODE ch)`8889Возвращает 1 или 0 в зависимости от того, является ли *ch* цифровым символом.9091#### `int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)`9293Возвращает 1 или 0 в зависимости от того, является ли *ch* числовым символом.9495#### `int Py_UNICODE_ISALPHA(Py_UNICODE ch)`9697Возвращает 1 или 0 в зависимости от того, является ли *ch* буквенным символом.9899#### `int Py_UNICODE_ISALNUM(Py_UNICODE ch)`100101Возвращает 1 или 0 в зависимости от того, является ли *ch* буквенно-цифровым символом.102103#### `int Py_UNICODE_ISPRINTABLE(Py_UNICODE ch)`104105Возвращает 1 или 0 в зависимости от того, является ли *ch* печатаемым символом. Непечатаемые символы – это символы, определённые в базе данных Unicode как «Other» или «Separator», за исключением пробела ASCII (0x20), который считается печатаемым. (Обратите внимание, что печатаемые символы в этом контексте – это те, которые не должны экранироваться при вызове [`repr()`](https://python-all.ru/3.2/library/functions.html#repr) для строки. Это не влияет на обработку строк, записываемых в [`sys.stdout`](https://python-all.ru/3.2/library/sys.html#sys.stdout) или [`sys.stderr`](https://python-all.ru/3.2/library/sys.html#sys.stderr).)106107Эти API можно использовать для быстрых прямых преобразований символов:108109#### `Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)`110111Возвращает символ *ch*, преобразованный в нижний регистр.112113#### `Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)`114115Возвращает символ *ch*, преобразованный в верхний регистр.116117#### `Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)`118119Возвращает символ *ch*, приведённый к регистру заголовка.120121#### `int Py_UNICODE_TODECIMAL(Py_UNICODE ch)`122123Возвращает символ *ch*, преобразованный в десятичное положительное целое. Возвращает `-1`, если это невозможно. Этот макрос не вызывает исключений.124125#### `int Py_UNICODE_TODIGIT(Py_UNICODE ch)`126127Возвращает символ *ch*, преобразованный в целое однозначное число. Возвращает `-1`, если это невозможно. Этот макрос не вызывает исключений.128129#### `double Py_UNICODE_TONUMERIC(Py_UNICODE ch)`130131Возвращает символ *ch*, преобразованный в double. Возвращает `-1.0`, если это невозможно. Этот макрос не вызывает исключений.132133### Простой Py\_UNICODE134135Для создания объектов Unicode и доступа к их базовым свойствам последовательности используйте следующие API:136137#### `PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)`138139*Возвращаемое значение: новая ссылка.*140141Создаёт объект Unicode из буфера Py\_UNICODE *u* указанного размера. *u* может быть *NULL*, что делает содержимое неопределённым. Ответственность за заполнение нужными данными лежит на пользователе. Буфер копируется в новый объект. Если буфер не равен *NULL*, возвращаемое значение может быть разделяемым объектом. Поэтому изменение результирующего объекта Unicode допускается только когда *u* равно *NULL*.142143#### `PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)`144145Создаёт объект Unicode из буфера char *u*. Байты интерпретируются как кодировка UTF-8. *u* также может быть *NULL*, что делает содержимое неопределённым. Ответственность за заполнение нужными данными лежит на пользователе. Буфер копируется в новый объект. Если буфер не равен *NULL*, возвращаемое значение может быть разделяемым объектом. Поэтому изменение результирующего объекта Unicode допускается только когда *u* равно *NULL*.146147#### `PyObject *PyUnicode_FromString(const char *u)`148149Создаёт объект Unicode из UTF-8-кодированного символьного буфера с завершающим нулём *u*.150151#### `PyObject* PyUnicode_FromFormat(const char *format, ...)`152153Принимает строку *format* в стиле C `printf()` и переменное количество аргументов, вычисляет размер результирующей Python-строки Unicode и возвращает строку с отформатированными значениями. Переменные аргументы должны быть типами C и должны точно соответствовать символам формата в строке *format*, закодированной в ASCII. Допускаются следующие символы формата:154155| Символы формата | Тип | Описание |156| --- | --- | --- |157| `%%` | *н/д* | Буквальный символ %. |158| `%c` | int | Одиночный символ, представленный как C int. |159| `%d` | int | Полностью эквивалентно `printf("%d")`. |160| `%u` | беззнаковый int | Полностью эквивалентно `printf("%u")`. |161| `%ld` | long | Полностью эквивалентно `printf("%ld")`. |162| `%lu` | беззнаковый long | Полностью эквивалентно `printf("%lu")`. |163| `%lld` | long long | Полностью эквивалентно `printf("%lld")`. |164| `%llu` | беззнаковый long long | Полностью эквивалентно `printf("%llu")`. |165| `%zd` | Py\_ssize\_t | Полностью эквивалентно `printf("%zd")`. |166| `%zu` | size\_t | Полностью эквивалентно `printf("%zu")`. |167| `%i` | int | Полностью эквивалентно `printf("%i")`. |168| `%x` | int | Полностью эквивалентно `printf("%x")`. |169| `%s` | char\* | Нуль-терминированный массив символов C. |170| `%p` | void\* | Шестнадцатеричное представление указателя C. В основном эквивалентно `printf("%p")` за исключением того, что гарантированно начинается с литерала `0x` независимо от того, что выдает `printf` на данной платформе. |171| `%A` | PyObject\* | Результат вызова [`ascii()`](https://python-all.ru/3.2/library/functions.html#ascii). |172| `%U` | PyObject\* | Unicode-объект. |173| `%V` | PyObject\*, char \* | Unicode-объект (может быть *NULL*) и завершающийся нулевым символом C-массив символов в качестве второго параметра (используется, если первый параметр равен *NULL*). |174| `%S` | PyObject\* | Результат вызова [`PyObject_Str()`](https://python-all.ru/3.2/c-api/object.html#PyObject_Str). |175| `%R` | PyObject\* | Результат вызова [`PyObject_Repr()`](https://python-all.ru/3.2/c-api/object.html#PyObject_Repr). |176177Нераспознанный символ формата приводит к тому, что вся оставшаяся строка формата копируется как есть в результирующую строку, а все лишние аргументы отбрасываются.178179> **Примечание**180>181> Спецификаторы формата *"%lld"* и *"%llu"* доступны только при определённом `HAVE_LONG_LONG`.182183Изменено в версии 3.2: Добавлена поддержка `"%lld"` и `"%llu"`.184185#### `PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)`186187Идентична [`PyUnicode_FromFormat()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_FromFormat), за исключением того, что принимает ровно два аргумента.188189#### `PyObject* PyUnicode_TransformDecimalToASCII(Py_UNICODE *s, Py_ssize_t size)`190191Создаёт объект Unicode, заменяя все десятичные цифры в буфере [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) заданного размера *size* на ASCII-цифры 0–9 в соответствии с их десятичным значением. Возвращает *NULL* в случае возникновения исключения.192193#### `Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)`194195Возвращает указатель только для чтения на внутренний буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) объекта Unicode; *NULL*, если *unicode* не является объектом Unicode. Обратите внимание, что результирующая строка [`Py_UNICODE*`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) может содержать встроенные нулевые символы, что приведёт к усечению строки при использовании в большинстве функций C.196197#### `Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode)`198199Создаёт копию строки Unicode, завершающуюся нулевым символом. Возвращает *NULL* и возбуждает исключение [`MemoryError`](https://python-all.ru/3.2/library/exceptions.html#MemoryError) при сбое выделения памяти; в противном случае возвращает новый выделенный буфер (для освобождения буфера используйте [`PyMem_Free()`](https://python-all.ru/3.2/c-api/memory.html#PyMem_Free)). Обратите внимание, что результирующая строка [`Py_UNICODE*`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) может содержать встроенные нулевые символы, что приведёт к усечению строки при использовании в большинстве функций C.200201Новое в версии 3.2.202203#### `Py_ssize_t PyUnicode_GetSize(PyObject *unicode)`204205Возвращает длину объекта Unicode.206207#### `PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)`208209*Возвращаемое значение: новая ссылка.*210211Преобразует закодированный объект *obj* в объект Unicode и возвращает ссылку с увеличенным счётчиком ссылок.212213[`bytes`](https://python-all.ru/3.2/library/functions.html#bytes), [`bytearray`](https://python-all.ru/3.2/library/functions.html#bytearray) и другие объекты, совместимые с символьным буфером, декодируются согласно заданной *кодировке* с использованием обработки ошибок, определенной *errors*. Оба параметра могут быть *NULL*, чтобы интерфейс использовал значения по умолчанию (подробнее см. в следующем разделе).214215Все остальные объекты, включая объекты Unicode, вызывают установку [`TypeError`](https://python-all.ru/3.2/library/exceptions.html#TypeError).216217API возвращает *NULL* при ошибке. Вызывающий отвечает за уменьшение счётчика ссылок возвращённых объектов.218219#### `PyObject* PyUnicode_FromObject(PyObject *obj)`220221*Возвращаемое значение: новая ссылка.*222223Shortcut for `PyUnicode_FromEncodedObject(obj, NULL, "strict")` which is used throughout the interpreter whenever coercion to Unicode is needed.224225Если платформа поддерживает `wchar_t` и предоставляет заголовочный файл wchar.h, Python может напрямую взаимодействовать с этим типом с помощью следующих функций. Поддержка оптимизируется, если собственный тип [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) Python идентичен системному `wchar_t`.226227### Кодировка файловой системы228229Для кодирования и декодирования имён файлов и других строк окружения в качестве кодировки следует использовать `Py_FileSystemEncoding`, а в качестве обработчика ошибок – `"surrogateescape"` ([**PEP 383**](https://python-all.ru/3.2/c-api/unicode.html)). Для кодирования имён файлов при разборе аргументов следует использовать преобразователь `"O&"`, передавая [`PyUnicode_FSConverter()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_FSConverter) в качестве функции преобразования:230231#### `int PyUnicode_FSConverter(PyObject* obj, void* result)`232233Преобразователь ParseTuple: кодирует объекты [`str`](https://python-all.ru/3.2/library/functions.html#str) в [`bytes`](https://python-all.ru/3.2/library/functions.html#bytes) с помощью [`PyUnicode_EncodeFSDefault()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_EncodeFSDefault); объекты [`bytes`](https://python-all.ru/3.2/library/functions.html#bytes) передаются как есть. *result* должен быть [`PyBytesObject*`](https://python-all.ru/3.2/c-api/bytes.html#PyBytesObject), который нужно освободить, когда он больше не нужен.234235Новое в версии 3.1.236237Для декодирования имён файлов при разборе аргументов следует использовать преобразователь `"O&"`, передавая [`PyUnicode_FSDecoder()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_FSDecoder) в качестве функции преобразования:238239#### `int PyUnicode_FSDecoder(PyObject* obj, void* result)`240241Преобразователь ParseTuple: декодирует объекты [`bytes`](https://python-all.ru/3.2/library/functions.html#bytes) в [`str`](https://python-all.ru/3.2/library/functions.html#str) с помощью [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_DecodeFSDefaultAndSize); объекты [`str`](https://python-all.ru/3.2/library/functions.html#str) передаются как есть. *result* должен быть [`PyUnicodeObject*`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicodeObject), который нужно освободить, когда он больше не нужен.242243Новое в версии 3.2.244245#### `PyObject* PyUnicode_DecodeFSDefaultAndSize(const char *s, Py_ssize_t size)`246247Декодирует строку, используя `Py_FileSystemDefaultEncoding` и обработчик ошибок `'surrogateescape'`, или `'strict'` в Windows.248249Если `Py_FileSystemDefaultEncoding` не установлена, используется кодировка локали.250251Изменено в версии 3.2: Используется обработчик ошибок `'strict'` в Windows.252253#### `PyObject* PyUnicode_DecodeFSDefault(const char *s)`254255Декодирует строку, завершающуюся нулевым символом, используя `Py_FileSystemDefaultEncoding` и обработчик ошибок `'surrogateescape'`, или `'strict'` в Windows.256257Если `Py_FileSystemDefaultEncoding` не установлена, используется кодировка локали.258259Используйте [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_DecodeFSDefaultAndSize), если известна длина строки.260261Изменено в версии 3.2: Используется обработчик ошибок `'strict'` в Windows.262263#### `PyObject* PyUnicode_EncodeFSDefault(PyObject *unicode)`264265Кодирует объект Unicode в `Py_FileSystemDefaultEncoding` с обработчиком ошибок `'surrogateescape'`, или `'strict'` в Windows, и возвращает [`bytes`](https://python-all.ru/3.2/library/functions.html#bytes). Обратите внимание, что результирующий объект [`bytes`](https://python-all.ru/3.2/library/functions.html#bytes) может содержать нулевые байты.266267Если `Py_FileSystemDefaultEncoding` не установлена, используется кодировка локали.268269Новое в версии 3.2.270271### Поддержка wchar\_t272273Поддержка `wchar_t` на платформах, которые её поддерживают:274275#### `PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)`276277*Возвращаемое значение: новая ссылка.*278279Создаёт объект Unicode из буфера `wchar_t` *w* заданного размера *size*. Передача -1 в качестве *size* означает, что функция должна сама вычислить длину, используя wcslen. В случае ошибки возвращает *NULL*.280281#### `Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size)`282283Копирует содержимое объекта Unicode в буфер `wchar_t` *w*. Копируется не более *size* символов `wchar_t` (исключая возможный завершающий нулевой символ). Возвращает количество скопированных символов `wchar_t` или -1 в случае ошибки. Обратите внимание, что результирующая строка `wchar_t` может быть как завершена нулевым символом, так и нет. Вызывающий должен обеспечить, что строка `wchar_t` завершена нулевым символом, если это требуется приложением. Также обратите внимание, что строка `wchar_t*` может содержать нулевые символы, что приведёт к усечению строки при использовании с большинством функций C.284285#### `wchar_t* PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)`286287Преобразует объект Unicode в строку широких символов. Выходная строка всегда завершается нулевым символом. Если *size* не равно *NULL*, в *\*size* записывается количество широких символов (исключая завершающий нулевой символ).288289Возвращает буфер, выделенный функцией `PyMem_Alloc()` (для освобождения используйте [`PyMem_Free()`](https://python-all.ru/3.2/c-api/memory.html#PyMem_Free)) в случае успеха. При ошибке возвращает *NULL*, *\*size* не определён, и возбуждается исключение [`MemoryError`](https://python-all.ru/3.2/library/exceptions.html#MemoryError). Обратите внимание, что результирующая строка `wchar_t*` может содержать нулевые символы, что приведёт к усечению строки при использовании с большинством функций C.290291Новое в версии 3.2.292293## Встроенные кодеки294295Python предоставляет набор встроенных кодеков, написанных на C для скорости. Все эти кодеки могут использоваться напрямую через следующие функции.296297Многие из следующих API принимают два аргумента encoding и errors и имеют ту же семантику, что и одноимённые параметры конструктора встроенного строкового объекта [`str()`](https://python-all.ru/3.2/library/functions.html#str).298299Установка encoding в *NULL* приводит к использованию кодировки по умолчанию, которой является ASCII. Для кодирования имён файлов вызовы файловой системы должны использовать [`PyUnicode_FSConverter()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_FSConverter). Внутри используется переменная `Py_FileSystemDefaultEncoding`. Эту переменную следует считать доступной только для чтения: в одних системах это будет указатель на статическую строку, в других – она изменяется во время выполнения (например, когда приложение вызывает setlocale).300301Обработка ошибок задаётся параметром errors, который также может быть установлен в *NULL*, что означает использование обработки по умолчанию, определённой для кодера. Обработка ошибок по умолчанию для всех встроенных кодеров – «strict» (возбуждается [`ValueError`](https://python-all.ru/3.2/library/exceptions.html#ValueError)).302303Все кодеки используют похожий интерфейс. Для простоты документированы только отклонения от следующего общего описания.304305### Общие кодеки306307Это общие API кодеков:308309#### `PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)`310311*Возвращаемое значение: новая ссылка.*312313Создаёт объект Unicode, декодируя *size* байтов закодированной строки *s*. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры встроенной функции `unicode()`. Используемый кодек ищется в реестре кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.314315#### `PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)`316317*Возвращаемое значение: новая ссылка.*318319Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) *s* заданного размера *size* и возвращает объект Python bytes. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода `encode()` объекта Unicode. Используемый кодек ищется в реестре кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.320321#### `PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)`322323*Возвращаемое значение: новая ссылка.*324325Кодирует объект Unicode и возвращает результат в виде объекта Python bytes. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода `encode()` объекта Unicode. Используемый кодек ищется в реестре кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.326327### Кодеки UTF-8328329Это API кодеков UTF-8:330331#### `PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)`332333*Возвращаемое значение: новая ссылка.*334335Создаёт объект Unicode путём декодирования *size* байт строки, закодированной в UTF-8, *s*. Возвращает *NULL*, если кодек возбудил исключение.336337#### `PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`338339*Возвращаемое значение: новая ссылка.*340341Если *consumed* равно *NULL*, ведёт себя как [`PyUnicode_DecodeUTF8()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_DecodeUTF8). Если *consumed* не равно *NULL*, завершающие неполные последовательности байт UTF-8 не будут считаться ошибкой. Эти байты не будут декодированы, а количество декодированных байт будет сохранено в *consumed*.342343#### `PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`344345*Возвращаемое значение: новая ссылка.*346347Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) *s* заданного размера *size* с использованием UTF-8 и возвращает объект bytes Python. Возвращает *NULL*, если кодек возбудил исключение.348349#### `PyObject* PyUnicode_AsUTF8String(PyObject *unicode)`350351*Возвращаемое значение: новая ссылка.*352353Кодирует объект Unicode с использованием UTF-8 и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек возбудил исключение.354355### Кодеки UTF-32356357Это API кодеков UTF-32:358359#### `PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)`360361Декодирует *size* байт из строки буфера в кодировке UTF-32 и возвращает соответствующий объект Unicode. *errors* (если не *NULL*) определяет обработку ошибок. По умолчанию используется «strict».362363Если *byteorder* не равен *NULL*, декодер начинает декодирование с использованием заданного порядка байтов:364365```c366*byteorder == -1: little endian367*byteorder == 0:  native order368*byteorder == 1:  big endian369```370371Если `*byteorder` равен нулю, и первые четыре байта входных данных являются маркером порядка байт (BOM), декодер переключается на этот порядок байт, и BOM не копируется в результирующую строку Unicode. Если `*byteorder` равен `-1` или `1`, любой маркер порядка байт копируется в выходные данные.372373После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных.374375В сборке с узким представлением кодовые точки за пределами BMP будут декодироваться как суррогатные пары.376377Если *byteorder* равен *NULL*, кодек запускается в режиме собственного порядка байтов.378379Возвращает *NULL*, если кодек сгенерировал исключение.380381#### `PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)`382383Если *consumed* равен *NULL*, ведёт себя как [`PyUnicode_DecodeUTF32()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_DecodeUTF32). Если *consumed* не равен *NULL*, [`PyUnicode_DecodeUTF32Stateful()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_DecodeUTF32Stateful) не будет считать неполные конечные последовательности байтов UTF-32 (например, количество байтов, не кратное четырём) ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.384385#### `PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)`386387Возвращает объект Python bytes, содержащий значение Unicode-данных из *s*, закодированное в UTF-32. Вывод записывается в соответствии со следующим порядком байтов:388389```c390byteorder == -1: little endian391byteorder == 0:  native byte order (writes a BOM mark)392byteorder == 1:  big endian393```394395Если `0`, выходная строка всегда начинается с метки BOM Unicode (U+FEFF). В двух других режимах метка BOM не добавляется.396397Если *Py\_UNICODE\_WIDE* не определён, суррогатные пары будут выводиться как одна кодовая точка.398399Возвращает *NULL*, если кодек сгенерировал исключение.400401#### `PyObject* PyUnicode_AsUTF32String(PyObject *unicode)`402403Возвращает Python-строку байт в кодировке UTF-32 с собственным порядком байтов. Строка всегда начинается с маркера BOM. Обработка ошибок – «strict». Возвращает *NULL*, если кодек сгенерировал исключение.404405### Кодеки UTF-32406407Это API кодеков UTF-32:408409#### `PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)`410411*Возвращаемое значение: новая ссылка.*412413Декодирует *size* байт из строки буфера в кодировке UTF-16 и возвращает соответствующий объект Unicode. *errors* (если не *NULL*) определяет обработку ошибок. По умолчанию используется «strict».414415Если *byteorder* не равен *NULL*, декодер начинает декодирование с использованием заданного порядка байтов:416417```c418*byteorder == -1: little endian419*byteorder == 0:  native order420*byteorder == 1:  big endian421```422423Если `*byteorder` равен нулю и первые два байта входных данных являются меткой порядка байтов (BOM), декодер переключается на этот порядок байтов, и BOM не копируется в результирующую строку Unicode. Если `*byteorder` равен `-1` или `1`, любая метка порядка байтов копируется в выходные данные (в результате чего появится символ `\ufeff` или `\ufffe`).424425После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных.426427Если *byteorder* равен *NULL*, кодек запускается в режиме собственного порядка байтов.428429Возвращает *NULL*, если кодек сгенерировал исключение.430431#### `PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)`432433*Возвращаемое значение: новая ссылка.*434435Если *consumed* равен *NULL*, ведёт себя как [`PyUnicode_DecodeUTF16()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_DecodeUTF16). Если *consumed* не равен *NULL*, [`PyUnicode_DecodeUTF16Stateful()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_DecodeUTF16Stateful) не будет считать неполные конечные последовательности байтов UTF-16 (например, нечётное количество байтов или разбитая суррогатная пара) ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.436437#### `PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)`438439*Возвращаемое значение: новая ссылка.*440441Возвращает объект Python bytes, содержащий значение Unicode-данных из *s*, закодированное в UTF-16. Вывод записывается в соответствии со следующим порядком байтов:442443```c444byteorder == -1: little endian445byteorder == 0:  native byte order (writes a BOM mark)446byteorder == 1:  big endian447```448449Если `0`, выходная строка всегда начинается с метки BOM Unicode (U+FEFF). В двух других режимах метка BOM не добавляется.450451Если *Py\_UNICODE\_WIDE* определён, одно значение [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) может быть представлено как суррогатная пара. Если он не определён, каждое значение [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) интерпретируется как символ UCS-2.452453Возвращает *NULL*, если кодек сгенерировал исключение.454455#### `PyObject* PyUnicode_AsUTF16String(PyObject *unicode)`456457*Возвращаемое значение: новая ссылка.*458459Возвращает Python-строку байт в кодировке UTF-16 с собственным порядком байтов. Строка всегда начинается с маркера BOM. Обработка ошибок – «strict». Возвращает *NULL*, если кодек сгенерировал исключение.460461### Кодеки UTF-7462463Это API кодеков UTF-7:464465#### `PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)`466467Создаёт объект Unicode путём декодирования *size* байт строки в кодировке UTF-7 *s*. Возвращает *NULL*, если кодек сгенерировал исключение.468469#### `PyObject* PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`470471Если *consumed* равен *NULL*, ведёт себя как [`PyUnicode_DecodeUTF7()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_DecodeUTF7). Если *consumed* не равен *NULL*, конечные неполные секции base-64 UTF-7 не будут считаться ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.472473#### `PyObject* PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)`474475Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) заданного размера с использованием UTF-7 и возвращает объект Python bytes. Возвращает *NULL*, если кодек вызвал исключение.476477Если *base64SetO* не равно нулю, «Set O» (знаки препинания, не имеющие иного особого значения) будут закодированы в base-64. Если *base64WhiteSpace* не равно нулю, пробельные символы будут закодированы в base-64. Оба параметра установлены в ноль для кодека Python «utf-7».478479### Кодеки Unicode-Escape480481Это API кодеков «Unicode Escape»:482483#### `PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)`484485*Возвращаемое значение: новая ссылка.*486487Создаёт объект Unicode путём декодирования *size* байт строки в кодировке Unicode-Escape *s*. Возвращает *NULL*, если кодек сгенерировал исключение.488489#### `PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)`490491*Возвращаемое значение: новая ссылка.*492493Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) заданного размера *size* с использованием Unicode-Escape и возвращает строковый объект Python. Возвращает *NULL*, если кодек вызвал исключение.494495#### `PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)`496497*Возвращаемое значение: новая ссылка.*498499Кодирует объект Unicode с использованием Unicode-Escape и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.500501### Кодеки Raw-Unicode-Escape502503Это API кодеков «Raw Unicode Escape»:504505#### `PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)`506507*Возвращаемое значение: новая ссылка.*508509Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в Raw-Unicode-Escape. Возвращает *NULL*, если кодек вызвал исключение.510511#### `PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`512513*Возвращаемое значение: новая ссылка.*514515Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) заданного размера *size* с использованием Raw-Unicode-Escape и возвращает строковый объект Python. Возвращает *NULL*, если кодек вызвал исключение.516517#### `PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)`518519*Возвращаемое значение: новая ссылка.*520521Кодирует объект Unicode с использованием Raw-Unicode-Escape и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.522523### Кодеки Latin-1524525Это API кодеков Latin-1: Latin-1 соответствует первым 256 кодовым позициям Unicode, и только они принимаются кодеками при кодировании.526527#### `PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)`528529*Возвращаемое значение: новая ссылка.*530531Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в Latin-1. Возвращает *NULL*, если кодек вызвал исключение.532533#### `PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`534535*Возвращаемое значение: новая ссылка.*536537Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) заданного размера *size* с помощью Latin-1 и возвращает объект bytes Python. Возвращает *NULL*, если кодек вызвал исключение.538539#### `PyObject* PyUnicode_AsLatin1String(PyObject *unicode)`540541*Возвращаемое значение: новая ссылка.*542543Кодирует объект Unicode с помощью Latin-1 и возвращает результат как объект bytes Python. Обработка ошибок – “strict”. Возвращает *NULL*, если кодек вызвал исключение.544545### Кодеки ASCII546547Это API кодеков ASCII. Принимаются только 7-битные данные ASCII. Все остальные коды вызывают ошибки.548549#### `PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)`550551*Возвращаемое значение: новая ссылка.*552553Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в ASCII. Возвращает *NULL*, если кодек вызвал исключение.554555#### `PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`556557*Возвращаемое значение: новая ссылка.*558559Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) заданного размера *size* с помощью ASCII и возвращает объект bytes Python. Возвращает *NULL*, если кодек вызвал исключение.560561#### `PyObject* PyUnicode_AsASCIIString(PyObject *unicode)`562563*Возвращаемое значение: новая ссылка.*564565Кодирует объект Unicode с помощью ASCII и возвращает результат как объект bytes Python. Обработка ошибок – “strict”. Возвращает *NULL*, если кодек вызвал исключение.566567### Кодеки с таблицей символов568569Этот кодек особенный, так как его можно использовать для реализации множества разных кодеков (именно так и были получены большинство стандартных кодеков, входящих в пакет `encodings`). Кодек использует отображение для кодирования и декодирования символов.570571Отображения для декодирования должны сопоставлять отдельные строковые символы отдельным символам Unicode, целым числам (которые затем интерпретируются как кодовые точки Unicode) или None (что означает «неопределённое отображение» и вызывает ошибку).572573Отображения для кодирования должны сопоставлять отдельные символы Unicode отдельным строковым символам, целым числам (которые затем интерпретируются как кодовые точки Latin-1) или None (что означает «неопределённое отображение» и вызывает ошибку).574575Объекты отображения должны поддерживать только интерфейс отображения \_\_getitem\_\_.576577Если при поиске символа возникает LookupError, символ копируется как есть; это означает, что его порядковое значение будет интерпретироваться как кодовая точка Unicode или Latin-1 соответственно. Из-за этого отображения должны содержать только те соответствия, которые переводят символы в другие кодовые точки.578579Это API кодеков отображения:580581#### `PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors)`582583*Возвращаемое значение: новая ссылка.*584585Создаёт объект Unicode, декодируя *size* байт закодированной строки *s* с помощью заданного объекта *mapping*. Возвращает *NULL*, если кодек вызвал исключение. Если *mapping* равен *NULL*, выполняется декодирование Latin-1. В противном случае это может быть словарь, отображающий байты, или строка Unicode, которая интерпретируется как таблица поиска. Значения байтов, превышающие длину строки, и «символ» U+FFFE считаются «неопределённым отображением».586587#### `PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)`588589*Возвращаемое значение: новая ссылка.*590591Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) заданного размера *size* с помощью заданного объекта *mapping* и возвращает строковый объект Python. Возвращает *NULL*, если кодек вызвал исключение.592593#### `PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)`594595*Возвращаемое значение: новая ссылка.*596597Кодирует объект Unicode с помощью заданного объекта *mapping* и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.598599Следующее API кодека особенное тем, что отображает Unicode в Unicode.600601#### `PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *table, const char *errors)`602603*Возвращаемое значение: новая ссылка.*604605Переводит буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) заданного размера *size*, применяя к нему символьное отображение *table*, и возвращает результирующий объект Unicode. Возвращает *NULL*, если кодек вызвал исключение.606607Таблица *mapping* должна сопоставлять целочисленные кодовые точки Unicode целочисленным кодовым точкам Unicode или None (что приводит к удалению символа).608609Таблицам отображения достаточно реализовать интерфейс [`__getitem__()`](https://python-all.ru/3.2/reference/datamodel.html#object.__getitem__); словари и последовательности подходят. Неотображённые коды символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.2/library/exceptions.html#LookupError)) остаются без изменений и копируются как есть.610611### Кодеки MBCS для Windows612613Это API кодеков MBCS. В настоящее время они доступны только в Windows и используют преобразователи Win32 MBCS для выполнения преобразований. Обратите внимание, что MBCS (или DBCS) – это класс кодировок, а не одна конкретная. Целевая кодировка определяется пользовательскими настройками на машине, где выполняется кодек.614615#### `PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)`616617*Возвращаемое значение: новая ссылка.*618619Создаёт объект Unicode, декодируя *size* байтов строки, закодированной в MBCS, из *s*. Возвращает *NULL*, если кодек вызвал исключение.620621#### `PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed)`622623Если *consumed* равен *NULL*, ведёт себя как [`PyUnicode_DecodeMBCS()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_DecodeMBCS). Если *consumed* не равен *NULL*, то [`PyUnicode_DecodeMBCSStateful()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_DecodeMBCSStateful) не будет декодировать конечный ведущий байт, а количество декодированных байтов будет сохранено в *consumed*.624625#### `PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`626627*Возвращаемое значение: новая ссылка.*628629Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) заданного размера *size* с помощью MBCS и возвращает объект bytes Python. Возвращает *NULL*, если кодек возбудил исключение.630631#### `PyObject* PyUnicode_AsMBCSString(PyObject *unicode)`632633*Возвращаемое значение: новая ссылка.*634635Кодирует объект Unicode с помощью MBCS и возвращает результат в виде объекта bytes Python. Обработка ошибок – "strict". Возвращает *NULL*, если кодек вызвал исключение.636637### Методы и слоты638639## Методы и слот-функции640641Следующие API могут обрабатывать объекты Unicode и строки на входе (в описаниях мы называем их строками) и возвращают объекты Unicode или целые числа по необходимости.642643Все они возвращают *NULL* или `-1` в случае исключения.644645#### `PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)`646647*Возвращаемое значение: новая ссылка.*648649Объединяет две строки, возвращая новую строку Unicode.650651#### `PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)`652653*Возвращаемое значение: новая ссылка.*654655Разделяет строку и возвращает список строк Unicode. Если *sep* равен *NULL*, разделение происходит по всем подстрокам из пробельных символов. В противном случае разделение выполняется по указанному разделителю. Выполняется не более *maxsplit* разделений. Если значение отрицательное, ограничение не устанавливается. Разделители не включаются в результирующий список.656657#### `PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)`658659*Возвращаемое значение: новая ссылка.*660661Разделяет строку Unicode по символам перевода строки и возвращает список строк Unicode. CRLF считается одним переносом строки. Если *keepend* равен 0, символы перевода строки не включаются в результирующие строки.662663#### `PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)`664665*Возвращаемое значение: новая ссылка.*666667Переводит строку, применяя к ней таблицу отображения символов, и возвращает результирующий объект Unicode.668669Таблица отображения должна сопоставлять целочисленные коды Unicode другим целочисленным кодам Unicode или None (что приводит к удалению символа).670671Таблицам отображения достаточно реализовать интерфейс [`__getitem__()`](https://python-all.ru/3.2/reference/datamodel.html#object.__getitem__); словари и последовательности подходят. Неотображённые коды символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.2/library/exceptions.html#LookupError)) остаются без изменений и копируются как есть.672673*errors* имеет обычное для кодеков значение. Может быть *NULL*, что означает использование обработки ошибок по умолчанию.674675#### `PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)`676677*Возвращаемое значение: новая ссылка.*678679Объединяет последовательность строк, используя заданный *разделитель*, и возвращает полученную Unicode-строку.680681#### `int PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)`682683Возвращает 1, если *substr* совпадает с `str[start:end]` на указанном конце (*direction* == -1 означает поиск по префиксу, *direction* == 1 – поиск по суффиксу), и 0 в противном случае. Возвращает `-1`, если произошла ошибка.684685#### `Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)`686687Возвращает первую позицию *substr* в `str[start:end]`, используя заданное *direction* (*direction* == 1 означает прямой поиск, *direction* == -1 – обратный). Возвращаемое значение – индекс первого совпадения; значение `-1` означает, что совпадений не найдено, а `-2` – что произошла ошибка и было установлено исключение.688689#### `Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)`690691Возвращает количество непересекающихся вхождений *substr* в `str[start:end]`. Возвращает `-1`, если произошла ошибка.692693#### `PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)`694695*Возвращаемое значение: новая ссылка.*696697Заменяет не более *maxcount* вхождений *substr* в *str* на *replstr* и возвращает результирующий объект Unicode. *maxcount* == -1 означает замену всех вхождений.698699#### `int PyUnicode_Compare(PyObject *left, PyObject *right)`700701Сравнивает две строки и возвращает -1, 0, 1 для случаев «меньше», «равно» и «больше» соответственно.702703#### `int PyUnicode_CompareWithASCIIString(PyObject *uni, char *string)`704705Сравнивает объект Unicode *uni* со строкой *string* и возвращает -1, 0, 1 для случаев меньше, равно и больше соответственно. Рекомендуется передавать только строки в кодировке ASCII, но если строка содержит не-ASCII символы, функция интерпретирует её как ISO-8859-1.706707#### `int PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)`708709Выполняет расширенное сравнение двух строк unicode и возвращает одно из следующих значений:710711- `NULL` в случае возбуждения исключения712- `Py_True` или `Py_False` при успешном сравнении713- `Py_NotImplemented` в случае, если комбинация типов неизвестна714715Обратите внимание, что сравнения с `Py_EQ` и `Py_NE` могут вызвать [`UnicodeWarning`](https://python-all.ru/3.2/library/exceptions.html#UnicodeWarning), если преобразование аргументов в Unicode завершится ошибкой с [`UnicodeDecodeError`](https://python-all.ru/3.2/library/exceptions.html#UnicodeDecodeError).716717Возможные значения для *op*: `Py_GT`, `Py_GE`, `Py_EQ`, `Py_NE`, `Py_LT` и `Py_LE`.718719#### `PyObject* PyUnicode_Format(PyObject *format, PyObject *args)`720721*Возвращаемое значение: новая ссылка.*722723Возвращает новый строковый объект из *format* и *args*; это аналогично `format % args`. Аргумент *args* должен быть кортежем.724725#### `int PyUnicode_Contains(PyObject *container, PyObject *element)`726727Проверяет, содержится ли *element* в *container*, и возвращает true или false соответственно.728729*element* должен преобразовываться в односимвольную строку Unicode. Если произошла ошибка, возвращается `-1`.730731#### `void PyUnicode_InternInPlace(PyObject **string)`732733Интернирует аргумент *\*string* на месте. Аргумент должен быть адресом переменной-указателя, указывающей на объект строки Unicode Python. Если уже существует интернированная строка, совпадающая с *\*string*, то она устанавливает *\*string* на эту строку (уменьшая счётчик ссылок старого строкового объекта и увеличивая счётчик интернированной строки); в противном случае она оставляет *\*string* без изменений и интернирует её (увеличивая её счётчик ссылок). (Уточнение: хотя много говорится о счётчиках ссылок, считайте эту функцию нейтральной к счётчикам ссылок – вы владеете объектом после вызова, только если владели им до вызова.)734735#### `PyObject* PyUnicode_InternFromString(const char *v)`736737Комбинация [`PyUnicode_FromString()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_FromString) и [`PyUnicode_InternInPlace()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_InternInPlace), возвращающая либо новый объект строки Unicode, который был интернирован, либо новую («владетельную») ссылку на ранее интернированный строковый объект с тем же значением.738