`unicode.md`

1130 строк · 70.3 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.1/c-api/unicode.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты Unicode и кодеки89## Объекты Unicode1011### Тип Unicode1213Это основные типы объектов Unicode, используемые в реализации Unicode в Python:1415**`Py_UNICODE`**1617Этот тип представляет тип хранения, который используется внутри Python в качестве основы для хранения порядковых номеров символов Unicode. В стандартной сборке Python используется 16-битный тип для1819[`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE)2021, и значения Unicode хранятся внутри в UCS2. Также возможна сборка Python с UCS4 (большинство современных дистрибутивов Linux поставляются с UCS4-сборками Python). В таких сборках используется 32-битный тип для2223[`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE)2425, и данные Unicode хранятся внутри в UCS4. На платформах, где2627`wchar_t`2829доступен и совместим с выбранным вариантом сборки Unicode Python,3031[`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE)3233является псевдонимом typedef для3435`wchar_t`3637для улучшения совместимости с нативной платформой. На всех остальных платформах3839[`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE)4041является псевдонимом typedef для4243`unsigned short`4445(UCS2) или4647`unsigned long`4849(UCS4).5051Обратите внимание, что сборки Python с UCS2 и UCS4 не являются двоично совместимыми. Учитывайте это при написании расширений или интерфейсов.5253**`PyUnicodeObject`**5455Этот подтип5657[`PyObject`](https://python-all.ru/3.1/c-api/structures.html#PyObject)5859представляет объект Unicode в Python.6061**[PyTypeObject](https://python-all.ru/3.1/c-api/type.html#PyTypeObject) `PyUnicode_Type`**6263Этот экземпляр6465[`PyTypeObject`](https://python-all.ru/3.1/c-api/type.html#PyTypeObject)6667представляет тип Unicode в Python. Он доступен в коде Python как6869`str`7071.7273Следующие API на самом деле являются макросами C и могут использоваться для быстрых проверок и доступа к внутренним данным Unicode объектов только для чтения:7475**int `PyUnicode_Check`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*o*)**7677Возвращает true, если объект7879*o*8081является объектом Unicode или экземпляром подтипа Unicode.8283**int `PyUnicode_CheckExact`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*o*)**8485Возвращает true, если объект8687*o*8889является объектом Unicode, но не экземпляром подтипа.9091**Py\_ssize\_t `PyUnicode_GET_SIZE`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*o*)**9293Возвращает размер объекта.9495*o*9697должен быть9899[`PyUnicodeObject`](https://python-all.ru/3.1/c-api/unicode.html#PyUnicodeObject)100101(не проверяется).102103**Py\_ssize\_t `PyUnicode_GET_DATA_SIZE`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*o*)**104105Возвращает размер внутреннего буфера объекта в байтах.106107*o*108109должен быть110111[`PyUnicodeObject`](https://python-all.ru/3.1/c-api/unicode.html#PyUnicodeObject)112113(не проверяется).114115**[Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE)\* `PyUnicode_AS_UNICODE`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*o*)**116117Возвращает указатель на внутренний буфер118119[`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE)120121объекта.122123*o*124125должен быть126127[`PyUnicodeObject`](https://python-all.ru/3.1/c-api/unicode.html#PyUnicodeObject)128129(не проверяется).130131**const char\* `PyUnicode_AS_DATA`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*o*)**132133Возвращает указатель на внутренний буфер объекта.134135*o*136137должен быть138139[`PyUnicodeObject`](https://python-all.ru/3.1/c-api/unicode.html#PyUnicodeObject)140141(не проверяется).142143**int `PyUnicode_ClearFreeList`()**144145Очищает список свободных элементов. Возвращает общее количество освобождённых элементов.146147### Свойства символов Unicode148149Unicode предоставляет множество различных свойств символов. Наиболее востребованные из них доступны через следующие макросы, которые сопоставляются с функциями на C в зависимости от конфигурации Python.150151**int `Py_UNICODE_ISSPACE`([Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *ch*)**152153Возвращает 1 или 0 в зависимости от того, является ли154155*ch*156157пробельным символом.158159**int `Py_UNICODE_ISLOWER`([Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *ch*)**160161Возвращает 1 или 0 в зависимости от того, является ли162163*ch*164165символом нижнего регистра.166167**int `Py_UNICODE_ISUPPER`([Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *ch*)**168169Возвращает 1 или 0 в зависимости от того, является ли170171*ch*172173символом верхнего регистра.174175**int `Py_UNICODE_ISTITLE`([Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *ch*)**176177Возвращает 1 или 0 в зависимости от того, является ли178179*ch*180181символом в регистре заголовка.182183**int `Py_UNICODE_ISLINEBREAK`([Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *ch*)**184185Возвращает 1 или 0 в зависимости от того, является ли186187*ch*188189символом разрыва строки.190191**int `Py_UNICODE_ISDECIMAL`([Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *ch*)**192193Возвращает 1 или 0 в зависимости от того, является ли194195*ch*196197десятичной цифрой.198199**int `Py_UNICODE_ISDIGIT`([Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *ch*)**200201Возвращает 1 или 0 в зависимости от того, является ли202203*ch*204205цифровым символом.206207**int `Py_UNICODE_ISNUMERIC`([Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *ch*)**208209Возвращает 1 или 0 в зависимости от того, является ли210211*ch*212213числовым символом.214215**int `Py_UNICODE_ISALPHA`([Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *ch*)**216217Возвращает 1 или 0 в зависимости от того, является ли218219*ch*220221буквенным символом.222223**int `Py_UNICODE_ISALNUM`([Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *ch*)**224225Возвращает 1 или 0 в зависимости от того, является ли226227*ch*228229буквенно-цифровым символом.230231**int `Py_UNICODE_ISPRINTABLE`([Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *ch*)**232233Возвращает 1 или 0 в зависимости от того, является ли234235*ch*236237печатаемым символом. Непечатаемые символы – это символы, определённые в базе данных Unicode как «Other» или «Separator», за исключением пробела ASCII (0x20), который считается печатаемым. (Обратите внимание, что печатаемые символы в этом контексте – это те, которые не должны экранироваться при вызове238239[`repr()`](https://python-all.ru/3.1/library/functions.html#repr)240241для строки. Это не влияет на обработку строк, записываемых в242243[`sys.stdout`](https://python-all.ru/3.1/library/sys.html#sys.stdout)244245или246247[`sys.stderr`](https://python-all.ru/3.1/library/sys.html#sys.stderr)248249.)250251Эти API можно использовать для быстрых прямых преобразований символов:252253**[Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) `Py_UNICODE_TOLOWER`([Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *ch*)**254255Возвращает символ256257*ch*258259, преобразованный в нижний регистр.260261**[Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) `Py_UNICODE_TOUPPER`([Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *ch*)**262263Возвращает символ264265*ch*266267, преобразованный в верхний регистр.268269**[Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) `Py_UNICODE_TOTITLE`([Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *ch*)**270271Возвращает символ272273*ch*274275, приведённый к регистру заголовка.276277**int `Py_UNICODE_TODECIMAL`([Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *ch*)**278279Возвращает символ280281*ch*282283, преобразованный в десятичное положительное целое. Возвращает284285`-1`286287, если это невозможно. Этот макрос не вызывает исключений.288289**int `Py_UNICODE_TODIGIT`([Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *ch*)**290291Возвращает символ292293*ch*294295, преобразованный в целое однозначное число. Возвращает296297`-1`298299, если это невозможно. Этот макрос не вызывает исключений.300301**double `Py_UNICODE_TONUMERIC`([Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *ch*)**302303Возвращает символ304305*ch*306307, преобразованный в double. Возвращает308309`-1.0`310311, если это невозможно. Этот макрос не вызывает исключений.312313### Простой Py\_UNICODE314315Для создания объектов Unicode и доступа к их базовым свойствам последовательности используйте следующие API:316317**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_FromUnicode`(const [Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *\*u*, Py\_ssize\_t *size*)**318319*Возвращаемое значение: новая ссылка.*320321Создаёт объект Unicode из буфера Py\_UNICODE *u* указанного размера. *u* может быть *NULL*, что делает содержимое неопределённым. Ответственность за заполнение нужными данными лежит на пользователе. Буфер копируется в новый объект. Если буфер не равен *NULL*, возвращаемое значение может быть разделяемым объектом. Поэтому изменение результирующего объекта Unicode допускается только когда *u* равно *NULL*.322323**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_FromStringAndSize`(const char *\*u*, Py\_ssize\_t *size*)**324325Создаёт объект Unicode из буфера char326327*u*328329. Байты интерпретируются как кодировка UTF-8.330331*u*332333также может быть334335*NULL*336337, что делает содержимое неопределённым. Ответственность за заполнение нужными данными лежит на пользователе. Буфер копируется в новый объект. Если буфер не равен338339*NULL*340341, возвращаемое значение может быть разделяемым объектом. Поэтому изменение результирующего объекта Unicode допускается только когда342343*u*344345равно346347*NULL*348349.350351**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) \*`PyUnicode_FromString`(const char *\*u*)**352353Создаёт объект Unicode из UTF-8-кодированного символьного буфера с завершающим нулём354355*u*356357.358359**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_FromFormat`(const char *\*format*, ...)**360361Принимает в стиле C `printf()` *формат* строку и переменное число аргументов, вычисляет размер результирующей строки Python в Unicode и возвращает строку с отформатированными в неё значениями. Переменные аргументы должны быть типами C и точно соответствовать символам формата в строке *формата*. Допускаются следующие символы формата:362363| Символы формата | Тип | Описание |364| --- | --- | --- |365| `%%` | *н/д* | Буквальный символ %. |366| `%c` | int | Одиночный символ, представленный как C int. |367| `%d` | int | Полностью эквивалентно `printf("%d")`. |368| `%u` | беззнаковый int | Полностью эквивалентно `printf("%u")`. |369| `%ld` | long | Полностью эквивалентно `printf("%ld")`. |370| `%lu` | беззнаковый long | Полностью эквивалентно `printf("%lu")`. |371| `%zd` | Py\_ssize\_t | Полностью эквивалентно `printf("%zd")`. |372| `%zu` | size\_t | Полностью эквивалентно `printf("%zu")`. |373| `%i` | int | Полностью эквивалентно `printf("%i")`. |374| `%x` | int | Полностью эквивалентно `printf("%x")`. |375| `%s` | char\* | Нуль-терминированный массив символов C. |376| `%p` | void\* | Шестнадцатеричное представление указателя C. В основном эквивалентно `printf("%p")` за исключением того, что гарантированно начинается с литерала `0x` независимо от того, что выдает `printf` на данной платформе. |377| `%A` | PyObject\* | Результат вызова [`ascii()`](https://python-all.ru/3.1/library/functions.html#ascii). |378| `%U` | PyObject\* | Unicode-объект. |379| `%V` | PyObject\*, char \* | Unicode-объект (может быть *NULL*) и завершающийся нулевым символом C-массив символов в качестве второго параметра (используется, если первый параметр равен *NULL*). |380| `%S` | PyObject\* | Результат вызова [`PyObject_Str()`](https://python-all.ru/3.1/c-api/object.html#PyObject_Str). |381| `%R` | PyObject\* | Результат вызова [`PyObject_Repr()`](https://python-all.ru/3.1/c-api/object.html#PyObject_Repr). |382383Нераспознанный символ формата приводит к тому, что вся оставшаяся строка формата копируется как есть в результирующую строку, а все лишние аргументы отбрасываются.384385**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_FromFormatV`(const char *\*format*, va\_list *vargs*)**386387Идентична388389[`PyUnicode_FromFormat()`](https://python-all.ru/3.1/c-api/unicode.html#PyUnicode_FromFormat)390391, за исключением того, что принимает ровно два аргумента.392393**[Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE)\* `PyUnicode_AsUnicode`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*unicode*)**394395Возвращает указатель только для чтения на внутренний буфер396397[`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE)398399объекта Unicode;400401*NULL*402403, если404405*unicode*406407не является объектом Unicode.408409**Py\_ssize\_t `PyUnicode_GetSize`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*unicode*)**410411Возвращает длину объекта Unicode.412413**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_FromEncodedObject`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*obj*, const char *\*encoding*, const char *\*errors*)**414415*Возвращаемое значение: новая ссылка.*416417Преобразует закодированный объект *obj* в объект Unicode и возвращает ссылку с увеличенным счётчиком ссылок.418419[`bytes`](https://python-all.ru/3.1/library/functions.html#bytes), [`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray) и другие объекты, совместимые с символьным буфером, декодируются согласно заданной *кодировке* с использованием обработки ошибок, определенной *errors*. Оба параметра могут быть *NULL*, чтобы интерфейс использовал значения по умолчанию (подробнее см. в следующем разделе).420421Все остальные объекты, включая объекты Unicode, вызывают установку [`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError).422423API возвращает *NULL* при ошибке. Вызывающий отвечает за уменьшение счётчика ссылок возвращённых объектов.424425**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_FromObject`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*obj*)**426427*Возвращаемое значение: новая ссылка.*428429Shortcut for `PyUnicode_FromEncodedObject(obj, NULL, "strict")` which is used throughout the interpreter whenever coercion to Unicode is needed.430431Если платформа поддерживает `wchar_t` и предоставляет заголовочный файл wchar.h, Python может напрямую взаимодействовать с этим типом с помощью следующих функций. Поддержка оптимизируется, если собственный тип [`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) Python идентичен системному `wchar_t`.432433### Кодировка файловой системы434435Для кодирования и декодирования имён файлов и других строк окружения в качестве кодировки следует использовать `Py_FileSystemEncoding`, а в качестве обработчика ошибок – `"surrogateescape"` ([**PEP 383**](https://python-all.ru/3.1/c-api/unicode.html)). Для кодирования имён файлов при разборе аргументов следует использовать преобразователь `"O&"`, передавая [`PyUnicode_FSConverter()`](https://python-all.ru/3.1/c-api/unicode.html#PyUnicode_FSConverter) в качестве функции преобразования:436437**int `PyUnicode_FSConverter`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* *obj*, void\* *result*)**438439Преобразует *obj* в *result*, используя `Py_FileSystemDefaultEncoding` и обработчик ошибок `"surrogateescape"`. *result* должен быть `PyObject*`; возвращает объект [`bytes()`](https://python-all.ru/3.1/library/functions.html#bytes), который нужно освободить, когда он больше не нужен.440441Новое в версии 3.1.442443**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_DecodeFSDefaultAndSize`(const char *\*s*, Py\_ssize\_t *size*)**444445Декодирует строку, завершающуюся нулевым символом, используя `Py_FileSystemDefaultEncoding` и обработчик ошибок `"surrogateescape"`.446447Если `Py_FileSystemDefaultEncoding` не задана, используется UTF-8.448449Используйте [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.1/c-api/unicode.html#PyUnicode_DecodeFSDefaultAndSize), если известна длина строки.450451**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_DecodeFSDefault`(const char *\*s*)**452453Декодирует строку, используя `Py_FileSystemDefaultEncoding` и обработчик ошибок `"surrogateescape"`.454455Если `Py_FileSystemDefaultEncoding` не задана, используется UTF-8.456457### Поддержка wchar\_t458459Поддержка `wchar_t` на платформах, которые её поддерживают:460461**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_FromWideChar`(const wchar\_t *\*w*, Py\_ssize\_t *size*)**462463*Возвращаемое значение: новая ссылка.*464465Создаёт объект Unicode из буфера `wchar_t` *w* заданного размера *size*. Передача -1 в качестве *size* означает, что функция должна сама вычислить длину, используя wcslen. В случае ошибки возвращает *NULL*.466467**Py\_ssize\_t `PyUnicode_AsWideChar`([PyUnicodeObject](https://python-all.ru/3.1/c-api/unicode.html#PyUnicodeObject) *\*unicode*, wchar\_t *\*w*, Py\_ssize\_t *size*)**468469Копирует содержимое объекта Unicode в буфер470471`wchar_t`472473*w*474475. Копируется не более476477*size*478479символов480481`wchar_t`482483(возможный завершающий нулевой символ не учитывается). Возвращает количество скопированных символов484485`wchar_t`486487или -1 в случае ошибки. Обратите внимание: результирующая строка488489`wchar_t`490491может как содержать, так и не содержать завершающий нулевой символ. Вызывающий должен убедиться, что строка492493`wchar_t`494495заканчивается нулевым символом, если это требуется приложению.496497## Встроенные кодеки498499Python предоставляет набор встроенных кодеков, написанных на C для скорости. Все эти кодеки могут использоваться напрямую через следующие функции.500501Многие из следующих API принимают два аргумента encoding и errors и имеют ту же семантику, что и одноимённые параметры конструктора встроенного строкового объекта [`str()`](https://python-all.ru/3.1/library/functions.html#str).502503Установка encoding в *NULL* приводит к использованию кодировки по умолчанию, которой является ASCII. Для кодирования имён файлов вызовы файловой системы должны использовать [`PyUnicode_FSConverter()`](https://python-all.ru/3.1/c-api/unicode.html#PyUnicode_FSConverter). Внутри используется переменная `Py_FileSystemDefaultEncoding`. Эту переменную следует считать доступной только для чтения: в одних системах это будет указатель на статическую строку, в других – она изменяется во время выполнения (например, когда приложение вызывает setlocale).504505Обработка ошибок задаётся параметром errors, который также может быть установлен в *NULL*, что означает использование обработки по умолчанию, определённой для кодера. Обработка ошибок по умолчанию для всех встроенных кодеров – «strict» (возбуждается [`ValueError`](https://python-all.ru/3.1/library/exceptions.html#ValueError)).506507Все кодеки используют похожий интерфейс. Для простоты документированы только отклонения от следующего общего описания.508509### Общие кодеки510511Это общие API кодеков:512513**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_Decode`(const char *\*s*, Py\_ssize\_t *size*, const char *\*encoding*, const char *\*errors*)**514515*Возвращаемое значение: новая ссылка.*516517Создаёт объект Unicode, декодируя *size* байтов закодированной строки *s*. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры встроенной функции `unicode()`. Используемый кодек ищется в реестре кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.518519**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_Encode`(const [Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*encoding*, const char *\*errors*)**520521*Возвращаемое значение: новая ссылка.*522523Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *s* заданного размера *size* и возвращает объект Python bytes. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода `encode()` объекта Unicode. Используемый кодек ищется в реестре кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.524525**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_AsEncodedString`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*unicode*, const char *\*encoding*, const char *\*errors*)**526527*Возвращаемое значение: новая ссылка.*528529Кодирует объект Unicode и возвращает результат в виде объекта Python bytes. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода `encode()` объекта Unicode. Используемый кодек ищется в реестре кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.530531### Кодеки UTF-8532533Это API кодеков UTF-8:534535**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF8`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**536537*Возвращаемое значение: новая ссылка.*538539Создаёт объект Unicode путём декодирования *size* байт строки, закодированной в UTF-8, *s*. Возвращает *NULL*, если кодек возбудил исключение.540541**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF8Stateful`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*, Py\_ssize\_t *\*consumed*)**542543*Возвращаемое значение: новая ссылка.*544545Если *consumed* равно *NULL*, ведёт себя как [`PyUnicode_DecodeUTF8()`](https://python-all.ru/3.1/c-api/unicode.html#PyUnicode_DecodeUTF8). Если *consumed* не равно *NULL*, завершающие неполные последовательности байт UTF-8 не будут считаться ошибкой. Эти байты не будут декодированы, а количество декодированных байт будет сохранено в *consumed*.546547**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_EncodeUTF8`(const [Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**548549*Возвращаемое значение: новая ссылка.*550551Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *s* заданного размера *size* с использованием UTF-8 и возвращает объект bytes Python. Возвращает *NULL*, если кодек возбудил исключение.552553**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_AsUTF8String`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*unicode*)**554555*Возвращаемое значение: новая ссылка.*556557Кодирует объект Unicode с использованием UTF-8 и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек возбудил исключение.558559### Кодеки UTF-32560561Это API кодеков UTF-32:562563**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF32`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *\*byteorder*)**564565Декодирует *size* байт из строки буфера в кодировке UTF-32 и возвращает соответствующий объект Unicode. *errors* (если не *NULL*) определяет обработку ошибок. По умолчанию используется «strict».566567Если *byteorder* не равен *NULL*, декодер начинает декодирование с использованием заданного порядка байтов:568569```c570*byteorder == -1: little endian571*byteorder == 0:  native order572*byteorder == 1:  big endian573```574575Если `*byteorder` равен нулю, и первые четыре байта входных данных являются маркером порядка байт (BOM), декодер переключается на этот порядок байт, и BOM не копируется в результирующую строку Unicode. Если `*byteorder` равен `-1` или `1`, любой маркер порядка байт копируется в выходные данные.576577После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных.578579В сборке с узким представлением кодовые точки за пределами BMP будут декодироваться как суррогатные пары.580581Если *byteorder* равен *NULL*, кодек запускается в режиме собственного порядка байтов.582583Возвращает *NULL*, если кодек сгенерировал исключение.584585**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF32Stateful`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *\*byteorder*, Py\_ssize\_t *\*consumed*)**586587Если588589*consumed*590591равен592593*NULL*594595, ведёт себя как596597[`PyUnicode_DecodeUTF32()`](https://python-all.ru/3.1/c-api/unicode.html#PyUnicode_DecodeUTF32)598599. Если600601*consumed*602603не равен604605*NULL*606607,608609[`PyUnicode_DecodeUTF32Stateful()`](https://python-all.ru/3.1/c-api/unicode.html#PyUnicode_DecodeUTF32Stateful)610611не будет считать неполные конечные последовательности байтов UTF-32 (например, количество байтов, не кратное четырём) ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в612613*consumed*614615.616617**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_EncodeUTF32`(const [Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *byteorder*)**618619Возвращает объект Python bytes, содержащий значение Unicode-данных из *s*, закодированное в UTF-32. Вывод записывается в соответствии со следующим порядком байтов:620621```c622byteorder == -1: little endian623byteorder == 0:  native byte order (writes a BOM mark)624byteorder == 1:  big endian625```626627Если `0`, выходная строка всегда начинается с метки BOM Unicode (U+FEFF). В двух других режимах метка BOM не добавляется.628629Если *Py\_UNICODE\_WIDE* не определён, суррогатные пары будут выводиться как одна кодовая точка.630631Возвращает *NULL*, если кодек сгенерировал исключение.632633**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_AsUTF32String`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*unicode*)**634635Возвращает Python-строку байт в кодировке UTF-32 с собственным порядком байтов. Строка всегда начинается с маркера BOM. Обработка ошибок – «strict». Возвращает636637*NULL*638639, если кодек сгенерировал исключение.640641### Кодеки UTF-32642643Это API кодеков UTF-32:644645**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF16`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *\*byteorder*)**646647*Возвращаемое значение: новая ссылка.*648649Декодирует *size* байт из строки буфера в кодировке UTF-16 и возвращает соответствующий объект Unicode. *errors* (если не *NULL*) определяет обработку ошибок. По умолчанию используется «strict».650651Если *byteorder* не равен *NULL*, декодер начинает декодирование с использованием заданного порядка байтов:652653```c654*byteorder == -1: little endian655*byteorder == 0:  native order656*byteorder == 1:  big endian657```658659Если `*byteorder` равен нулю и первые два байта входных данных являются меткой порядка байтов (BOM), декодер переключается на этот порядок байтов, и BOM не копируется в результирующую строку Unicode. Если `*byteorder` равен `-1` или `1`, любая метка порядка байтов копируется в выходные данные (в результате чего появится символ `\ufeff` или `\ufffe`).660661После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных.662663Если *byteorder* равен *NULL*, кодек запускается в режиме собственного порядка байтов.664665Возвращает *NULL*, если кодек сгенерировал исключение.666667**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF16Stateful`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *\*byteorder*, Py\_ssize\_t *\*consumed*)**668669*Возвращаемое значение: новая ссылка.*670671Если *consumed* равен *NULL*, ведёт себя как [`PyUnicode_DecodeUTF16()`](https://python-all.ru/3.1/c-api/unicode.html#PyUnicode_DecodeUTF16). Если *consumed* не равен *NULL*, [`PyUnicode_DecodeUTF16Stateful()`](https://python-all.ru/3.1/c-api/unicode.html#PyUnicode_DecodeUTF16Stateful) не будет считать неполные конечные последовательности байтов UTF-16 (например, нечётное количество байтов или разбитая суррогатная пара) ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.672673**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_EncodeUTF16`(const [Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *byteorder*)**674675*Возвращаемое значение: новая ссылка.*676677Возвращает объект Python bytes, содержащий значение Unicode-данных из *s*, закодированное в UTF-16. Вывод записывается в соответствии со следующим порядком байтов:678679```c680byteorder == -1: little endian681byteorder == 0:  native byte order (writes a BOM mark)682byteorder == 1:  big endian683```684685Если `0`, выходная строка всегда начинается с метки BOM Unicode (U+FEFF). В двух других режимах метка BOM не добавляется.686687Если *Py\_UNICODE\_WIDE* определён, одно значение [`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) может быть представлено как суррогатная пара. Если он не определён, каждое значение [`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) интерпретируется как символ UCS-2.688689Возвращает *NULL*, если кодек сгенерировал исключение.690691**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_AsUTF16String`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*unicode*)**692693*Возвращаемое значение: новая ссылка.*694695Возвращает Python-строку байт в кодировке UTF-16 с собственным порядком байтов. Строка всегда начинается с маркера BOM. Обработка ошибок – «strict». Возвращает *NULL*, если кодек сгенерировал исключение.696697### Кодеки UTF-7698699Это API кодеков UTF-7:700701**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF7`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**702703Создаёт объект Unicode путём декодирования704705*size*706707байт строки в кодировке UTF-7708709*s*710711. Возвращает712713*NULL*714715, если кодек сгенерировал исключение.716717**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF7Stateful`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*, Py\_ssize\_t *\*consumed*)**718719Если720721*consumed*722723равен724725*NULL*726727, ведёт себя как728729[`PyUnicode_DecodeUTF7()`](https://python-all.ru/3.1/c-api/unicode.html#PyUnicode_DecodeUTF7)730731. Если732733*consumed*734735не равен736737*NULL*738739, конечные неполные секции base-64 UTF-7 не будут считаться ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в740741*consumed*742743.744745**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_EncodeUTF7`(const [Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, int *base64SetO*, int *base64WhiteSpace*, const char *\*errors*)**746747Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) заданного размера с использованием UTF-7 и возвращает объект Python bytes. Возвращает *NULL*, если кодек вызвал исключение.748749Если *base64SetO* не равно нулю, «Set O» (знаки препинания, не имеющие иного особого значения) будут закодированы в base-64. Если *base64WhiteSpace* не равно нулю, пробельные символы будут закодированы в base-64. Оба параметра установлены в ноль для кодека Python «utf-7».750751### Кодеки Unicode-Escape752753Это API кодеков «Unicode Escape»:754755**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUnicodeEscape`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**756757*Возвращаемое значение: новая ссылка.*758759Создаёт объект Unicode путём декодирования *size* байт строки в кодировке Unicode-Escape *s*. Возвращает *NULL*, если кодек сгенерировал исключение.760761**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_EncodeUnicodeEscape`(const [Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*)**762763*Возвращаемое значение: новая ссылка.*764765Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) заданного размера с использованием Unicode-Escape и возвращает объект строки Python. Возвращает *NULL*, если кодек вызвал исключение.766767**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_AsUnicodeEscapeString`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*unicode*)**768769*Возвращаемое значение: новая ссылка.*770771Кодирует объект Unicode с использованием Unicode-Escape и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.772773### Кодеки Raw-Unicode-Escape774775Это API кодеков «Raw Unicode Escape»:776777**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_DecodeRawUnicodeEscape`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**778779*Возвращаемое значение: новая ссылка.*780781Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в Raw-Unicode-Escape. Возвращает *NULL*, если кодек вызвал исключение.782783**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_EncodeRawUnicodeEscape`(const [Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**784785*Возвращаемое значение: новая ссылка.*786787Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) заданного размера *size* с использованием Raw-Unicode-Escape и возвращает строковый объект Python. Возвращает *NULL*, если кодек вызвал исключение.788789**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_AsRawUnicodeEscapeString`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*unicode*)**790791*Возвращаемое значение: новая ссылка.*792793Кодирует объект Unicode с использованием Raw-Unicode-Escape и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.794795### Кодеки Latin-1796797Это API кодеков Latin-1: Latin-1 соответствует первым 256 кодовым позициям Unicode, и только они принимаются кодеками при кодировании.798799**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_DecodeLatin1`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**800801*Возвращаемое значение: новая ссылка.*802803Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в Latin-1. Возвращает *NULL*, если кодек вызвал исключение.804805**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_EncodeLatin1`(const [Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**806807*Возвращаемое значение: новая ссылка.*808809Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) заданного размера *size* с помощью Latin-1 и возвращает объект bytes Python. Возвращает *NULL*, если кодек вызвал исключение.810811**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_AsLatin1String`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*unicode*)**812813*Возвращаемое значение: новая ссылка.*814815Кодирует объект Unicode с помощью Latin-1 и возвращает результат как объект bytes Python. Обработка ошибок – “strict”. Возвращает *NULL*, если кодек вызвал исключение.816817### Кодеки ASCII818819Это API кодеков ASCII. Принимаются только 7-битные данные ASCII. Все остальные коды вызывают ошибки.820821**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_DecodeASCII`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**822823*Возвращаемое значение: новая ссылка.*824825Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в ASCII. Возвращает *NULL*, если кодек вызвал исключение.826827**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_EncodeASCII`(const [Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**828829*Возвращаемое значение: новая ссылка.*830831Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) заданного размера *size* с помощью ASCII и возвращает объект bytes Python. Возвращает *NULL*, если кодек вызвал исключение.832833**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_AsASCIIString`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*unicode*)**834835*Возвращаемое значение: новая ссылка.*836837Кодирует объект Unicode с помощью ASCII и возвращает результат как объект bytes Python. Обработка ошибок – “strict”. Возвращает *NULL*, если кодек вызвал исключение.838839### Кодеки с таблицей символов840841Этот кодек особенный, так как его можно использовать для реализации множества разных кодеков (именно так и были получены большинство стандартных кодеков, входящих в пакет `encodings`). Кодек использует отображение для кодирования и декодирования символов.842843Отображения для декодирования должны сопоставлять отдельные строковые символы отдельным символам Unicode, целым числам (которые затем интерпретируются как кодовые точки Unicode) или None (что означает «неопределённое отображение» и вызывает ошибку).844845Отображения для кодирования должны сопоставлять отдельные символы Unicode отдельным строковым символам, целым числам (которые затем интерпретируются как кодовые точки Latin-1) или None (что означает «неопределённое отображение» и вызывает ошибку).846847Объекты отображения должны поддерживать только интерфейс отображения \_\_getitem\_\_.848849Если при поиске символа возникает LookupError, символ копируется как есть; это означает, что его порядковое значение будет интерпретироваться как кодовая точка Unicode или Latin-1 соответственно. Из-за этого отображения должны содержать только те соответствия, которые переводят символы в другие кодовые точки.850851Это API кодеков отображения:852853**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_DecodeCharmap`(const char *\*s*, Py\_ssize\_t *size*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*mapping*, const char *\*errors*)**854855*Возвращаемое значение: новая ссылка.*856857Создаёт объект Unicode, декодируя *size* байт закодированной строки *s* с помощью заданного объекта *mapping*. Возвращает *NULL*, если кодек вызвал исключение. Если *mapping* равен *NULL*, выполняется декодирование Latin-1. В противном случае это может быть словарь, отображающий байты, или строка Unicode, которая интерпретируется как таблица поиска. Значения байтов, превышающие длину строки, и «символ» U+FFFE считаются «неопределённым отображением».858859**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_EncodeCharmap`(const [Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*mapping*, const char *\*errors*)**860861*Возвращаемое значение: новая ссылка.*862863Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) заданного размера *size* с помощью заданного объекта *mapping* и возвращает строковый объект Python. Возвращает *NULL*, если кодек вызвал исключение.864865**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_AsCharmapString`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*unicode*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*mapping*)**866867*Возвращаемое значение: новая ссылка.*868869Кодирует объект Unicode с помощью заданного объекта *mapping* и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.870871Следующее API кодека особенное тем, что отображает Unicode в Unicode.872873**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_TranslateCharmap`(const [Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*table*, const char *\*errors*)**874875*Возвращаемое значение: новая ссылка.*876877Переводит буфер [`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) заданного размера *size*, применяя к нему символьное отображение *table*, и возвращает результирующий объект Unicode. Возвращает *NULL*, если кодек вызвал исключение.878879Таблица *mapping* должна сопоставлять целочисленные кодовые точки Unicode целочисленным кодовым точкам Unicode или None (что приводит к удалению символа).880881Таблицам отображения достаточно реализовать интерфейс [`__getitem__()`](https://python-all.ru/3.1/reference/datamodel.html#object.__getitem__); словари и последовательности подходят. Неотображённые коды символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.1/library/exceptions.html#LookupError)) остаются без изменений и копируются как есть.882883### Кодеки MBCS для Windows884885Это API кодеков MBCS. В настоящее время они доступны только в Windows и используют преобразователи Win32 MBCS для выполнения преобразований. Обратите внимание, что MBCS (или DBCS) – это класс кодировок, а не одна конкретная. Целевая кодировка определяется пользовательскими настройками на машине, где выполняется кодек.886887**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_DecodeMBCS`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**888889*Возвращаемое значение: новая ссылка.*890891Создаёт объект Unicode, декодируя *size* байтов строки, закодированной в MBCS, из *s*. Возвращает *NULL*, если кодек вызвал исключение.892893**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_DecodeMBCSStateful`(const char *\*s*, int *size*, const char *\*errors*, int *\*consumed*)**894895Если896897*consumed*898899равен900901*NULL*902903, ведёт себя как904905[`PyUnicode_DecodeMBCS()`](https://python-all.ru/3.1/c-api/unicode.html#PyUnicode_DecodeMBCS)906907. Если908909*consumed*910911не равен912913*NULL*914915, то916917[`PyUnicode_DecodeMBCSStateful()`](https://python-all.ru/3.1/c-api/unicode.html#PyUnicode_DecodeMBCSStateful)918919не будет декодировать конечный ведущий байт, а количество декодированных байтов будет сохранено в920921*consumed*922923.924925**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_EncodeMBCS`(const [Py\_UNICODE](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**926927*Возвращаемое значение: новая ссылка.*928929Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) заданного размера *size* с помощью MBCS и возвращает объект bytes Python. Возвращает *NULL*, если кодек возбудил исключение.930931**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_AsMBCSString`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*unicode*)**932933*Возвращаемое значение: новая ссылка.*934935Кодирует объект Unicode с помощью MBCS и возвращает результат в виде объекта bytes Python. Обработка ошибок – "strict". Возвращает *NULL*, если кодек вызвал исключение.936937### Методы и слоты938939## Методы и слот-функции940941Следующие API могут обрабатывать объекты Unicode и строки на входе (в описаниях мы называем их строками) и возвращают объекты Unicode или целые числа по необходимости.942943Все они возвращают *NULL* или `-1` в случае исключения.944945**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_Concat`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*left*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*right*)**946947*Возвращаемое значение: новая ссылка.*948949Объединяет две строки, возвращая новую строку Unicode.950951**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_Split`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*s*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*sep*, Py\_ssize\_t *maxsplit*)**952953*Возвращаемое значение: новая ссылка.*954955Разделяет строку и возвращает список строк Unicode. Если *sep* равен *NULL*, разделение происходит по всем подстрокам из пробельных символов. В противном случае разделение выполняется по указанному разделителю. Выполняется не более *maxsplit* разделений. Если значение отрицательное, ограничение не устанавливается. Разделители не включаются в результирующий список.956957**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_Splitlines`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*s*, int *keepend*)**958959*Возвращаемое значение: новая ссылка.*960961Разделяет строку Unicode по символам перевода строки и возвращает список строк Unicode. CRLF считается одним переносом строки. Если *keepend* равен 0, символы перевода строки не включаются в результирующие строки.962963**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_Translate`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*str*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*table*, const char *\*errors*)**964965*Возвращаемое значение: новая ссылка.*966967Переводит строку, применяя к ней таблицу отображения символов, и возвращает результирующий объект Unicode.968969Таблица отображения должна сопоставлять целочисленные коды Unicode другим целочисленным кодам Unicode или None (что приводит к удалению символа).970971Таблицам отображения достаточно реализовать интерфейс [`__getitem__()`](https://python-all.ru/3.1/reference/datamodel.html#object.__getitem__); словари и последовательности подходят. Неотображённые коды символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.1/library/exceptions.html#LookupError)) остаются без изменений и копируются как есть.972973*errors* имеет обычное для кодеков значение. Может быть *NULL*, что означает использование обработки ошибок по умолчанию.974975**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_Join`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*separator*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*seq*)**976977*Возвращаемое значение: новая ссылка.*978979Объединяет последовательность строк, используя заданный *разделитель*, и возвращает полученную Unicode-строку.980981**int `PyUnicode_Tailmatch`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*str*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*substr*, Py\_ssize\_t *start*, Py\_ssize\_t *end*, int *direction*)**982983Возвращает 1, если984985*substr*986987совпадает с988989`str[start:end]`990991на указанном конце (992993*direction*994995== -1 означает поиск по префиксу,996997*direction*998999== 1 – поиск по суффиксу), и 0 в противном случае. Возвращает10001001`-1`10021003, если произошла ошибка.10041005**Py\_ssize\_t `PyUnicode_Find`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*str*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*substr*, Py\_ssize\_t *start*, Py\_ssize\_t *end*, int *direction*)**10061007Возвращает первую позицию10081009*substr*10101011в10121013`str[start:end]`10141015, используя заданное10161017*direction*10181019(10201021*direction*10221023== 1 означает прямой поиск,10241025*direction*10261027== -1 – обратный). Возвращаемое значение – индекс первого совпадения; значение10281029`-1`10301031означает, что совпадений не найдено, а10321033`-2`10341035– что произошла ошибка и было установлено исключение.10361037**Py\_ssize\_t `PyUnicode_Count`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*str*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*substr*, Py\_ssize\_t *start*, Py\_ssize\_t *end*)**10381039Возвращает количество непересекающихся вхождений10401041*substr*10421043в10441045`str[start:end]`10461047. Возвращает10481049`-1`10501051, если произошла ошибка.10521053**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_Replace`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*str*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*substr*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*replstr*, Py\_ssize\_t *maxcount*)**10541055*Возвращаемое значение: новая ссылка.*10561057Заменяет не более *maxcount* вхождений *substr* в *str* на *replstr* и возвращает результирующий объект Unicode. *maxcount* == -1 означает замену всех вхождений.10581059**int `PyUnicode_Compare`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*left*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*right*)**10601061Сравнивает две строки и возвращает -1, 0, 1 для случаев «меньше», «равно» и «больше» соответственно.10621063**int `PyUnicode_CompareWithASCIIString`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*uni*, char *\*string*)**10641065Сравнивает объект Unicode10661067*uni*10681069со строкой10701071*string*10721073и возвращает -1, 0, 1 для меньше чем, равно и больше соответственно.10741075**int `PyUnicode_RichCompare`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*left*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*right*, int *op*)**10761077Выполняет расширенное сравнение двух строк unicode и возвращает одно из следующих значений:10781079- `NULL` в случае возбуждения исключения1080- [`Py_True`](https://python-all.ru/3.1/c-api/bool.html#Py_True) или [`Py_False`](https://python-all.ru/3.1/c-api/bool.html#Py_False) для успешных сравнений1081- `Py_NotImplemented` в случае, если комбинация типов неизвестна10821083Обратите внимание, что сравнения с `Py_EQ` и `Py_NE` могут вызвать [`UnicodeWarning`](https://python-all.ru/3.1/library/exceptions.html#UnicodeWarning), если преобразование аргументов в Unicode завершится ошибкой с [`UnicodeDecodeError`](https://python-all.ru/3.1/library/exceptions.html#UnicodeDecodeError).10841085Возможные значения для *op*: `Py_GT`, `Py_GE`, `Py_EQ`, `Py_NE`, `Py_LT` и `Py_LE`.10861087**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_Format`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*format*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*args*)**10881089*Возвращаемое значение: новая ссылка.*10901091Возвращает новый строковый объект из *format* и *args*; это аналогично `format % args`. Аргумент *args* должен быть кортежем.10921093**int `PyUnicode_Contains`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*container*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*element*)**10941095Проверяет, содержится ли *element* в *container*, и возвращает true или false соответственно.10961097*element* должен преобразовываться в односимвольную строку Unicode. Если произошла ошибка, возвращается `-1`.10981099**void `PyUnicode_InternInPlace`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*\*string*)**11001101Интернирует аргумент11021103*\*string*11041105на месте. Аргумент должен быть адресом переменной-указателя, указывающей на объект строки Unicode Python. Если уже существует интернированная строка, совпадающая с11061107*\*string*11081109, то она устанавливает11101111*\*string*11121113на эту строку (уменьшая счётчик ссылок старого строкового объекта и увеличивая счётчик интернированной строки); в противном случае она оставляет11141115*\*string*11161117без изменений и интернирует её (увеличивая её счётчик ссылок). (Уточнение: хотя много говорится о счётчиках ссылок, считайте эту функцию нейтральной к счётчикам ссылок – вы владеете объектом после вызова, только если владели им до вызова.)11181119**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyUnicode_InternFromString`(const char *\*v*)**11201121Комбинация11221123[`PyUnicode_FromString()`](https://python-all.ru/3.1/c-api/unicode.html#PyUnicode_FromString)11241125и11261127[`PyUnicode_InternInPlace()`](https://python-all.ru/3.1/c-api/unicode.html#PyUnicode_InternInPlace)11281129, возвращающая либо новый объект строки Unicode, который был интернирован, либо новую («владетельную») ссылку на ранее интернированный строковый объект с тем же значением.1130