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

Тип Unicode

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

PyTypeObject PyUnicode_Type

Входит в стабильный ABI.

Этот экземпляр PyTypeObject представляет тип Unicode в Python. В коде Python он доступен как str.

PyTypeObject PyUnicodeIter_Type

Входит в стабильный ABI.

Этот экземпляр PyTypeObject представляет тип итератора Unicode в Python. Он используется для перебора объектов строк Unicode.

type Py_UCS4

type Py_UCS2

type Py_UCS1

Входит в стабильный ABI.

Эти типы являются псевдонимами беззнаковых целочисленных типов, достаточно широких для хранения символов размером соответственно 32, 16 и 8 бит. При работе с отдельными символами Unicode используйте Py_UCS4.

Добавлено в версии 3.3.

type PyASCIIObject

type PyCompactUnicodeObject

type PyUnicodeObject

Эти подтипы PyObject представляют объект Unicode в Python. Почти во всех случаях их не следует использовать напрямую, поскольку все функции API, работающие с объектами Unicode, принимают и возвращают указатели PyObject.

Добавлено в версии 3.3.

Структуру конкретного объекта можно определить с помощью следующих макросов. Макросы не могут завершиться с ошибкой; если аргумент не является объектом Unicode в Python, их поведение не определено.

PyUnicode_IS_COMPACT(o)

Истина, если o использует структуру PyCompactUnicodeObject.

Добавлено в версии 3.3.

PyUnicode_IS_COMPACT_ASCII(o)

Истина, если o использует структуру PyASCIIObject.

Добавлено в версии 3.3.

Следующие API — это макросы C и статические встроенные функции для быстрой проверки и доступа к внутренним данным объектов Unicode, доступным только для чтения:

int PyUnicode_Check(PyObject *obj)

Возвращает true, если объект obj является объектом Unicode или экземпляром подтипа Unicode. Эта функция всегда завершается успешно.

int PyUnicode_CheckExact(PyObject *obj)

Возвращает true, если объект obj является объектом Unicode, но не экземпляром подтипа. Эта функция всегда завершается успешно.

Py_ssize_t PyUnicode_GET_LENGTH(PyObject *unicode)

Возвращает длину строки Unicode в кодовых точках. unicode должен быть объектом Unicode в «каноническом» представлении (проверка не выполняется).

Добавлено в версии 3.3.

Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *unicode)

Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *unicode)

Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *unicode)

Возвращает указатель на каноническое представление, приведённое к целочисленным типам UCS1, UCS2 или UCS4, для прямого доступа к символам. Проверки соответствия размера символа каноническому представлению не выполняются; для выбора подходящей функции используйте PyUnicode_KIND().

Добавлено в версии 3.3.

PyUnicode_1BYTE_KIND

PyUnicode_2BYTE_KIND

PyUnicode_4BYTE_KIND

Возвращаемые значения макроса PyUnicode_KIND().

Добавлено в версии 3.3.

Изменено в версии 3.12: PyUnicode_WCHAR_KIND удалён.

int PyUnicode_KIND(PyObject *unicode)

Возвращает одну из констант PyUnicode kind (см. выше), указывающих, сколько байт на символ использует этот объект Unicode для хранения данных. unicode должен быть объектом Unicode в «каноническом» представлении (проверка не выполняется).

Добавлено в версии 3.3.

void *PyUnicode_DATA(PyObject *unicode)

Возвращает указатель void на необработанный буфер Unicode. unicode должен быть объектом Unicode в «каноническом» представлении (проверка не выполняется).

Добавлено в версии 3.3.

void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)

Записывает кодовую точку value по указанному индексу index строки (индексация начинается с нуля).

Значение kind и указатель data должны быть получены из строки с помощью PyUnicode_KIND() и PyUnicode_DATA() соответственно. При вызове PyUnicode_WRITE() необходимо удерживать ссылку на эту строку. Также применяются все требования PyUnicode_WriteChar().

Функция не проверяет соблюдение каких-либо своих требований и предназначена для использования в циклах.

Добавлено в версии 3.3.

Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)

Считывает кодовую точку из канонического представления data (полученного с помощью PyUnicode_DATA()). Проверки и вызовы ready не выполняются.

Добавлено в версии 3.3.

Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)

Считывает символ из объекта Unicode unicode, который должен быть в «каноническом» представлении. При нескольких последовательных чтениях это менее эффективно, чем PyUnicode_READ().

Добавлено в версии 3.3.

Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *unicode)

Возвращает максимальную кодовую точку, подходящую для создания другой строки на основе unicode, который должен быть в «каноническом» представлении. Это значение всегда является приближённым, но его вычисление эффективнее перебора строки.

Добавлено в версии 3.3.

