Объекты 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 вы выбрали при сборке.

type PyASCIIObject

type PyCompactUnicodeObject

type PyUnicodeObject

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

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

PyTypeObject PyUnicode_Type

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

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

Следующие 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, преобразованный в нижний регистр.

Устарело с версии 3.3: Эта функция использует простые сопоставления регистра.

Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4 ch)

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

Устарело с версии 3.3: Эта функция использует простые сопоставления регистра.

Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4 ch)

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

Устарело с версии 3.3: Эта функция использует простые сопоставления регистра.

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, преобразованный в число double. Если преобразование невозможно, возвращает -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 из символьного буфера 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().

Примечание

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

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_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)

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

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

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

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

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

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.

Читает символ из строки. В отличие от 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. Передача -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: Возбуждает исключение ValueError, если size равен NULL, а строка wchar_t* содержит нулевые символы.

Общие кодеки

Общие 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, если кодек возбудил исключение.

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

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

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

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

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

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

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

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

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

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