> **Источник:** https://python-all.ru/3.2/c-api/unicode.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# Объекты Unicode и кодеки

## Объекты Unicode

### Тип Unicode

Это основные типы объектов Unicode, используемые в реализации Unicode в Python:

**`Py_UNICODE`**

Этот тип представляет тип хранения, который используется внутри 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).

Обратите внимание, что сборки Python с UCS2 и UCS4 не являются двоично совместимыми. Учитывайте это при написании расширений или интерфейсов.

**`PyUnicodeObject`**

Этот подтип [`PyObject`](https://python-all.ru/3.2/c-api/structures.html#PyObject) представляет объект Unicode в Python.

**[PyTypeObject](https://python-all.ru/3.2/c-api/type.html#PyTypeObject) `PyUnicode_Type`**

Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.2/c-api/type.html#PyTypeObject) представляет тип Unicode в Python. Он доступен в коде Python как `str`.

Следующие API на самом деле являются макросами C и могут использоваться для быстрых проверок и доступа к внутренним данным Unicode объектов только для чтения:

#### `int PyUnicode_Check(PyObject *o)`

Возвращает true, если объект *o* является объектом Unicode или экземпляром подтипа Unicode.

#### `int PyUnicode_CheckExact(PyObject *o)`

Возвращает true, если объект *o* является объектом Unicode, но не экземпляром подтипа.

#### `Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)`

Возвращает размер объекта. *o* должен быть [`PyUnicodeObject`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicodeObject) (не проверяется).

#### `Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)`

Возвращает размер внутреннего буфера объекта в байтах. *o* должен быть [`PyUnicodeObject`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicodeObject) (не проверяется).

#### `Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)`

Возвращает указатель на внутренний буфер [`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) (не проверяется).

#### `const char* PyUnicode_AS_DATA(PyObject *o)`

Возвращает указатель на внутренний буфер объекта. *o* должен быть [`PyUnicodeObject`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicodeObject) (не проверяется).

#### `int PyUnicode_ClearFreeList()`

Очищает список свободных элементов. Возвращает общее количество освобождённых элементов.

### Свойства символов Unicode

Unicode предоставляет множество различных свойств символов. Наиболее востребованные из них доступны через следующие макросы, которые сопоставляются с функциями на C в зависимости от конфигурации Python.

#### `int Py_UNICODE_ISSPACE(Py_UNICODE ch)`

Возвращает 1 или 0 в зависимости от того, является ли *ch* пробельным символом.

#### `int Py_UNICODE_ISLOWER(Py_UNICODE ch)`

Возвращает 1 или 0 в зависимости от того, является ли *ch* символом нижнего регистра.

#### `int Py_UNICODE_ISUPPER(Py_UNICODE ch)`

Возвращает 1 или 0 в зависимости от того, является ли *ch* символом верхнего регистра.

#### `int Py_UNICODE_ISTITLE(Py_UNICODE ch)`

Возвращает 1 или 0 в зависимости от того, является ли *ch* символом в регистре заголовка.

#### `int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)`

Возвращает 1 или 0 в зависимости от того, является ли *ch* символом разрыва строки.

#### `int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)`

Возвращает 1 или 0 в зависимости от того, является ли *ch* десятичной цифрой.

#### `int Py_UNICODE_ISDIGIT(Py_UNICODE ch)`

Возвращает 1 или 0 в зависимости от того, является ли *ch* цифровым символом.

#### `int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)`

Возвращает 1 или 0 в зависимости от того, является ли *ch* числовым символом.

#### `int Py_UNICODE_ISALPHA(Py_UNICODE ch)`

Возвращает 1 или 0 в зависимости от того, является ли *ch* буквенным символом.

#### `int Py_UNICODE_ISALNUM(Py_UNICODE ch)`

Возвращает 1 или 0 в зависимости от того, является ли *ch* буквенно-цифровым символом.

#### `int Py_UNICODE_ISPRINTABLE(Py_UNICODE ch)`

Возвращает 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).)

Эти API можно использовать для быстрых прямых преобразований символов:

#### `Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)`

Возвращает символ *ch*, преобразованный в нижний регистр.

#### `Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)`

Возвращает символ *ch*, преобразованный в верхний регистр.

#### `Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)`

Возвращает символ *ch*, приведённый к регистру заголовка.

#### `int Py_UNICODE_TODECIMAL(Py_UNICODE ch)`

Возвращает символ *ch*, преобразованный в десятичное положительное целое. Возвращает `-1`, если это невозможно. Этот макрос не вызывает исключений.

#### `int Py_UNICODE_TODIGIT(Py_UNICODE ch)`

Возвращает символ *ch*, преобразованный в целое однозначное число. Возвращает `-1`, если это невозможно. Этот макрос не вызывает исключений.

#### `double Py_UNICODE_TONUMERIC(Py_UNICODE ch)`

Возвращает символ *ch*, преобразованный в double. Возвращает `-1.0`, если это невозможно. Этот макрос не вызывает исключений.

### Простой Py\_UNICODE

Для создания объектов Unicode и доступа к их базовым свойствам последовательности используйте следующие API:

#### `PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)`

*Возвращаемое значение: новая ссылка.*

Создаёт объект Unicode из буфера Py\_UNICODE *u* указанного размера. *u* может быть *NULL*, что делает содержимое неопределённым. Ответственность за заполнение нужными данными лежит на пользователе. Буфер копируется в новый объект. Если буфер не равен *NULL*, возвращаемое значение может быть разделяемым объектом. Поэтому изменение результирующего объекта Unicode допускается только когда *u* равно *NULL*.

#### `PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)`

Создаёт объект Unicode из буфера char *u*. Байты интерпретируются как кодировка UTF-8. *u* также может быть *NULL*, что делает содержимое неопределённым. Ответственность за заполнение нужными данными лежит на пользователе. Буфер копируется в новый объект. Если буфер не равен *NULL*, возвращаемое значение может быть разделяемым объектом. Поэтому изменение результирующего объекта Unicode допускается только когда *u* равно *NULL*.

#### `PyObject *PyUnicode_FromString(const char *u)`

Создаёт объект Unicode из UTF-8-кодированного символьного буфера с завершающим нулём *u*.

#### `PyObject* PyUnicode_FromFormat(const char *format, ...)`

Принимает строку *format* в стиле C `printf()` и переменное количество аргументов, вычисляет размер результирующей Python-строки Unicode и возвращает строку с отформатированными значениями. Переменные аргументы должны быть типами C и должны точно соответствовать символам формата в строке *format*, закодированной в ASCII. Допускаются следующие символы формата:

| Символы формата | Тип | Описание |
| --- | --- | --- |
| `%%` | *н/д* | Буквальный символ %. |
| `%c` | int | Одиночный символ, представленный как C int. |
| `%d` | int | Полностью эквивалентно `printf("%d")`. |
| `%u` | беззнаковый int | Полностью эквивалентно `printf("%u")`. |
| `%ld` | long | Полностью эквивалентно `printf("%ld")`. |
| `%lu` | беззнаковый long | Полностью эквивалентно `printf("%lu")`. |
| `%lld` | long long | Полностью эквивалентно `printf("%lld")`. |
| `%llu` | беззнаковый long long | Полностью эквивалентно `printf("%llu")`. |
| `%zd` | Py\_ssize\_t | Полностью эквивалентно `printf("%zd")`. |
| `%zu` | size\_t | Полностью эквивалентно `printf("%zu")`. |
| `%i` | int | Полностью эквивалентно `printf("%i")`. |
| `%x` | int | Полностью эквивалентно `printf("%x")`. |
| `%s` | char\* | Нуль-терминированный массив символов C. |
| `%p` | void\* | Шестнадцатеричное представление указателя C. В основном эквивалентно `printf("%p")` за исключением того, что гарантированно начинается с литерала `0x` независимо от того, что выдает `printf` на данной платформе. |
| `%A` | PyObject\* | Результат вызова [`ascii()`](https://python-all.ru/3.2/library/functions.html#ascii). |
| `%U` | PyObject\* | Unicode-объект. |
| `%V` | PyObject\*, char \* | Unicode-объект (может быть *NULL*) и завершающийся нулевым символом C-массив символов в качестве второго параметра (используется, если первый параметр равен *NULL*). |
| `%S` | PyObject\* | Результат вызова [`PyObject_Str()`](https://python-all.ru/3.2/c-api/object.html#PyObject_Str). |
| `%R` | PyObject\* | Результат вызова [`PyObject_Repr()`](https://python-all.ru/3.2/c-api/object.html#PyObject_Repr). |

Нераспознанный символ формата приводит к тому, что вся оставшаяся строка формата копируется как есть в результирующую строку, а все лишние аргументы отбрасываются.

> **Примечание**
>
> Спецификаторы формата *"%lld"* и *"%llu"* доступны только при определённом `HAVE_LONG_LONG`.

Изменено в версии 3.2: Добавлена поддержка `"%lld"` и `"%llu"`.

#### `PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)`

Идентична [`PyUnicode_FromFormat()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_FromFormat), за исключением того, что принимает ровно два аргумента.

