Объекты и кодеки 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-битный тип, в зависимости от выбора «узкого» или «широкого» Unicode-варианта Python во время компиляции.

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

type PyASCIIObject

type PyCompactUnicodeObject

type PyUnicodeObject

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

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

PyTypeObject PyUnicode_Type

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

Этот экземпляр PyTypeObject представляет собой тип Python Unicode. Он доступен в коде 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 (см. выше), указывающих, сколько байтов на символ используется данным объектом Unicode для хранения данных. unicode должен быть объектом Unicode в «каноническом» представлении (не проверяется).

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

void *PyUnicode_DATA(PyObject *unicode)

Возвращает указатель на необработанный буфер 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(), если строка не готова.

Свойства символов Юникода

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

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 печатным символом. Непечатные символы — это те символы, которые определены в базе данных символов Юникода как «Другие» или «Разделитель», за исключением ASCII-пробела (0x20), который считается печатным. (Обратите внимание, что печатные символы в этом контексте — это те, которые не должны быть экранированы при вызове repr() для строки. Это не влияет на обработку строк, записанных в sys.stdout или sys.stderr.)

Эти 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].

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

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

PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)

Значение возврата: Новая ссылка.

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

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

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

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

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

Значение возврата: Новая ссылка.

Создает новый объект Юникода с заданным 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.

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

Эта функция вызывает SystemError при:

• size < 0,
• str — NULL и size > 0

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

PyObject *PyUnicode_FromString(const char *str)

Значение возврата: Новая ссылка. Часть Стабильной ABI.

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

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

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

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

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

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

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

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

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

Модификатор	Типы
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*.

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

Спецификатор преобразования	Тип	Комментарий
%	n/a	Литеральный символ %.
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_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)

Значение возврата: Новый ссылка. Часть Стабильной ABI.

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

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

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

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

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). Декодер использует обработчик ошибок "strict" если errors имеет значение NULL. str должна заканчиваться нулевым символом, но не может содержать вложенные нулевые символы.

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

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

См. также

Функцию Py_DecodeLocale().

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

Изменено в версии 3.7: Функция теперь также использует текущую кодировку локали для обработчика ошибок surrogateescape, за исключением Android. Ранее использовалась функция Py_DecodeLocale() для surrogateescape, а текущая кодировка локали использовалась для 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). Кодировщик использует обработчик ошибок "strict" если errors имеет значение NULL. Возвращает объект bytes. unicode не может содержать вложенные нулевые символы.

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

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

См. также

Функцию Py_EncodeLocale().

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

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

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

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

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

int PyUnicode_FSConverter(PyObject *obj, void *result)

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

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

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

Изменено в версии 3.6: Принимает объект типа путь.

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

int PyUnicode_FSDecoder(PyObject *obj, void *result)

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

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

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

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

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

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

Возвращает указатель на UTF-8 кодировку объекта Unicode и сохраняет размер закодированного представления (в байтах) в 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(), но не сохраняет размер.

Добавлена в версии 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) определяет обработку ошибок. По умолчанию — «строгая».

Если 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 типа bytes, используя кодировку UTF-32 в родном порядке байтов. Строка всегда начинается со знака BOM. Обработка ошибок — «строгая». Возвращает 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) определяет обработку ошибок. По умолчанию — «строго».

Если 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. Обработка ошибок — «строго». Возвращает NULL , если кодек вызвал исключение.

Кодеки UTF-7

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

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

Значение возврата: новая ссылка. Часть Стабильной ABI.

Создать объект Unicode, декодировав size байтов из строки, закодированной в UTF-7, str. Возвращает 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, неполные секции UTF-7 base-64 не будут обрабатываться как ошибка. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в consumed.

Кодеки «Unicode Escape»

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

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

Значение возврата: новая ссылка. Часть Стабильной ABI.

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

PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)

Значение возврата: новая ссылка. Часть Стабильной ABI.

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

Кодеки «Raw Unicode Escape»

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

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

Значение возврата: новая ссылка. Часть Стабильной ABI.

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

PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)

Значение возврата: новая ссылка. Часть Стабильной ABI.

Кодировать объект Unicode с использованием «Raw Unicode Escape» и возвращать результат в виде объекта bytes. Обработка ошибок — «строго». Возвращает 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 байтов из строки, закодированной в Latin-1, str. Возвращает NULL , если кодек вызвал исключение.

PyObject *PyUnicode_AsLatin1String(PyObject *unicode)

Значение возврата: новая ссылка. Часть Стабильной ABI.

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

Кодеки ASCII

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

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

Значение возврата: новая ссылка. Часть Стабильной ABI.

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

PyObject *PyUnicode_AsASCIIString(PyObject *unicode)

Значение возврата: новая ссылка. Часть Стабильной ABI.

Кодировать объект Unicode с использованием ASCII и возвращать результат как объект Python bytes. Обработка ошибок — «строго». Возвращает 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, и возвращает результат как объект байтов. Обработка ошибок – «строгая». Возвращает 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 и используют преобразователи MBCS Win32 для реализации преобразований. Обратите внимание, что MBCS (или DBCS) – это класс кодировок, а не одна кодировка. Целевая кодировка определяется настройками пользователя на компьютере, на котором работает кодек.

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

Значение возврата: Новая ссылка. Часть Стабильной ABI в Windows с версии 3.7.

Создаёт объект Unicode, декодируя size байтов строки MBCS str. Возвращает 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_AsMBCSString(PyObject *unicode)

Значение возврата: Новая ссылка. Часть Стабильной ABI в Windows с версии 3.7.

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

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

Значение возврата: Новая ссылка. Часть Стабильной ABI в Windows с версии 3.7.

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

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

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