int PyUnicode_IsIdentifier(PyObject *unicode)

Входит в стабильный ABI.

Возвращает 1, если строка является допустимым идентификатором согласно определению языка, разделу Имена (идентификаторы и ключевые слова). В противном случае возвращает 0.

Изменено в версии 3.9: Функция больше не вызывает Py_FatalError(), если строка не готова.

unsigned int PyUnicode_IS_ASCII(PyObject *unicode)

Возвращает true, если строка содержит только символы ASCII. Эквивалентно str.isascii().

Добавлено в версии 3.2.

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

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

int Py_UNICODE_ISSPACE(Py_UCS4 ch)

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

int Py_UNICODE_ISLOWER(Py_UCS4 ch)

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

int Py_UNICODE_ISUPPER(Py_UCS4 ch)

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

int Py_UNICODE_ISTITLE(Py_UCS4 ch)

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

int Py_UNICODE_ISLINEBREAK(Py_UCS4 ch)

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

int Py_UNICODE_ISDECIMAL(Py_UCS4 ch)

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

int Py_UNICODE_ISDIGIT(Py_UCS4 ch)

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

int Py_UNICODE_ISNUMERIC(Py_UCS4 ch)

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

int Py_UNICODE_ISALPHA(Py_UCS4 ch)

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

int Py_UNICODE_ISALNUM(Py_UCS4 ch)

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

int Py_UNICODE_ISPRINTABLE(Py_UCS4 ch)

Возвращает 1 или 0 в зависимости от того, является ли ch печатным символом в смысле str.isprintable().

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

Py_UCS4 Py_UNICODE_TOLOWER(Py_UCS4 ch)

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

Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4 ch)

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

Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4 ch)

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

int Py_UNICODE_TODECIMAL(Py_UCS4 ch)

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

int Py_UNICODE_TODIGIT(Py_UCS4 ch)

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

double Py_UNICODE_TONUMERIC(Py_UCS4 ch)

Возвращает символ ch, преобразованный в число с плавающей точкой двойной точности. Если это невозможно, возвращает -1.0. Эта функция не вызывает исключений.

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

int Py_UNICODE_IS_SURROGATE(Py_UCS4 ch)

Проверяет, является ли ch суррогатом (0xD800 <= ch <= 0xDFFF).

int Py_UNICODE_IS_HIGH_SURROGATE(Py_UCS4 ch)

Проверяет, является ли ch старшим суррогатом (0xD800 <= ch <= 0xDBFF).

int Py_UNICODE_IS_LOW_SURROGATE(Py_UCS4 ch)

Проверяет, является ли ch младшим суррогатом (0xDC00 <= ch <= 0xDFFF).

Py_UCS4 Py_UNICODE_HIGH_SURROGATE(Py_UCS4 ch)

Возвращает старший суррогат UTF-16 (от 0xD800 до 0xDBFF) для кодовой точки Unicode в диапазоне [0x10000; 0x10FFFF].

Py_UCS4 Py_UNICODE_LOW_SURROGATE(Py_UCS4 ch)

Возвращает младший суррогат UTF-16 (от 0xDC00 до 0xDFFF) для кодовой точки Unicode в диапазоне [0x10000; 0x10FFFF].

Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)

Объединяет две кодовые точки-суррогата и возвращает одно значение Py_UCS4. high и low — соответственно ведущий и замыкающий суррогаты в суррогатной паре. high должен находиться в диапазоне [0xD800; 0xDBFF], а low — в диапазоне [0xDC00; 0xDFFF].

Создание строк Unicode и доступ к ним

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

PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)

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

Создайте новый объект Unicode. maxchar должен быть максимальным кодом символа, который будет помещён в строку. Для приблизительной оценки его можно округлить вверх до ближайшего значения в последовательности 127, 255, 65535, 1114111.

При ошибке установите исключение и верните NULL.

После создания строку можно заполнить с помощью PyUnicode_WriteChar(), PyUnicode_CopyCharacters(), PyUnicode_Fill(), PyUnicode_WRITE() или аналогичных функций. Поскольку строки считаются неизменяемыми, не используйте результат во время его изменения. В частности, пока строка не заполнена окончательным содержимым:

• её нельзя хешировать,
• её нельзя преобразовывать с помощью converted to UTF-8 или в другое неканоническое представление,
• нельзя изменять её счётчик ссылок,
• её нельзя передавать коду, который может выполнить что-либо из перечисленного выше.

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

Чтобы случайно не предоставить доступ к частично записанному объекту строки, предпочтительно использовать API PyUnicodeWriter или одну из приведённых ниже функций PyUnicode_From*.

Добавлено в версии 3.3.

PyObject *PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)

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