#### `PyObject* PyUnicode_TransformDecimalToASCII(Py_UNICODE *s, Py_ssize_t size)`

Создаёт объект Unicode, заменяя все десятичные цифры в буфере [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) заданного размера *size* на ASCII-цифры 0–9 в соответствии с их десятичным значением. Возвращает *NULL* в случае возникновения исключения.

#### `Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)`

Возвращает указатель только для чтения на внутренний буфер [`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.

#### `Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode)`

Создаёт копию строки 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.

Новое в версии 3.2.

#### `Py_ssize_t PyUnicode_GetSize(PyObject *unicode)`

Возвращает длину объекта Unicode.

#### `PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)`

*Возвращаемое значение: новая ссылка.*

Преобразует закодированный объект *obj* в объект Unicode и возвращает ссылку с увеличенным счётчиком ссылок.

[`bytes`](https://python-all.ru/3.2/library/functions.html#bytes), [`bytearray`](https://python-all.ru/3.2/library/functions.html#bytearray) и другие объекты, совместимые с символьным буфером, декодируются согласно заданной *кодировке* с использованием обработки ошибок, определенной *errors*. Оба параметра могут быть *NULL*, чтобы интерфейс использовал значения по умолчанию (подробнее см. в следующем разделе).

Все остальные объекты, включая объекты Unicode, вызывают установку [`TypeError`](https://python-all.ru/3.2/library/exceptions.html#TypeError).

API возвращает *NULL* при ошибке. Вызывающий отвечает за уменьшение счётчика ссылок возвращённых объектов.

#### `PyObject* PyUnicode_FromObject(PyObject *obj)`

*Возвращаемое значение: новая ссылка.*

Shortcut for `PyUnicode_FromEncodedObject(obj, NULL, "strict")` which is used throughout the interpreter whenever coercion to Unicode is needed.

Если платформа поддерживает `wchar_t` и предоставляет заголовочный файл wchar.h, Python может напрямую взаимодействовать с этим типом с помощью следующих функций. Поддержка оптимизируется, если собственный тип [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) Python идентичен системному `wchar_t`.

### Кодировка файловой системы

Для кодирования и декодирования имён файлов и других строк окружения в качестве кодировки следует использовать `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) в качестве функции преобразования:

#### `int PyUnicode_FSConverter(PyObject* obj, void* result)`

Преобразователь 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), который нужно освободить, когда он больше не нужен.

Новое в версии 3.1.

Для декодирования имён файлов при разборе аргументов следует использовать преобразователь `"O&"`, передавая [`PyUnicode_FSDecoder()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_FSDecoder) в качестве функции преобразования:

#### `int PyUnicode_FSDecoder(PyObject* obj, void* result)`

Преобразователь 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), который нужно освободить, когда он больше не нужен.

Новое в версии 3.2.

#### `PyObject* PyUnicode_DecodeFSDefaultAndSize(const char *s, Py_ssize_t size)`

Декодирует строку, используя `Py_FileSystemDefaultEncoding` и обработчик ошибок `'surrogateescape'`, или `'strict'` в Windows.

Если `Py_FileSystemDefaultEncoding` не установлена, используется кодировка локали.

Изменено в версии 3.2: Используется обработчик ошибок `'strict'` в Windows.

#### `PyObject* PyUnicode_DecodeFSDefault(const char *s)`

Декодирует строку, завершающуюся нулевым символом, используя `Py_FileSystemDefaultEncoding` и обработчик ошибок `'surrogateescape'`, или `'strict'` в Windows.

Если `Py_FileSystemDefaultEncoding` не установлена, используется кодировка локали.

Используйте [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_DecodeFSDefaultAndSize), если известна длина строки.

Изменено в версии 3.2: Используется обработчик ошибок `'strict'` в Windows.

#### `PyObject* PyUnicode_EncodeFSDefault(PyObject *unicode)`

Кодирует объект 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) может содержать нулевые байты.

Если `Py_FileSystemDefaultEncoding` не установлена, используется кодировка локали.

Новое в версии 3.2.

### Поддержка wchar\_t

Поддержка `wchar_t` на платформах, которые её поддерживают:

#### `PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)`

*Возвращаемое значение: новая ссылка.*

Создаёт объект Unicode из буфера `wchar_t` *w* заданного размера *size*. Передача -1 в качестве *size* означает, что функция должна сама вычислить длину, используя wcslen. В случае ошибки возвращает *NULL*.

#### `Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size)`

Копирует содержимое объекта Unicode в буфер `wchar_t` *w*. Копируется не более *size* символов `wchar_t` (исключая возможный завершающий нулевой символ). Возвращает количество скопированных символов `wchar_t` или -1 в случае ошибки. Обратите внимание, что результирующая строка `wchar_t` может быть как завершена нулевым символом, так и нет. Вызывающий должен обеспечить, что строка `wchar_t` завершена нулевым символом, если это требуется приложением. Также обратите внимание, что строка `wchar_t*` может содержать нулевые символы, что приведёт к усечению строки при использовании с большинством функций C.

#### `wchar_t* PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)`

Преобразует объект Unicode в строку широких символов. Выходная строка всегда завершается нулевым символом. Если *size* не равно *NULL*, в *\*size* записывается количество широких символов (исключая завершающий нулевой символ).

Возвращает буфер, выделенный функцией `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.

