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

Тип Unicode

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

type Py_UCS4

type Py_UCS2

type Py_UCS1

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

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

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

type Py_UNICODE

Это псевдоним типа wchar_t, который в зависимости от платформы является 16- или 32-битным типом.

Изменено в версии 3.3: В предыдущих версиях это был 16- или 32-битный тип в зависимости от того, какую сборку Python с «узкой» или «широкой» поддержкой Unicode вы выбрали во время сборки.

Устарело начиная с версии 3.13, будет удалено в версии 3.15.

type PyASCIIObject

type PyCompactUnicodeObject

type PyUnicodeObject

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

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

PyTypeObject PyUnicode_Type

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

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

PyTypeObject PyUnicodeIter_Type

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

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

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

int PyUnicode_Check(PyObject *obj)

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

int PyUnicode_CheckExact(PyObject *obj)

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

int PyUnicode_READY(PyObject *unicode)

Возвращает 0. Этот API сохранён только для обратной совместимости.

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

Устарело начиная с версии 3.10: Этот API ничего не делает начиная с Python 3.12.

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)

Выполняет запись в каноническое представление data (полученное с помощью PyUnicode_DATA()). Эта функция не выполняет проверок корректности и предназначена для использования в циклах. Вызывающая сторона должна кэшировать значение kind и указатель data, полученные из других вызовов. index — это индекс в строке (начиная с 0), а value — новое значение кодовой точки, которое нужно записать в эту позицию.

Добавлено в версии 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(), если строка не готова.

Свойства символов 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, преобразованный в целое число, соответствующее одной цифре. Если это невозможно, возвращает -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_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.

Это рекомендуемый способ выделения нового объекта Unicode. Объекты, созданные с помощью этой функции, нельзя изменять в размере.

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

Добавлено в версии 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 байта на символ, согласно значению kind.

При необходимости входной 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 из буфера char str. Байты интерпретируются как закодированные в UTF-8. Буфер копируется в новый объект. Возвращаемое значение может быть совместно используемым объектом, то есть изменять данные нельзя.

Эта функция вызывает SystemError, если:

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

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

PyObject *PyUnicode_FromString(const char *str)

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

Создаёт объект Unicode из нуль-терминированного буфера char str, закодированного в UTF-8.

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

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

Принимает форматирующую строку в стиле C printf() и переменное число аргументов, вычисляет размер результирующей строки Python Unicode и возвращает строку со вставленными в неё отформатированными значениями. Аргументы переменного числа должны иметь типы 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 и другие объекты, подобные bytes декодируются с использованием заданной кодировки encoding и обработки ошибок, определённой параметром errors. Для обоих параметров можно указать NULL, чтобы использовать значения по умолчанию (подробности см. в разделе Встроенные кодеки).

Для всех остальных объектов, включая объекты Unicode, устанавливается исключение TypeError.

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

PyObject *PyUnicode_BuildEncodingMap(PyObject *string)

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

Возвращает отображение, подходящее для декодирования пользовательской однобайтовой кодировки. Принимает строку Unicode string длиной до 256 символов, представляющую таблицу кодировки, и возвращает либо компактный внутренний объект отображения, либо словарь, сопоставляющий порядковые номера символов значениям байтов. При недопустимых входных данных вызывает исключение TypeError и возвращает NULL. .. versionadded:: 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 и устанавливает исключение; в противном случае возвращает количество скопированных символов.

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

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

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

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

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

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

Записывает символ в строку. Строка должна быть создана с помощью PyUnicode_New(). Поскольку строки Unicode должны быть неизменяемыми, строка не должна совместно использоваться и не должна быть захеширована.

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

В случае успеха возвращает 0; в случае ошибки возвращает -1 и устанавливает исключение.

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

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)

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

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

В случае успеха возвращает символ; в случае ошибки возвращает -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. Значение -1 для size указывает, что функция должна самостоятельно вычислить длину с помощью 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.

Общие кодеки

Общие 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 и возвращает результат в виде объекта bytes Python. Параметры encoding и errors имеют тот же смысл, что и параметры с такими же именами метода Unicode encode(). Используемый кодек определяется с помощью реестра кодеков 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 и возвращает результат в виде объекта bytes 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 и возвращает результат в виде объекта bytes. Обработка ошибок — «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 и возвращает результат в виде объекта bytes. Обработка ошибок — «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 и возвращает результат в виде объекта bytes 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 и возвращает результат в виде объекта bytes 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 и возвращает результат в виде объекта bytes. Обработка ошибок — «strict». Возвращает NULL, если кодек вызвал исключение.

Объект mapping должен сопоставлять целые числа — порядковые номера Unicode — объектам bytes, целым числам от 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 и используют преобразователи MBCS Win32. Обратите внимание, что 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 и возвращает результат в виде объекта bytes Python. Обработка ошибок — «strict». Возвращает NULL, если кодек вызвал исключение.

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

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

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

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