Создайте новый объект Unicode с указанным kind (возможные значения — PyUnicode_1BYTE_KIND и т. д., возвращаемые функцией PyUnicode_KIND()). buffer должен указывать на массив из size элементов размером 1, 2 или 4 байта на символ, в соответствии с указанным видом.

При необходимости входной buffer копируется и преобразуется в каноническое представление. Например, если buffer — строка UCS4 (PyUnicode_4BYTE_KIND) и она состоит только из кодовых точек диапазона UCS1, она будет преобразована в UCS1 (PyUnicode_1BYTE_KIND).

Добавлено в версии 3.3.

PyObject *PyUnicode_FromStringAndSize(const char *str, Py_ssize_t size)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

Создайте объект Unicode из буфера символов str. Байты будут интерпретироваться как закодированные в UTF-8. Буфер копируется в новый объект. Возвращаемое значение может быть совместно используемым объектом, то есть изменять данные нельзя.

Эта функция вызывает SystemError в следующих случаях:

• size < 0,
• str равен NULL, а size > 0

Изменено в версии 3.12: использование str == NULL при size > 0 больше не допускается.

PyObject *PyUnicode_FromString(const char *str)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

Создайте объект Unicode из буфера символов str, закодированного в UTF-8 и завершающегося нулевым символом.

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

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

Спецификатор преобразования состоит из двух или более символов и содержит следующие компоненты, которые должны идти в указанном порядке:

1. Символ '%', обозначающий начало спецификатора.
2. Флаги преобразования (необязательно), влияющие на результат некоторых типов преобразования.
3. Минимальная ширина поля (необязательно). Если задана как '*' (звёздочка), фактическая ширина задаётся следующим аргументом, который должен иметь тип int; объект для преобразования указывается после минимальной ширины поля и необязательной точности.
4. Точность (необязательно), задаваемая как '.' (точка) с последующим значением точности. Если задана как '*' (звёздочка), фактическая точность задаётся следующим аргументом, который должен иметь тип int; значение для преобразования указывается после точности.
5. Модификатор длины (необязательно).
6. Тип преобразования.

Символы флагов преобразования:

Флаг	Значение
0	Для числовых значений преобразование дополняется нулями.
-	Преобразованное значение выравнивается по левому краю (переопределяет флаг 0, если указаны оба).

Модификаторы длины для следующих преобразований целых чисел (d, i, o, u, x или X) задают тип аргумента (по умолчанию int):

Модификатор	Типы
l	long или unsigned long
ll	long long или unsigned long long
j	intmax_t или uintmax_t
z	size_t или ssize_t
t	ptrdiff_t

Модификатор длины l для следующих преобразований s или V указывает, что тип аргумента — const wchar_t*.

Спецификаторы преобразования:

Спецификатор преобразования	Тип	Комментарий
%	не применимо	Буквальный символ %.
d, i	Задаётся модификатором длины	Десятичное представление знакового целого числа C.
u	Задаётся модификатором длины	Десятичное представление беззнакового целого числа C.
o	Задаётся модификатором длины	Восьмеричное представление беззнакового целого числа C.
x	Задаётся модификатором длины	Шестнадцатеричное представление беззнакового целого числа C (строчными буквами).
X	Задаётся модификатором длины	Шестнадцатеричное представление беззнакового целого числа C (прописными буквами).
c	int	Один символ.
s	const char* или const wchar_t*	Массив символов C, завершающийся нулевым символом.
p	const void*	Шестнадцатеричное представление указателя C. В основном эквивалентно printf("%p"), но гарантированно начинается с буквального 0x независимо от результата printf на данной платформе.
A	PyObject*	Результат вызова ascii().
U	PyObject*	Объект Unicode.
V	PyObject*, const char* или const wchar_t*	Объект Unicode (который может быть NULL) и массив символов C, завершающийся нулевым символом, в качестве второго параметра (он будет использоваться, если первый параметр равен NULL).
S	PyObject*	Результат вызова PyObject_Str().
R	PyObject*	Результат вызова PyObject_Repr().
T	PyObject*	Получить полное имя объекта типа; вызвать PyType_GetFullyQualifiedName().
#T	PyObject*	Аналогично формату T, но в качестве разделителя между именем модуля и полным именем используется двоеточие (:).
N	PyTypeObject*	Получить полное имя типа; вызвать PyType_GetFullyQualifiedName().
#N	PyTypeObject*	Аналогично формату N, но в качестве разделителя между именем модуля и полным именем используется двоеточие (:).

Примечание

Единицей измерения ширины является число символов, а не байтов. Единицей измерения точности является число байтов или элементов wchar_t (если используется модификатор длины l) для "%s" и "%V" (если аргумент PyObject* равен NULL), а также число символов для "%A", "%U", "%S", "%R" и "%V" (если аргумент PyObject* не равен NULL).