Новое в версии 3.2.

## Встроенные кодеки

Python предоставляет набор встроенных кодеков, написанных на C для скорости. Все эти кодеки могут использоваться напрямую через следующие функции.

Многие из следующих API принимают два аргумента encoding и errors и имеют ту же семантику, что и одноимённые параметры конструктора встроенного строкового объекта [`str()`](https://python-all.ru/3.2/library/functions.html#str).

Установка encoding в *NULL* приводит к использованию кодировки по умолчанию, которой является ASCII. Для кодирования имён файлов вызовы файловой системы должны использовать [`PyUnicode_FSConverter()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_FSConverter). Внутри используется переменная `Py_FileSystemDefaultEncoding`. Эту переменную следует считать доступной только для чтения: в одних системах это будет указатель на статическую строку, в других – она изменяется во время выполнения (например, когда приложение вызывает setlocale).

Обработка ошибок задаётся параметром errors, который также может быть установлен в *NULL*, что означает использование обработки по умолчанию, определённой для кодера. Обработка ошибок по умолчанию для всех встроенных кодеров – «strict» (возбуждается [`ValueError`](https://python-all.ru/3.2/library/exceptions.html#ValueError)).

Все кодеки используют похожий интерфейс. Для простоты документированы только отклонения от следующего общего описания.

### Общие кодеки

Это общие API кодеков:

#### `PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)`

*Возвращаемое значение: новая ссылка.*

Создаёт объект Unicode, декодируя *size* байтов закодированной строки *s*. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры встроенной функции `unicode()`. Используемый кодек ищется в реестре кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.

#### `PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)`

*Возвращаемое значение: новая ссылка.*

Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) *s* заданного размера *size* и возвращает объект Python bytes. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода `encode()` объекта Unicode. Используемый кодек ищется в реестре кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.

#### `PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)`

*Возвращаемое значение: новая ссылка.*

Кодирует объект Unicode и возвращает результат в виде объекта Python bytes. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода `encode()` объекта Unicode. Используемый кодек ищется в реестре кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.

### Кодеки UTF-8

Это API кодеков UTF-8:

#### `PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)`

*Возвращаемое значение: новая ссылка.*

Создаёт объект Unicode путём декодирования *size* байт строки, закодированной в UTF-8, *s*. Возвращает *NULL*, если кодек возбудил исключение.

#### `PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`

*Возвращаемое значение: новая ссылка.*

Если *consumed* равно *NULL*, ведёт себя как [`PyUnicode_DecodeUTF8()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_DecodeUTF8). Если *consumed* не равно *NULL*, завершающие неполные последовательности байт UTF-8 не будут считаться ошибкой. Эти байты не будут декодированы, а количество декодированных байт будет сохранено в *consumed*.

#### `PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`

*Возвращаемое значение: новая ссылка.*

Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) *s* заданного размера *size* с использованием UTF-8 и возвращает объект bytes Python. Возвращает *NULL*, если кодек возбудил исключение.

#### `PyObject* PyUnicode_AsUTF8String(PyObject *unicode)`

