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

---

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

## Объекты Unicode

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

**\[Py\_UNICODE\]`Py_UNICODE`**

Этот тип представляет тип хранения, который используется внутри Python в качестве основы для хранения порядковых номеров символов Unicode. В стандартной сборке Python используется 16-битный тип для

[`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE)

, и значения Unicode хранятся внутри в UCS2. Также возможна сборка Python с UCS4 (большинство современных дистрибутивов Linux поставляются с UCS4-сборками Python). В таких сборках используется 32-битный тип для

[`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE)

, и данные Unicode хранятся внутри в UCS4. На платформах, где

`wchar_t`

доступен и совместим с выбранным вариантом сборки Unicode Python,

[`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE)

является псевдонимом typedef для

`wchar_t`

для улучшения совместимости с нативной платформой. На всех остальных платформах

[`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE)

является псевдонимом typedef для

`unsigned short`

(UCS2) или

`unsigned long`

(UCS4).

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

**\[PyUnicodeObject\]`PyUnicodeObject`**

Этот подтип

[`PyObject`](https://python-all.ru/3.0/c-api/structures.html#PyObject)

представляет объект Unicode в Python.

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

Этот экземпляр

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

представляет тип Unicode в Python. Он доступен в коде Python как

`str`

.

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

**\[PyUnicode\_Check\]int `PyUnicode_Check`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**

Возвращает true, если объект

*o*

является объектом Unicode или экземпляром подтипа Unicode.

**\[PyUnicode\_CheckExact\]int `PyUnicode_CheckExact`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**

Возвращает true, если объект

*o*

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

**\[PyUnicode\_GET\_SIZE\]Py\_ssize\_t `PyUnicode_GET_SIZE`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**

Возвращает размер объекта.

*o*

должен быть

[`PyUnicodeObject`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicodeObject)

(не проверяется).

**\[PyUnicode\_GET\_DATA\_SIZE\]Py\_ssize\_t `PyUnicode_GET_DATA_SIZE`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**

Возвращает размер внутреннего буфера объекта в байтах.

*o*

должен быть

[`PyUnicodeObject`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicodeObject)

(не проверяется).

**\[PyUnicode\_AS\_UNICODE\][Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE)\* `PyUnicode_AS_UNICODE`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**

Возвращает указатель на внутренний буфер

[`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE)

объекта.

*o*

должен быть

[`PyUnicodeObject`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicodeObject)

(не проверяется).

**\[PyUnicode\_AS\_DATA\]const char\* `PyUnicode_AS_DATA`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**

Возвращает указатель на внутренний буфер объекта.

*o*

должен быть

[`PyUnicodeObject`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicodeObject)

(не проверяется).

**\[PyUnicode\_ClearFreeList\]int `PyUnicode_ClearFreeList`(void)**

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

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

**\[Py\_UNICODE\_ISSPACE\]int `Py_UNICODE_ISSPACE`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**

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

*ch*

пробельным символом.

**\[Py\_UNICODE\_ISLOWER\]int `Py_UNICODE_ISLOWER`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**

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

*ch*

символом нижнего регистра.

**\[Py\_UNICODE\_ISUPPER\]int `Py_UNICODE_ISUPPER`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**

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

*ch*

символом верхнего регистра.

**\[Py\_UNICODE\_ISTITLE\]int `Py_UNICODE_ISTITLE`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**

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

*ch*

символом в регистре заголовка.

**\[Py\_UNICODE\_ISLINEBREAK\]int `Py_UNICODE_ISLINEBREAK`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**

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

*ch*

символом разрыва строки.

**\[Py\_UNICODE\_ISDECIMAL\]int `Py_UNICODE_ISDECIMAL`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**

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

*ch*

десятичной цифрой.

**\[Py\_UNICODE\_ISDIGIT\]int `Py_UNICODE_ISDIGIT`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**

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

*ch*

цифровым символом.

**\[Py\_UNICODE\_ISNUMERIC\]int `Py_UNICODE_ISNUMERIC`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**

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

*ch*

числовым символом.

**\[Py\_UNICODE\_ISALPHA\]int `Py_UNICODE_ISALPHA`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**

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

*ch*

буквенным символом.

**\[Py\_UNICODE\_ISALNUM\]int `Py_UNICODE_ISALNUM`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**

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

*ch*

буквенно-цифровым символом.

**\[Py\_UNICODE\_ISPRINTABLE\]int `Py_UNICODE_ISPRINTABLE`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**

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

*ch*

печатаемым символом. Непечатаемые символы – это символы, определённые в базе данных Unicode как «Other» или «Separator», за исключением пробела ASCII (0x20), который считается печатаемым. (Обратите внимание, что печатаемые символы в этом контексте – это те, которые не должны экранироваться при вызове

[`repr()`](https://python-all.ru/3.0/library/functions.html#repr)

для строки. Это не влияет на обработку строк, записываемых в

[`sys.stdout`](https://python-all.ru/3.0/library/sys.html#sys.stdout)

или

[`sys.stderr`](https://python-all.ru/3.0/library/sys.html#sys.stderr)

.)

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

**\[Py\_UNICODE\_TOLOWER\][Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) `Py_UNICODE_TOLOWER`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает символ

*ch*

, преобразованный в нижний регистр.

**\[Py\_UNICODE\_TOUPPER\][Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) `Py_UNICODE_TOUPPER`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает символ

*ch*

, преобразованный в верхний регистр.

**\[Py\_UNICODE\_TOTITLE\][Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) `Py_UNICODE_TOTITLE`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает символ

*ch*

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

**\[Py\_UNICODE\_TODECIMAL\]int `Py_UNICODE_TODECIMAL`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает символ

*ch*

, преобразованный в десятичное положительное целое. Возвращает

`-1`

, если это невозможно. Этот макрос не вызывает исключений.

**\[Py\_UNICODE\_TODIGIT\]int `Py_UNICODE_TODIGIT`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает символ

*ch*

, преобразованный в целое однозначное число. Возвращает

`-1`

, если это невозможно. Этот макрос не вызывает исключений.

**\[Py\_UNICODE\_TONUMERIC\]double `Py_UNICODE_TONUMERIC`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает символ

*ch*

, преобразованный в double. Возвращает

`-1.0`

, если это невозможно. Этот макрос не вызывает исключений.

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

**\[PyUnicode\_FromUnicode\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_FromUnicode`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*u*, Py\_ssize\_t *size*)**

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

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

**\[PyUnicode\_FromStringAndSize\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_FromStringAndSize`(const char *\*u*, Py\_ssize\_t *size*)**

Create a Unicode Object from the char buffer

*u*

. The bytes will be interpreted as being UTF-8 encoded.

*u*

may also be

*NULL*

which causes the contents to be undefined. It is the user’s responsibility to fill in the needed data. The buffer is copied into the new object. If the buffer is not

*NULL*

, the return value might be a shared object. Therefore, modification of the resulting Unicode object is only allowed when

*u*

is

*NULL*

.

**\[PyUnicode\_FromString\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) \*`PyUnicode_FromString`(const char *\*u*)**

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

*u*

.

**\[PyUnicode\_FromFormat\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_FromFormat`(const char *\*format*, ...)**

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

| Символы формата | Тип | Описание |
| --- | --- | --- |
| `%%` | *н/д* | Буквальный символ %. |
| `%c` | int | Одиночный символ, представленный как C int. |
| `%d` | int | Полностью эквивалентно `printf("%d")`. |
| `%u` | беззнаковый int | Полностью эквивалентно `printf("%u")`. |
| `%ld` | long | Полностью эквивалентно `printf("%ld")`. |
| `%lu` | беззнаковый long | Полностью эквивалентно `printf("%lu")`. |
| `%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.0/library/functions.html#ascii). |
| `%U` | PyObject\* | Unicode-объект. |
| `%V` | PyObject\*, char \* | Unicode-объект (может быть *NULL*) и завершающийся нулевым символом C-массив символов в качестве второго параметра (используется, если первый параметр равен *NULL*). |
| `%S` | PyObject\* | Результат вызова `PyObject_Unicode()`. |
| `%R` | PyObject\* | Результат вызова [`PyObject_Repr()`](https://python-all.ru/3.0/c-api/object.html#PyObject_Repr). |

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

**\[PyUnicode\_FromFormatV\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_FromFormatV`(const char *\*format*, va\_list *vargs*)**

Идентична

[`PyUnicode_FromFormat()`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicode_FromFormat)

, за исключением того, что принимает ровно два аргумента.

**\[PyUnicode\_AsUnicode\][Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE)\* `PyUnicode_AsUnicode`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*)**

Возвращает указатель только для чтения на внутренний буфер

[`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE)

объекта Unicode;

*NULL*

, если

*unicode*

не является объектом Unicode.

**\[PyUnicode\_GetSize\]Py\_ssize\_t `PyUnicode_GetSize`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*)**

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

**\[PyUnicode\_FromEncodedObject\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_FromEncodedObject`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*obj*, const char *\*encoding*, const char *\*errors*)**

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

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

Строки и другие объекты, совместимые с символьными буферами, декодируются в соответствии с заданной кодировкой и с использованием обработки ошибок, определённой параметром errors. Оба параметра могут быть *NULL*, чтобы интерфейс использовал значения по умолчанию (подробнее см. следующий раздел).

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

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

**\[PyUnicode\_FromObject\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_FromObject`([PyObject](https://python-all.ru/3.0/c-api/structures.html#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.0/c-api/unicode.html#Py_UNICODE) Python идентичен системному `wchar_t`.

**\[PyUnicode\_FromWideChar\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_FromWideChar`(const wchar\_t *\*w*, Py\_ssize\_t *size*)**

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

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

**\[PyUnicode\_AsWideChar\]Py\_ssize\_t `PyUnicode_AsWideChar`([PyUnicodeObject](https://python-all.ru/3.0/c-api/unicode.html#PyUnicodeObject) *\*unicode*, wchar\_t *\*w*, Py\_ssize\_t *size*)**

Копирует содержимое объекта Unicode в буфер

`wchar_t`

*w*

. Копируется не более

*size*

символов

`wchar_t`

(возможный завершающий нулевой символ не учитывается). Возвращает количество скопированных символов

`wchar_t`

или -1 в случае ошибки. Обратите внимание: результирующая строка

`wchar_t`

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

`wchar_t`

заканчивается нулевым символом, если это требуется приложению.

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

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

Многие из следующих API принимают два аргумента: encoding и errors. Эти параметры encoding и errors имеют ту же семантику, что и одноимённые параметры встроенного конструктора объектов Unicode unicode().

Установка encoding в *NULL* приводит к использованию кодировки по умолчанию, которой является ASCII. Системные вызовы для работы с файлами должны использовать `Py_FileSystemDefaultEncoding` в качестве кодировки для имён файлов. Эту переменную следует считать доступной только для чтения: на одних системах это указатель на статическую строку, на других она может изменяться во время выполнения (например, когда приложение вызывает setlocale).

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

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

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

**\[PyUnicode\_Decode\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_Decode`(const char *\*s*, Py\_ssize\_t *size*, const char *\*encoding*, const char *\*errors*)**

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

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

**\[PyUnicode\_Encode\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_Encode`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*encoding*, const char *\*errors*)**

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

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

**\[PyUnicode\_AsEncodedString\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_AsEncodedString`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*, const char *\*encoding*, const char *\*errors*)**

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

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

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

**\[PyUnicode\_DecodeUTF8\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF8`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

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

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

**\[PyUnicode\_DecodeUTF8Stateful\][PyObject](https://python-all.ru/3.0/c-api/structures.html#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.0/c-api/unicode.html#PyUnicode_DecodeUTF8). Если *consumed* не равен *NULL*, конечные неполные последовательности байт UTF-8 не считаются ошибкой. Эти байты не декодируются, а количество уже декодированных байт сохраняется в *consumed*.

**\[PyUnicode\_EncodeUTF8\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_EncodeUTF8`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

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

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

**\[PyUnicode\_AsUTF8String\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_AsUTF8String`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*)**

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

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

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

**\[PyUnicode\_DecodeUTF32\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF32`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *\*byteorder*)**

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

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

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

а затем переключается, если первые четыре байта входных данных являются маркером порядка байт (BOM) и заданный порядок байт является порядком хост-системы. Этот BOM не копируется в результирующую строку Unicode. После завершения в *\*byteorder* устанавливается текущий порядок байт на конец входных данных.

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

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

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

**\[PyUnicode\_DecodeUTF32Stateful\][PyObject](https://python-all.ru/3.0/c-api/structures.html#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.0/c-api/unicode.html#PyUnicode_DecodeUTF32)

. Если

*consumed*

не равен

*NULL*

,

[`PyUnicode_DecodeUTF32Stateful`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicode_DecodeUTF32Stateful)

не считает ошибкой остаточные неполные последовательности байтов UTF-32 (например, количество байтов, не кратное четырем). Такие байты не декодируются, а количество декодированных байтов сохраняется в

*consumed*

.

**\[PyUnicode\_EncodeUTF32\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_EncodeUTF32`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *byteorder*)**

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

```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*, если кодек сгенерировал исключение.

**\[PyUnicode\_AsUTF32String\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_AsUTF32String`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*)**

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

*NULL*

, если кодек вызвал исключение.

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

**\[PyUnicode\_DecodeUTF16\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF16`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *\*byteorder*)**

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

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

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

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

и затем переключается, если первые два байта входных данных являются маркером порядка байтов (BOM), а указанный порядок байтов является native. Этот BOM не копируется в результирующую строку Unicode. После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных.

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

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

**\[PyUnicode\_DecodeUTF16Stateful\][PyObject](https://python-all.ru/3.0/c-api/structures.html#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.0/c-api/unicode.html#PyUnicode_DecodeUTF16). Если *consumed* не равен *NULL*, [`PyUnicode_DecodeUTF16Stateful`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicode_DecodeUTF16Stateful) не считает ошибкой остаточные неполные последовательности байтов UTF-16 (например, нечётное количество байтов или разделённая суррогатная пара). Такие байты не декодируются, а количество декодированных байтов сохраняется в *consumed*.

**\[PyUnicode\_EncodeUTF16\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_EncodeUTF16`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *byteorder*)**

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

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

```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.0/c-api/unicode.html#Py_UNICODE) может быть представлено как суррогатная пара. Если он не определён, каждое значение [`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) интерпретируется как символ UCS-2.

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

**\[PyUnicode\_AsUTF16String\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_AsUTF16String`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*)**

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

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

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

**\[PyUnicode\_DecodeUnicodeEscape\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUnicodeEscape`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

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

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

**\[PyUnicode\_EncodeUnicodeEscape\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_EncodeUnicodeEscape`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*)**

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

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

**\[PyUnicode\_AsUnicodeEscapeString\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_AsUnicodeEscapeString`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*)**

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

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

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

**\[PyUnicode\_DecodeRawUnicodeEscape\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeRawUnicodeEscape`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

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

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

**\[PyUnicode\_EncodeRawUnicodeEscape\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_EncodeRawUnicodeEscape`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

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

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

**\[PyUnicode\_AsRawUnicodeEscapeString\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_AsRawUnicodeEscapeString`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*)**

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

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

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

**\[PyUnicode\_DecodeLatin1\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeLatin1`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

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

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

**\[PyUnicode\_EncodeLatin1\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_EncodeLatin1`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

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

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

**\[PyUnicode\_AsLatin1String\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_AsLatin1String`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*)**

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

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

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

**\[PyUnicode\_DecodeASCII\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeASCII`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

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

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

**\[PyUnicode\_EncodeASCII\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_EncodeASCII`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

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

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

**\[PyUnicode\_AsASCIIString\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_AsASCIIString`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*)**

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

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

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

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

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

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

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

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

**\[PyUnicode\_DecodeCharmap\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeCharmap`(const char *\*s*, Py\_ssize\_t *size*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*mapping*, const char *\*errors*)**

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

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

**\[PyUnicode\_EncodeCharmap\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_EncodeCharmap`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*mapping*, const char *\*errors*)**

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

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

**\[PyUnicode\_AsCharmapString\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_AsCharmapString`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*mapping*)**

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

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

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

**\[PyUnicode\_TranslateCharmap\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_TranslateCharmap`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*table*, const char *\*errors*)**

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

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

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

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

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

**\[PyUnicode\_DecodeMBCS\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeMBCS`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

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

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

**\[PyUnicode\_DecodeMBCSStateful\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeMBCSStateful`(const char *\*s*, int *size*, const char *\*errors*, int *\*consumed*)**

Если

*consumed*

равно

*NULL*

, ведёт себя как

[`PyUnicode_DecodeMBCS`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicode_DecodeMBCS)

. Если

*consumed*

не равно

*NULL*

,

[`PyUnicode_DecodeMBCSStateful`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicode_DecodeMBCSStateful)

не будет декодировать ведущий байт в конце, и количество декодированных байтов будет сохранено в

*consumed*

.

**\[PyUnicode\_EncodeMBCS\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_EncodeMBCS`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

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

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

**\[PyUnicode\_AsMBCSString\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_AsMBCSString`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*)**

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

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

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

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

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

**\[PyUnicode\_Concat\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_Concat`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*left*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*right*)**

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

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

**\[PyUnicode\_Split\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_Split`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*s*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*sep*, Py\_ssize\_t *maxsplit*)**

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

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

**\[PyUnicode\_Splitlines\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_Splitlines`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*s*, int *keepend*)**

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

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

**\[PyUnicode\_Translate\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_Translate`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*str*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*table*, const char *\*errors*)**

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

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

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

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

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

**\[PyUnicode\_Join\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_Join`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*separator*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*seq*)**

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

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

**\[PyUnicode\_Tailmatch\]int `PyUnicode_Tailmatch`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*str*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*substr*, Py\_ssize\_t *start*, Py\_ssize\_t *end*, int *direction*)**

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

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

**\[PyUnicode\_Find\]Py\_ssize\_t `PyUnicode_Find`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*str*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*substr*, Py\_ssize\_t *start*, Py\_ssize\_t *end*, int *direction*)**

Возвращает первую позицию

*substr*

в

*str\[\*start*

:

*end*

\], используя заданное

*direction*

(

*direction*

== 1 означает прямой поиск,

*direction*

== -1 – обратный поиск). Возвращаемое значение – индекс первого совпадения; значение

`-1`

указывает, что совпадение не найдено, а

`-2`

указывает, что произошла ошибка и было установлено исключение.

**\[PyUnicode\_Count\]Py\_ssize\_t `PyUnicode_Count`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*str*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*substr*, Py\_ssize\_t *start*, Py\_ssize\_t *end*)**

Возвращает количество непересекающихся вхождений

*substr*

в

`str[start:end]`

. Возвращает

`-1`

, если произошла ошибка.

**\[PyUnicode\_Replace\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_Replace`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*str*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*substr*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*replstr*, Py\_ssize\_t *maxcount*)**

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

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

**\[PyUnicode\_Compare\]int `PyUnicode_Compare`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*left*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*right*)**

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

**\[PyUnicode\_CompareWithASCIIString\]int `PyUnicode_CompareWithASCIIString`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*uni*, char *\*string*)**

Сравнивает объект Unicode

*uni*

со строкой

*string*

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

**\[PyUnicode\_RichCompare\]int `PyUnicode_RichCompare`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*left*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*right*, int *op*)**

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

- `NULL` в случае возбуждения исключения
- [`Py_True`](https://python-all.ru/3.0/c-api/bool.html#Py_True) или [`Py_False`](https://python-all.ru/3.0/c-api/bool.html#Py_False) для успешных сравнений
- `Py_NotImplemented` в случае, если комбинация типов неизвестна

Обратите внимание, что сравнения с `Py_EQ` и `Py_NE` могут вызвать [`UnicodeWarning`](https://python-all.ru/3.0/library/exceptions.html#exceptions.UnicodeWarning), если преобразование аргументов в Unicode завершится ошибкой с [`UnicodeDecodeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.UnicodeDecodeError).

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

**\[PyUnicode\_Format\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_Format`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*format*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*args*)**

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

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

**\[PyUnicode\_Contains\]int `PyUnicode_Contains`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*container*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*element*)**

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

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

**\[PyUnicode\_InternInPlace\]void `PyUnicode_InternInPlace`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*\*string*)**

Интернирует аргумент

*\*string*

на месте. Аргумент должен быть адресом переменной-указателя, указывающей на объект строки Unicode Python. Если уже существует интернированная строка, совпадающая с

*\*string*

, то она устанавливает

*\*string*

на эту строку (уменьшая счётчик ссылок старого строкового объекта и увеличивая счётчик интернированной строки); в противном случае она оставляет

*\*string*

без изменений и интернирует её (увеличивая её счётчик ссылок). (Уточнение: хотя много говорится о счётчиках ссылок, считайте эту функцию нейтральной к счётчикам ссылок – вы владеете объектом после вызова, только если владели им до вызова.)

**\[PyUnicode\_InternFromString\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_InternFromString`(const char *\*v*)**

Комбинация

[`PyUnicode_FromString`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicode_FromString)

и

[`PyUnicode_InternInPlace`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicode_InternInPlace)

, возвращающая либо новый объект строки юникода, который был интернирован, либо новую («собственную») ссылку на ранее интернированный строковый объект с тем же значением.