Примечание

В отличие от C printf(), флаг 0 действует даже при заданной точности для преобразований целых чисел (d, i, u, o, x или X).

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

Изменено в версии 3.3: добавлена поддержка "%li", "%lli" и "%zi".

Изменено в версии 3.4: добавлена поддержка форматирования ширины и точности для "%s", "%A", "%U", "%V", "%S", "%R".

Изменено в версии 3.12: добавлена поддержка спецификаторов преобразования o и X. Добавлена поддержка модификаторов длины j и t. Теперь модификаторы длины применяются ко всем преобразованиям целых чисел. Модификатор длины l теперь применяется к спецификаторам преобразования s и V. Добавлена поддержка переменной ширины и точности *. Добавлена поддержка флага -.

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

Изменено в версии 3.13: добавлена поддержка форматов %T, %#T, %N и %#N.

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

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

Идентична PyUnicode_FromFormat(), но принимает ровно два аргумента.

PyObject *PyUnicode_FromObject(PyObject *obj)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

При необходимости скопируйте экземпляр подкласса Unicode в новый объект Unicode. Если obj уже является полноценным объектом Unicode (не подклассом), верните новую сильную ссылку на объект.

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

PyObject *PyUnicode_FromOrdinal(int ordinal)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

Создайте объект Unicode из заданной кодовой точки Unicode ordinal.

Порядковый номер должен находиться в диапазоне range(0x110000). Если это не так, вызывается исключение ValueError.

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

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

Декодируйте закодированный объект obj в объект Unicode.

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

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

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

void PyUnicode_Append(PyObject **p_left, PyObject *right)

Часть стабильного ABI.

Добавьте строку right в конец p_left. p_left должен указывать на сильную ссылку на объект Unicode; PyUnicode_Append() освобождает (то есть «забирает») эту ссылку.

При ошибке установите для *p_left значение NULL и установите исключение.

При успешном выполнении присвойте *p_left новую сильную ссылку на результат.

void PyUnicode_AppendAndDel(PyObject **p_left, PyObject *right)

Часть стабильного ABI.

Функция аналогична PyUnicode_Append(), но уменьшает счётчик ссылок right на единицу.

PyObject *PyUnicode_BuildEncodingMap(PyObject *string)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

Верните таблицу соответствий, подходящую для декодирования пользовательской однобайтовой кодировки. Для строки Unicode string длиной не более 256 символов, представляющей таблицу кодировки, возвращается компактный внутренний объект соответствий либо словарь, сопоставляющий порядковые номера символов значениям байтов. При некорректных входных данных вызывается исключение TypeError и возвращается NULL.

Добавлено в версии 3.2.

const char *PyUnicode_GetDefaultEncoding(void)

Часть стабильного ABI.

Верните имя кодировки строк по умолчанию: "utf-8". См. sys.getdefaultencoding().

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

Py_ssize_t PyUnicode_GetLength(PyObject *unicode)

Часть стабильного ABI начиная с версии 3.7.

Верните длину объекта Unicode в кодовых точках.

При ошибке установите исключение и верните -1.

Добавлено в версии 3.3.

Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t from_start, Py_ssize_t how_many)

Скопируйте символы из одного объекта Unicode в другой. Эта функция при необходимости преобразует символы и, если возможно, использует memcpy(). При ошибке возвращает -1 и устанавливает исключение; в противном случае возвращает количество скопированных символов.

Строка ещё не должна была использоваться. Подробности см. в описании PyUnicode_New().

Добавлено в версии 3.3.

int PyUnicode_Resize(PyObject **unicode, Py_ssize_t length);

Часть стабильного ABI.

Измените размер объекта Unicode *unicode, задав новую length в кодовых точках.

Попытайтесь изменить размер строки на месте (обычно это быстрее, чем выделять память для новой строки и копировать символы) либо создайте новую строку.

*unicode изменяется так, чтобы указывать на новый объект (с изменённым размером); при успехе возвращается 0. В противном случае возвращается -1 и устанавливается исключение, а *unicode остаётся без изменений.

Функция не проверяет содержимое строки; результат может не быть строкой в каноническом представлении.

Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)

Заполните строку символом: запишите fill_char в unicode[start:start+length].

Операция завершается ошибкой, если fill_char больше максимального символа строки или если у строки больше одной ссылки.

Строка ещё не должна была использоваться. Подробности см. в описании PyUnicode_New().

Верните число записанных символов либо верните -1 и вызовите исключение при ошибке.

Добавлено в версии 3.3.

int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)

Часть стабильного ABI начиная с версии 3.7.