*Возвращаемое значение: новая ссылка.*

Кодирует объект Unicode с использованием UTF-8 и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек возбудил исключение.

### Кодеки UTF-32

Это API кодеков UTF-32:

#### `PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)`

Декодирует *size* байт из строки буфера в кодировке UTF-32 и возвращает соответствующий объект Unicode. *errors* (если не *NULL*) определяет обработку ошибок. По умолчанию используется «strict».

Если *byteorder* не равен *NULL*, декодер начинает декодирование с использованием заданного порядка байтов:

```c
*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian
```

Если `*byteorder` равен нулю, и первые четыре байта входных данных являются маркером порядка байт (BOM), декодер переключается на этот порядок байт, и BOM не копируется в результирующую строку Unicode. Если `*byteorder` равен `-1` или `1`, любой маркер порядка байт копируется в выходные данные.

После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных.

В сборке с узким представлением кодовые точки за пределами BMP будут декодироваться как суррогатные пары.

Если *byteorder* равен *NULL*, кодек запускается в режиме собственного порядка байтов.

Возвращает *NULL*, если кодек сгенерировал исключение.

#### `PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)`

Если *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*.

#### `PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)`

Возвращает объект Python bytes, содержащий значение Unicode-данных из *s*, закодированное в UTF-32. Вывод записывается в соответствии со следующим порядком байтов:

```c
byteorder == -1: little endian
byteorder == 0:  native byte order (writes a BOM mark)
byteorder == 1:  big endian
```

Если `0`, выходная строка всегда начинается с метки BOM Unicode (U+FEFF). В двух других режимах метка BOM не добавляется.

Если *Py\_UNICODE\_WIDE* не определён, суррогатные пары будут выводиться как одна кодовая точка.

Возвращает *NULL*, если кодек сгенерировал исключение.

#### `PyObject* PyUnicode_AsUTF32String(PyObject *unicode)`

Возвращает Python-строку байт в кодировке UTF-32 с собственным порядком байтов. Строка всегда начинается с маркера BOM. Обработка ошибок – «strict». Возвращает *NULL*, если кодек сгенерировал исключение.

### Кодеки UTF-32

Это API кодеков UTF-32:

#### `PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)`

*Возвращаемое значение: новая ссылка.*

Декодирует *size* байт из строки буфера в кодировке UTF-16 и возвращает соответствующий объект Unicode. *errors* (если не *NULL*) определяет обработку ошибок. По умолчанию используется «strict».

Если *byteorder* не равен *NULL*, декодер начинает декодирование с использованием заданного порядка байтов:

```c
*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian
```

Если `*byteorder` равен нулю и первые два байта входных данных являются меткой порядка байтов (BOM), декодер переключается на этот порядок байтов, и BOM не копируется в результирующую строку Unicode. Если `*byteorder` равен `-1` или `1`, любая метка порядка байтов копируется в выходные данные (в результате чего появится символ `\ufeff` или `\ufffe`).

После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных.

Если *byteorder* равен *NULL*, кодек запускается в режиме собственного порядка байтов.

Возвращает *NULL*, если кодек сгенерировал исключение.

#### `PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)`

*Возвращаемое значение: новая ссылка.*

Если *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*.

#### `PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)`

*Возвращаемое значение: новая ссылка.*

Возвращает объект Python bytes, содержащий значение Unicode-данных из *s*, закодированное в UTF-16. Вывод записывается в соответствии со следующим порядком байтов:

```c
byteorder == -1: little endian
byteorder == 0:  native byte order (writes a BOM mark)
byteorder == 1:  big endian
```

Если `0`, выходная строка всегда начинается с метки BOM Unicode (U+FEFF). В двух других режимах метка BOM не добавляется.

Если *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.

Возвращает *NULL*, если кодек сгенерировал исключение.

#### `PyObject* PyUnicode_AsUTF16String(PyObject *unicode)`

*Возвращаемое значение: новая ссылка.*

Возвращает Python-строку байт в кодировке UTF-16 с собственным порядком байтов. Строка всегда начинается с маркера BOM. Обработка ошибок – «strict». Возвращает *NULL*, если кодек сгенерировал исключение.

### Кодеки UTF-7

Это API кодеков UTF-7:

#### `PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)`

Создаёт объект Unicode путём декодирования *size* байт строки в кодировке UTF-7 *s*. Возвращает *NULL*, если кодек сгенерировал исключение.