Запишите character в строку unicode по индексу index, отсчитываемому от нуля. При успехе верните 0; при ошибке верните -1 и установите исключение.

Эта функция проверяет, что unicode является объектом Unicode, индекс не выходит за границы, а счётчик ссылок объекта равен единице. Вариант PyUnicode_WRITE() пропускает эти проверки, поэтому выполнять их должны вы.

Строка ещё не должна была использоваться. Подробности см. в описании PyUnicode_New().

Добавлено в версии 3.3.

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)

Часть стабильного ABI начиная с версии 3.7.

Прочитайте символ из строки. В отличие от PyUnicode_READ_CHAR(), которая не выполняет проверку ошибок, эта функция проверяет, что unicode является объектом Unicode и индекс не выходит за границы.

При успехе верните символ; при ошибке верните -1 и установите исключение.

Добавлено в версии 3.3.

PyObject *PyUnicode_Substring(PyObject *unicode, Py_ssize_t start, Py_ssize_t end)

Возвращаемое значение: новая ссылка.Часть стабильного ABI начиная с версии 3.7.

Верните подстроку объекта unicode от индекса символа start (включительно) до индекса символа end (не включительно). Отрицательные индексы не поддерживаются. При ошибке установите исключение и верните NULL.

Добавлено в версии 3.3.

Py_UCS4 *PyUnicode_AsUCS4(PyObject *unicode, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)

Часть стабильного ABI начиная с версии 3.7.

Скопируйте строку unicode в буфер UCS4, добавив нулевой символ, если установлен параметр copy_null. При ошибке возвращается NULL и устанавливается исключение (в частности, SystemError, если buflen меньше длины unicode). При успехе возвращается buffer.

Добавлено в версии 3.3.

Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)

Часть стабильного ABI начиная с версии 3.7.

Копирует строку unicode в новый буфер UCS4, выделенный с помощью PyMem_Malloc(). В случае сбоя возвращается NULL и устанавливается MemoryError. К возвращаемому буферу всегда добавляется дополнительная нулевая кодовая точка.

Добавлено в версии 3.3.

Кодировка локали

Текущую кодировку локали можно использовать для декодирования текста из операционной системы.

PyObject *PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t length, const char *errors)

Возвращаемое значение: новая ссылка. Часть стабильного ABI начиная с версии 3.7.

Декодирует строку из UTF-8 на Android и VxWorks либо из текущей кодировки локали на других платформах. Поддерживаются обработчики ошибок "strict" и "surrogateescape" (PEP 383). Если errors имеет значение NULL, декодер использует обработчик ошибок "strict". str должна оканчиваться нулевым символом, но не может содержать встроенные нулевые символы.

Используйте PyUnicode_DecodeFSDefaultAndSize() для декодирования строки с использованием кодировки файловой системы и обработчика ошибок.

Эта функция игнорирует режим UTF-8 Python.

См. также

Функцию Py_DecodeLocale().

Добавлено в версии 3.3.

Изменено в версии 3.7: Теперь функция также использует текущую кодировку локали для обработчика ошибок surrogateescape, за исключением Android. Ранее для surrogateescape использовалась Py_DecodeLocale(), а для strict — текущая кодировка локали.

PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors)

Возвращаемое значение: новая ссылка. Часть стабильного ABI начиная с версии 3.7.

Аналогична PyUnicode_DecodeLocaleAndSize(), но вычисляет длину строки с помощью strlen().

Добавлено в версии 3.3.

PyObject *PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)

Возвращаемое значение: новая ссылка. Часть стабильного ABI начиная с версии 3.7.

Кодирует объект Unicode в UTF-8 на Android и VxWorks либо в текущую кодировку локали на других платформах. Поддерживаются обработчики ошибок "strict" и "surrogateescape" (PEP 383). Если errors имеет значение NULL, кодировщик использует обработчик ошибок "strict". Возвращает объект bytes. unicode не может содержать встроенные нулевые символы.

Используйте PyUnicode_EncodeFSDefault() для кодирования строки с использованием кодировки файловой системы и обработчика ошибок.

Эта функция игнорирует режим UTF-8 Python.

См. также

Функцию Py_EncodeLocale().

Добавлено в версии 3.3.

Изменено в версии 3.7: Теперь функция также использует текущую кодировку локали для обработчика ошибок surrogateescape, за исключением Android. Ранее для surrogateescape использовалась Py_EncodeLocale(), а для strict — текущая кодировка локали.

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

Функции кодирования и декодирования с использованием кодировки файловой системы и обработчика ошибок (PEP 383 и PEP 529).

Для кодирования имён файлов в bytes при разборе аргументов следует использовать преобразователь "O&", передав PyUnicode_FSConverter() в качестве функции преобразования:

int PyUnicode_FSConverter(PyObject *obj, void *result)

Часть стабильного ABI.

Преобразователь PyArg_Parse*: кодирует объекты str — полученные напрямую или через интерфейс os.PathLike — в bytes с помощью PyUnicode_EncodeFSDefault(); объекты bytes возвращаются без изменений. result должен быть адресом переменной C типа PyObject* (или PyBytesObject*). В случае успеха переменной присваивается новая сильная ссылка на объект bytes, которую необходимо освободить, когда она больше не используется; функция возвращает ненулевое значение (Py_CLEANUP_SUPPORTED). Встроенные нулевые байты в результате не допускаются. В случае сбоя возвращается 0 и устанавливается исключение.

Если obj имеет значение NULL, функция освобождает сильную ссылку, сохранённую в переменной, на которую указывает result, и возвращает 1.

Добавлено в версии 3.1.

Изменено в версии 3.6: Поддерживает объекты, подобные путям.

Для декодирования имён файлов в str при разборе аргументов следует использовать преобразователь "O&", передав PyUnicode_FSDecoder() в качестве функции преобразования:

int PyUnicode_FSDecoder(PyObject *obj, void *result)

Часть стабильного ABI.

Преобразователь PyArg_Parse*: декодирует объекты bytes — полученные напрямую или косвенно через интерфейс os.PathLike — в str с помощью PyUnicode_DecodeFSDefaultAndSize(); объекты str возвращаются без изменений. result должен быть адресом переменной C типа PyObject* (или PyUnicodeObject*). В случае успеха переменной присваивается новая сильная ссылка на объект Unicode, которую необходимо освободить, когда она больше не используется; функция возвращает ненулевое значение (Py_CLEANUP_SUPPORTED). Встроенные нулевые символы в результате не допускаются. В случае сбоя возвращается 0 и устанавливается исключение.

Если obj имеет значение NULL, освободите сильную ссылку на объект, на который указывает result, и верните 1.

Добавлено в версии 3.2.

Изменено в версии 3.6: Поддерживает объекты, подобные путям.

PyObject *PyUnicode_DecodeFSDefaultAndSize(const char *str, Py_ssize_t size)

Возвращаемое значение: новая ссылка.Часть стабильного ABI.

Декодирует строку с использованием кодировки файловой системы и обработчика ошибок.

Если необходимо декодировать строку с использованием текущей кодировки локали, используйте PyUnicode_DecodeLocaleAndSize().

См. также

Функцию Py_DecodeLocale().

Изменено в версии 3.6: Теперь используется обработчик ошибок файловой системы.

PyObject *PyUnicode_DecodeFSDefault(const char *str)

Возвращаемое значение: новая ссылка.Часть стабильного ABI.

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

Если длина строки известна, используйте PyUnicode_DecodeFSDefaultAndSize().

Изменено в версии 3.6: Теперь используется обработчик ошибок файловой системы.

PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)

Возвращаемое значение: новая ссылка.Часть стабильного ABI.

Кодирует объект Unicode с использованием кодировки файловой системы и обработчика ошибок и возвращает bytes. Обратите внимание, что полученный объект bytes может содержать нулевые байты.

Если необходимо закодировать строку с использованием текущей кодировки локали, используйте PyUnicode_EncodeLocale().

См. также

Функцию Py_EncodeLocale().

Добавлено в версии 3.2.

Изменено в версии 3.6: Теперь используется обработчик ошибок файловой системы.

Поддержка wchar_t

Поддержка wchar_t для платформ, на которых она доступна:

PyObject *PyUnicode_FromWideChar(const wchar_t *wstr, Py_ssize_t size)

Возвращаемое значение: новая ссылка.Часть стабильного ABI.

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

Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *wstr, Py_ssize_t size)

Часть стабильного ABI.

Копирует содержимое объекта Unicode в буфер wchar_t wstr. Копируется не более size символов wchar_t (без учёта возможного завершающего нулевого символа). Возвращает количество скопированных символов wchar_t или -1 в случае ошибки.

Если wstr имеет значение NULL, вместо этого возвращает size, необходимый для хранения всего объекта unicode, включая завершающий нулевой символ.

Обратите внимание, что результирующая строка wchar_t* может быть завершена нулевым символом, а может и не быть. Если приложению требуется завершающий нулевой символ, вызывающая сторона должна убедиться, что строка wchar_t* им завершается. Кроме того, строка wchar_t* может содержать нулевые символы, из-за которых при использовании с большинством функций C строка будет усечена.

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

Часть стабильного ABI начиная с версии 3.7.

Преобразует объект Unicode в широкосимвольную строку. Выходная строка всегда заканчивается нулевым символом. Если size не имеет значения NULL, количество широких символов (без учёта завершающего нулевого символа) записывается в *size. Обратите внимание, что результирующая строка wchar_t может содержать нулевые символы, из-за которых при использовании с большинством функций C строка будет усечена. Если size имеет значение NULL, а строка wchar_t* содержит нулевые символы, возбуждается исключение ValueError.

В случае успеха возвращает буфер, выделенный с помощью PyMem_New (для освобождения используйте PyMem_Free()). В случае ошибки возвращает NULL, а значение *size не определено. Если выделить память не удалось, возбуждается исключение MemoryError.

Добавлено в версии 3.2.

Изменено в версии 3.7: Если size имеет значение NULL, а строка wchar_t* содержит нулевые символы, возбуждается исключение ValueError.

Общие кодеки

Предоставляется следующий макрос:

Py_UNICODE_REPLACEMENT_CHARACTER

Кодовая точка Unicode U+FFFD (символ замены).

Этот символ Unicode используется в качестве символа замены при декодировании, если аргумент errors имеет значение «replace».

Общие API кодеков:

PyObject *PyUnicode_Decode(const char *str, Py_ssize_t size, const char *encoding, const char *errors)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

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

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

Кодеки UTF-8

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

PyObject *PyUnicode_DecodeUTF8(const char *str, Py_ssize_t size, const char *errors)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

PyObject *PyUnicode_DecodeUTF8Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

Если consumed имеет значение NULL, функция работает так же, как PyUnicode_DecodeUTF8(). Если consumed не имеет значение NULL, завершающие неполные последовательности байтов UTF-8 не считаются ошибкой. Эти байты не декодируются, а количество декодированных байтов сохраняется в consumed.

PyObject *PyUnicode_AsUTF8String(PyObject *unicode)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

Функция завершается с ошибкой, если строка содержит суррогатные кодовые точки (U+D800 - U+DFFF).

const char *PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)

Часть стабильного ABI начиная с версии 3.10.

Возвращает указатель на представление объекта Unicode в кодировке UTF-8 и сохраняет размер закодированного представления (в байтах) в size. Аргумент size может иметь значение NULL; в этом случае размер не сохраняется. В конец возвращаемого буфера всегда добавляется дополнительный нулевой байт (не включённый в size), независимо от наличия других нулевых кодовых точек.

В случае ошибки задаёт исключение, устанавливает для size значение -1 (если он не равен NULL) и возвращает NULL.

Функция завершается с ошибкой, если строка содержит суррогатные кодовые точки (U+D800 - U+DFFF).

Представление строки в UTF-8 кэшируется в объекте Unicode, и последующие вызовы возвращают указатель на тот же буфер. Вызывающая сторона не должна освобождать буфер. Буфер освобождается, а указатели на него становятся недействительными при сборке мусора для объекта Unicode.

Добавлено в версии 3.3.

Изменено в версии 3.7: Теперь тип возвращаемого значения — const char *, а не char *.

Изменено в версии 3.10: Эта функция входит в состав ограниченного API.

const char *PyUnicode_AsUTF8(PyObject *unicode)

Аналогична PyUnicode_AsUTF8AndSize(), но не сохраняет размер.

Предупреждение

Эта функция не обрабатывает особым образом нулевые символы, встроенные в unicode. Поэтому строки, содержащие нулевые символы, сохраняются в возвращаемой строке; некоторые функции C могут интерпретировать их как конец строки, что приведёт к усечению. Если усечение может стать проблемой, рекомендуется использовать вместо неё PyUnicode_AsUTF8AndSize().

Добавлено в версии 3.3.

Изменено в версии 3.7: Теперь тип возвращаемого значения — const char *, а не char *.

Кодеки UTF-32

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

PyObject *PyUnicode_DecodeUTF32(const char *str, Py_ssize_t size, const char *errors, int *byteorder)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

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

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

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

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

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

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

PyObject *PyUnicode_DecodeUTF32Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

Если consumed имеет значение NULL, функция работает так же, как PyUnicode_DecodeUTF32(). Если consumed не имеет значения NULL, PyUnicode_DecodeUTF32Stateful() не считает завершающие неполные последовательности байтов UTF-32 (например, количество байтов, не делящееся на четыре) ошибкой. Эти байты не декодируются, а количество декодированных байтов сохраняется в consumed.

PyObject *PyUnicode_AsUTF32String(PyObject *unicode)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

Кодеки UTF-16

API кодеков UTF-16:

PyObject *PyUnicode_DecodeUTF16(const char *str, Py_ssize_t size, const char *errors, int *byteorder)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

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

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

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

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

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

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