#### `PyObject* PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`

Если *consumed* равен *NULL*, ведёт себя как [`PyUnicode_DecodeUTF7()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_DecodeUTF7). Если *consumed* не равен *NULL*, конечные неполные секции base-64 UTF-7 не будут считаться ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.

#### `PyObject* PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)`

Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) заданного размера с использованием UTF-7 и возвращает объект Python bytes. Возвращает *NULL*, если кодек вызвал исключение.

Если *base64SetO* не равно нулю, «Set O» (знаки препинания, не имеющие иного особого значения) будут закодированы в base-64. Если *base64WhiteSpace* не равно нулю, пробельные символы будут закодированы в base-64. Оба параметра установлены в ноль для кодека Python «utf-7».

### Кодеки Unicode-Escape

Это API кодеков «Unicode Escape»:

#### `PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)`

*Возвращаемое значение: новая ссылка.*

Создаёт объект Unicode путём декодирования *size* байт строки в кодировке Unicode-Escape *s*. Возвращает *NULL*, если кодек сгенерировал исключение.

#### `PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)`

*Возвращаемое значение: новая ссылка.*

Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) заданного размера *size* с использованием Unicode-Escape и возвращает строковый объект Python. Возвращает *NULL*, если кодек вызвал исключение.

#### `PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)`

*Возвращаемое значение: новая ссылка.*

Кодирует объект Unicode с использованием Unicode-Escape и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.

### Кодеки Raw-Unicode-Escape

Это API кодеков «Raw Unicode Escape»:

#### `PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)`

*Возвращаемое значение: новая ссылка.*

Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в Raw-Unicode-Escape. Возвращает *NULL*, если кодек вызвал исключение.

#### `PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`

*Возвращаемое значение: новая ссылка.*

Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) заданного размера *size* с использованием Raw-Unicode-Escape и возвращает строковый объект Python. Возвращает *NULL*, если кодек вызвал исключение.

#### `PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)`

*Возвращаемое значение: новая ссылка.*

Кодирует объект Unicode с использованием Raw-Unicode-Escape и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.

### Кодеки Latin-1

Это API кодеков Latin-1: Latin-1 соответствует первым 256 кодовым позициям Unicode, и только они принимаются кодеками при кодировании.

#### `PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)`

*Возвращаемое значение: новая ссылка.*

Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в Latin-1. Возвращает *NULL*, если кодек вызвал исключение.

#### `PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`

*Возвращаемое значение: новая ссылка.*

Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) заданного размера *size* с помощью Latin-1 и возвращает объект bytes Python. Возвращает *NULL*, если кодек вызвал исключение.

#### `PyObject* PyUnicode_AsLatin1String(PyObject *unicode)`

*Возвращаемое значение: новая ссылка.*

Кодирует объект Unicode с помощью Latin-1 и возвращает результат как объект bytes Python. Обработка ошибок – “strict”. Возвращает *NULL*, если кодек вызвал исключение.

### Кодеки ASCII

Это API кодеков ASCII. Принимаются только 7-битные данные ASCII. Все остальные коды вызывают ошибки.

#### `PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)`

*Возвращаемое значение: новая ссылка.*

Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в ASCII. Возвращает *NULL*, если кодек вызвал исключение.

#### `PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`

*Возвращаемое значение: новая ссылка.*

Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) заданного размера *size* с помощью ASCII и возвращает объект bytes Python. Возвращает *NULL*, если кодек вызвал исключение.

#### `PyObject* PyUnicode_AsASCIIString(PyObject *unicode)`

*Возвращаемое значение: новая ссылка.*

Кодирует объект Unicode с помощью ASCII и возвращает результат как объект bytes Python. Обработка ошибок – “strict”. Возвращает *NULL*, если кодек вызвал исключение.

### Кодеки с таблицей символов

Этот кодек особенный, так как его можно использовать для реализации множества разных кодеков (именно так и были получены большинство стандартных кодеков, входящих в пакет `encodings`). Кодек использует отображение для кодирования и декодирования символов.

Отображения для декодирования должны сопоставлять отдельные строковые символы отдельным символам Unicode, целым числам (которые затем интерпретируются как кодовые точки Unicode) или None (что означает «неопределённое отображение» и вызывает ошибку).

Отображения для кодирования должны сопоставлять отдельные символы Unicode отдельным строковым символам, целым числам (которые затем интерпретируются как кодовые точки Latin-1) или None (что означает «неопределённое отображение» и вызывает ошибку).

Объекты отображения должны поддерживать только интерфейс отображения \_\_getitem\_\_.

Если при поиске символа возникает LookupError, символ копируется как есть; это означает, что его порядковое значение будет интерпретироваться как кодовая точка Unicode или Latin-1 соответственно. Из-за этого отображения должны содержать только те соответствия, которые переводят символы в другие кодовые точки.

Это API кодеков отображения:

#### `PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors)`

*Возвращаемое значение: новая ссылка.*

Создаёт объект Unicode, декодируя *size* байт закодированной строки *s* с помощью заданного объекта *mapping*. Возвращает *NULL*, если кодек вызвал исключение. Если *mapping* равен *NULL*, выполняется декодирование Latin-1. В противном случае это может быть словарь, отображающий байты, или строка Unicode, которая интерпретируется как таблица поиска. Значения байтов, превышающие длину строки, и «символ» U+FFFE считаются «неопределённым отображением».

#### `PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)`

*Возвращаемое значение: новая ссылка.*

Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) заданного размера *size* с помощью заданного объекта *mapping* и возвращает строковый объект Python. Возвращает *NULL*, если кодек вызвал исключение.

#### `PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)`

*Возвращаемое значение: новая ссылка.*

Кодирует объект Unicode с помощью заданного объекта *mapping* и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.

Следующее API кодека особенное тем, что отображает Unicode в Unicode.

#### `PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *table, const char *errors)`

*Возвращаемое значение: новая ссылка.*

Переводит буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) заданного размера *size*, применяя к нему символьное отображение *table*, и возвращает результирующий объект Unicode. Возвращает *NULL*, если кодек вызвал исключение.

Таблица *mapping* должна сопоставлять целочисленные кодовые точки Unicode целочисленным кодовым точкам Unicode или None (что приводит к удалению символа).

Таблицам отображения достаточно реализовать интерфейс [`__getitem__()`](https://python-all.ru/3.2/reference/datamodel.html#object.__getitem__); словари и последовательности подходят. Неотображённые коды символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.2/library/exceptions.html#LookupError)) остаются без изменений и копируются как есть.

### Кодеки MBCS для Windows

Это API кодеков MBCS. В настоящее время они доступны только в Windows и используют преобразователи Win32 MBCS для выполнения преобразований. Обратите внимание, что MBCS (или DBCS) – это класс кодировок, а не одна конкретная. Целевая кодировка определяется пользовательскими настройками на машине, где выполняется кодек.

#### `PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)`

*Возвращаемое значение: новая ссылка.*

Создаёт объект Unicode, декодируя *size* байтов строки, закодированной в MBCS, из *s*. Возвращает *NULL*, если кодек вызвал исключение.

#### `PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed)`

Если *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*.

#### `PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`

*Возвращаемое значение: новая ссылка.*

Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) заданного размера *size* с помощью MBCS и возвращает объект bytes Python. Возвращает *NULL*, если кодек возбудил исключение.

#### `PyObject* PyUnicode_AsMBCSString(PyObject *unicode)`

*Возвращаемое значение: новая ссылка.*

Кодирует объект Unicode с помощью MBCS и возвращает результат в виде объекта bytes Python. Обработка ошибок – "strict". Возвращает *NULL*, если кодек вызвал исключение.

### Методы и слоты

## Методы и слот-функции

Следующие API могут обрабатывать объекты Unicode и строки на входе (в описаниях мы называем их строками) и возвращают объекты Unicode или целые числа по необходимости.

Все они возвращают *NULL* или `-1` в случае исключения.

#### `PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)`

*Возвращаемое значение: новая ссылка.*

Объединяет две строки, возвращая новую строку Unicode.

#### `PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)`

*Возвращаемое значение: новая ссылка.*

Разделяет строку и возвращает список строк Unicode. Если *sep* равен *NULL*, разделение происходит по всем подстрокам из пробельных символов. В противном случае разделение выполняется по указанному разделителю. Выполняется не более *maxsplit* разделений. Если значение отрицательное, ограничение не устанавливается. Разделители не включаются в результирующий список.

#### `PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)`

*Возвращаемое значение: новая ссылка.*

Разделяет строку Unicode по символам перевода строки и возвращает список строк Unicode. CRLF считается одним переносом строки. Если *keepend* равен 0, символы перевода строки не включаются в результирующие строки.

#### `PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)`

*Возвращаемое значение: новая ссылка.*

Переводит строку, применяя к ней таблицу отображения символов, и возвращает результирующий объект Unicode.

Таблица отображения должна сопоставлять целочисленные коды Unicode другим целочисленным кодам Unicode или None (что приводит к удалению символа).

Таблицам отображения достаточно реализовать интерфейс [`__getitem__()`](https://python-all.ru/3.2/reference/datamodel.html#object.__getitem__); словари и последовательности подходят. Неотображённые коды символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.2/library/exceptions.html#LookupError)) остаются без изменений и копируются как есть.

*errors* имеет обычное для кодеков значение. Может быть *NULL*, что означает использование обработки ошибок по умолчанию.

#### `PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)`

*Возвращаемое значение: новая ссылка.*

Объединяет последовательность строк, используя заданный *разделитель*, и возвращает полученную Unicode-строку.

#### `int PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)`

Возвращает 1, если *substr* совпадает с `str[start:end]` на указанном конце (*direction* == -1 означает поиск по префиксу, *direction* == 1 – поиск по суффиксу), и 0 в противном случае. Возвращает `-1`, если произошла ошибка.

#### `Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)`

Возвращает первую позицию *substr* в `str[start:end]`, используя заданное *direction* (*direction* == 1 означает прямой поиск, *direction* == -1 – обратный). Возвращаемое значение – индекс первого совпадения; значение `-1` означает, что совпадений не найдено, а `-2` – что произошла ошибка и было установлено исключение.

#### `Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)`

Возвращает количество непересекающихся вхождений *substr* в `str[start:end]`. Возвращает `-1`, если произошла ошибка.

#### `PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)`

*Возвращаемое значение: новая ссылка.*

Заменяет не более *maxcount* вхождений *substr* в *str* на *replstr* и возвращает результирующий объект Unicode. *maxcount* == -1 означает замену всех вхождений.

#### `int PyUnicode_Compare(PyObject *left, PyObject *right)`

Сравнивает две строки и возвращает -1, 0, 1 для случаев «меньше», «равно» и «больше» соответственно.

#### `int PyUnicode_CompareWithASCIIString(PyObject *uni, char *string)`

Сравнивает объект Unicode *uni* со строкой *string* и возвращает -1, 0, 1 для случаев меньше, равно и больше соответственно. Рекомендуется передавать только строки в кодировке ASCII, но если строка содержит не-ASCII символы, функция интерпретирует её как ISO-8859-1.

#### `int PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)`

Выполняет расширенное сравнение двух строк unicode и возвращает одно из следующих значений:

- `NULL` в случае возбуждения исключения
- `Py_True` или `Py_False` при успешном сравнении
- `Py_NotImplemented` в случае, если комбинация типов неизвестна

Обратите внимание, что сравнения с `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).