PyObject *PyUnicode_DecodeUTF16Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

Если consumed имеет значение NULL, функция работает так же, как PyUnicode_DecodeUTF16(). Если consumed не имеет значения NULL, PyUnicode_DecodeUTF16Stateful() не считает завершающие неполные последовательности байтов UTF-16 (например, нечётное количество байтов или разделённую суррогатную пару) ошибкой. Эти байты не декодируются, а количество декодированных байтов сохраняется в consumed.

PyObject *PyUnicode_AsUTF16String(PyObject *unicode)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

Кодеки UTF-7

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

PyObject *PyUnicode_DecodeUTF7(const char *str, Py_ssize_t size, const char *errors)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

PyObject *PyUnicode_DecodeUTF7Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

Если consumed имеет значение NULL, функция работает так же, как PyUnicode_DecodeUTF7(). Если consumed не имеет значения NULL, завершающие неполные участки base-64 в UTF-7 не считаются ошибкой. Эти байты не декодируются, а количество декодированных байтов сохраняется в consumed.

Кодеки Unicode-Escape

API кодека «Unicode Escape»:

PyObject *PyUnicode_DecodeUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

Кодеки Raw-Unicode-Escape

API кодека «Raw Unicode Escape»:

PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

Кодеки Latin-1

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

PyObject *PyUnicode_DecodeLatin1(const char *str, Py_ssize_t size, const char *errors)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

PyObject *PyUnicode_AsLatin1String(PyObject *unicode)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

Кодеки ASCII

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

PyObject *PyUnicode_DecodeASCII(const char *str, Py_ssize_t size, const char *errors)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

PyObject *PyUnicode_AsASCIIString(PyObject *unicode)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

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

Этот кодек особенный: его можно использовать для реализации множества различных кодеков (так и были получены большинство стандартных кодеков, включённых в пакет encodings). Для кодирования и декодирования символов кодек использует таблицы соответствий. Предоставляемые объекты таблиц должны поддерживать интерфейс отображения __getitem__(); хорошо подходят словари и последовательности.

API кодеков с таблицами соответствий:

PyObject *PyUnicode_DecodeCharmap(const char *str, Py_ssize_t length, PyObject *mapping, const char *errors)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

Если mapping равен NULL, применяется декодирование Latin-1. В противном случае mapping должен сопоставлять порядковые номера байтов (целые числа в диапазоне от 0 до 255) строкам Unicode, целым числам (которые затем интерпретируются как порядковые номера Unicode) или None. Несопоставленные байты данных — те, которые вызывают LookupError, а также те, которым сопоставлено значение None, 0xFFFE или '\ufffe', — считаются неопределёнными сопоставлениями и вызывают ошибку.

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

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

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

Следующий API кодека является особенным, так как сопоставляет Unicode с Unicode.

PyObject *PyUnicode_Translate(PyObject *unicode, PyObject *table, const char *errors)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

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

Таблицам сопоставления достаточно предоставлять интерфейс __getitem__(); хорошо подходят словари и последовательности. Несопоставленные порядковые номера символов (те, которые вызывают LookupError) остаются без изменений и копируются как есть.

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

Кодеки MBCS для Windows

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

PyObject *PyUnicode_DecodeMBCS(const char *str, Py_ssize_t size, const char *errors)

Возвращаемое значение: новая ссылка. Часть стабильного ABI в Windows начиная с версии 3.7.

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

PyObject *PyUnicode_DecodeMBCSStateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

Возвращаемое значение: новая ссылка. Часть стабильного ABI в Windows начиная с версии 3.7.

Если consumed имеет значение NULL, функция работает так же, как PyUnicode_DecodeMBCS(). Если consumed не имеет значения NULL, PyUnicode_DecodeMBCSStateful() не декодирует завершающий ведущий байт, а количество декодированных байтов сохраняет в consumed.

PyObject *PyUnicode_DecodeCodePageStateful(int code_page, const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

Возвращаемое значение: новая ссылка. Часть стабильного ABI в Windows начиная с версии 3.7.

Аналогична PyUnicode_DecodeMBCSStateful(), но использует кодовую страницу, заданную аргументом code_page.

PyObject *PyUnicode_AsMBCSString(PyObject *unicode)

Возвращаемое значение: новая ссылка. Часть стабильного ABI в Windows начиная с версии 3.7.

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

PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)

Возвращаемое значение: новая ссылка. Часть стабильного ABI в Windows начиная с версии 3.7.

Кодирует объект Unicode с помощью указанной кодовой страницы и возвращает байтовый объект Python. Возвращает NULL, если кодек вызвал исключение. Чтобы получить кодировщик MBCS, используйте кодовую страницу CP_ACP.

Добавлено в версии 3.3.