Возможные значения для *op*: `Py_GT`, `Py_GE`, `Py_EQ`, `Py_NE`, `Py_LT` и `Py_LE`.

#### `PyObject* PyUnicode_Format(PyObject *format, PyObject *args)`

*Возвращаемое значение: новая ссылка.*

Возвращает новый строковый объект из *format* и *args*; это аналогично `format % args`. Аргумент *args* должен быть кортежем.

#### `int PyUnicode_Contains(PyObject *container, PyObject *element)`

Проверяет, содержится ли *element* в *container*, и возвращает true или false соответственно.

*element* должен преобразовываться в односимвольную строку Unicode. Если произошла ошибка, возвращается `-1`.

#### `void PyUnicode_InternInPlace(PyObject **string)`

Интернирует аргумент *\*string* на месте. Аргумент должен быть адресом переменной-указателя, указывающей на объект строки Unicode Python. Если уже существует интернированная строка, совпадающая с *\*string*, то она устанавливает *\*string* на эту строку (уменьшая счётчик ссылок старого строкового объекта и увеличивая счётчик интернированной строки); в противном случае она оставляет *\*string* без изменений и интернирует её (увеличивая её счётчик ссылок). (Уточнение: хотя много говорится о счётчиках ссылок, считайте эту функцию нейтральной к счётчикам ссылок – вы владеете объектом после вызова, только если владели им до вызова.)

#### `PyObject* PyUnicode_InternFromString(const char *v)`

Комбинация [`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, который был интернирован, либо новую («владетельную») ссылку на ранее интернированный строковый объект с тем же значением.