Объекты 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)

Гарантирует, что строковый объект o представлен в «каноническом» формате. Это необходимо сделать перед использованием любых описанных ниже макросов доступа.

При успешном выполнении возвращает 0, а при ошибке — -1 и устанавливает исключение; в частности, это происходит при сбое выделения памяти.

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

Устарело с версии 3.10, будет удалено в версии 3.12: Этот API будет удалён вместе с PyUnicode_FromUnicode().

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(). Перед доступом убедитесь, что был вызван PyUnicode_READY().

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

PyUnicode_WCHAR_KIND

PyUnicode_1BYTE_KIND

PyUnicode_2BYTE_KIND

PyUnicode_4BYTE_KIND

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

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

Устарело с версии 3.10, будет удалено в версии 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()). Проверки и вызовы для подготовки не выполняются.

Добавлено в версии 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.

Py_ssize_t PyUnicode_GET_SIZE(PyObject *unicode)

Возвращает размер устаревшего представления Py_UNICODE в единицах кода (суррогатные пары учитываются как 2 единицы). unicode должен быть объектом Unicode (проверка не выполняется).

Устарело с версии 3.3, будет удалено в версии 3.12: Часть старого API Unicode; перейдите на использование PyUnicode_GET_LENGTH().

Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *unicode)

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

Устарело с версии 3.3, будет удалено в версии 3.12: Часть старого API Unicode; перейдите на использование PyUnicode_GET_LENGTH().

Py_UNICODE *PyUnicode_AS_UNICODE(PyObject *unicode)

const char *PyUnicode_AS_DATA(PyObject *unicode)

Возвращает указатель на представление объекта Py_UNICODE. Возвращаемый буфер всегда завершается дополнительной нулевой кодовой точкой. Он также может содержать встроенные нулевые кодовые точки, из-за которых строка будет усечена при использовании в большинстве функций C. Вариант AS_DATA приводит указатель к типу const char*. Аргумент unicode должен быть объектом Unicode (проверка не выполняется).

Изменено в версии 3.3: Эта функция стала неэффективной — во многих случаях представление Py_UNICODE отсутствует и его нужно создавать — и может завершиться ошибкой (вернуть NULL с установленным исключением). Попробуйте перенести код на использование новых макросов PyUnicode_nBYTE_DATA() или используйте PyUnicode_WRITE() либо PyUnicode_READ().

Устарело с версии 3.3, будет удалено в версии 3.12: Часть старого API Unicode; перейдите на использование семейства макросов PyUnicode_nBYTE_DATA().

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

Эти 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, преобразованный в число с плавающей точкой двойной точности. Если преобразование невозможно, возвращает -1.0. Этот макрос не вызывает исключений.

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

Py_UNICODE_IS_SURROGATE(ch)

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

Py_UNICODE_IS_HIGH_SURROGATE(ch)

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

Py_UNICODE_IS_LOW_SURROGATE(ch)

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

Py_UNICODE_JOIN_SURROGATES(high, low)

Объединяет два суррогатных символа и возвращает одно значение Py_UCS4. high и low — соответственно старший и младший суррогаты в суррогатной паре.

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

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

PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)

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

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

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

Добавлено в версии 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. Буфер копируется в новый объект. Если буфер не NULL, возвращаемое значение может быть общим объектом, то есть изменение данных не допускается.

Если str равен NULL, эта функция работает как PyUnicode_FromUnicode(), а буфер устанавливается в NULL. Такое использование устарело; вместо него следует использовать PyUnicode_New(). Оно будет удалено в Python 3.12.

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. Допускаются следующие символы формата:

Символы формата	Тип	Комментарий
%%	н/д	Символ % без изменений.
%c	int	Один символ, представленный как int языка C.
%d	int	Эквивалентно printf("%d"). [1]
%u	unsigned int	Эквивалентно printf("%u"). [1]
%ld	long	Эквивалентно printf("%ld"). [1]
%li	long	Эквивалентно printf("%li"). [1]
%lu	unsigned long	Эквивалентно printf("%lu"). [1]
%lld	long long	Эквивалентно printf("%lld"). [1]
%lli	long long	Эквивалентно printf("%lli"). [1]
%llu	unsigned long long	Эквивалентно printf("%llu"). [1]
%zd	Py_ssize_t	Эквивалентно printf("%zd"). [1]
%zi	Py_ssize_t	Эквивалентно printf("%zi"). [1]
%zu	size_t	Эквивалентно printf("%zu"). [1]
%i	int	Эквивалентно printf("%i"). [1]
%x	int	Эквивалентно printf("%x"). [1]
%s	const char*	Завершаемый нулём массив символов C.
%p	const void*	Шестнадцатеричное представление указателя C. В основном эквивалентно printf("%p"), за исключением того, что гарантированно начинается с буквального 0x независимо от того, какое значение возвращает printf платформы.
%A	PyObject*	Результат вызова ascii().
%U	PyObject*	Объект Unicode.
%V	PyObject*, const char*	Объект Unicode (который может быть NULL) и завершаемый нулём массив символов C в качестве второго параметра (который будет использован, если первый параметр равен NULL).
%S	PyObject*	Результат вызова PyObject_Str().
%R	PyObject*	Результат вызова PyObject_Repr().

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

Примечание

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

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

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

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

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 в кодовых точках.

Добавлено в версии 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, индекс находится в допустимых границах и объект можно безопасно изменить (то есть счётчик ссылок на него равен единице).

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

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)

Входит в стабильный ABI начиная с версии 3.7.

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

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

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

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

Возвращает подстроку unicode от символьного индекса start (включительно) до символьного индекса end (не включая его). Отрицательные индексы не поддерживаются.

Добавлено в версии 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.

Устаревшие API Py_UNICODE

Эти функции API устарели после реализации PEP 393. Модули расширения могут продолжать использовать их, поскольку они не будут удалены в Python 3.x, однако следует учитывать, что их использование может привести к снижению производительности и увеличению потребления памяти.

PyObject *PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)

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

Создаёт объект Unicode из буфера Py_UNICODE u указанного размера. u может быть равен NULL, в этом случае содержимое будет неопределённым. Пользователь должен самостоятельно заполнить необходимые данные. Буфер копируется в новый объект.

Если буфер не равен NULL, возвращаемое значение может быть общим объектом. Поэтому изменять результирующий объект Unicode разрешается только в том случае, если u равен NULL.

Если буфер равен NULL, после заполнения содержимого строки и до использования любых макросов доступа, например PyUnicode_KIND(), необходимо вызвать PyUnicode_READY().

Устарело начиная с версии 3.3; будет удалено в версии 3.12: Часть устаревшего API Unicode. Перейдите на использование PyUnicode_FromKindAndData(), PyUnicode_FromWideChar() или PyUnicode_New().

Py_UNICODE *PyUnicode_AsUnicode(PyObject *unicode)

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

Устарело начиная с версии 3.3; будет удалено в версии 3.12: Часть устаревшего API Unicode. Перейдите на использование PyUnicode_AsUCS4(), PyUnicode_AsWideChar(), PyUnicode_ReadChar() или аналогичных новых API.

Py_UNICODE *PyUnicode_AsUnicodeAndSize(PyObject *unicode, Py_ssize_t *size)

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

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

Устарело начиная с версии 3.3; будет удалено в версии 3.12: Часть устаревшего API Unicode. Перейдите на использование PyUnicode_AsUCS4(), PyUnicode_AsWideChar(), PyUnicode_ReadChar() или аналогичных новых API.

Py_ssize_t PyUnicode_GetSize(PyObject *unicode)

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

Возвращает размер устаревшего представления Py_UNICODE в кодовых единицах (суррогатные пары учитываются как 2 единицы).

Устарело начиная с версии 3.3; будет удалено в версии 3.12: Часть устаревшего API Unicode. Перейдите на использование PyUnicode_GET_LENGTH().

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

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

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() для декодирования строки из Py_FileSystemDefaultEncoding (кодировки локали, считанной при запуске Python).

Эта функция игнорирует режим 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). Кодировщик использует обработчик ошибок "strict", если errors равен NULL. Возвращает объект bytes. unicode не может содержать встроенные нулевые символы.

Используйте PyUnicode_EncodeFSDefault() для кодирования строки в Py_FileSystemDefaultEncoding (кодировку локали, считанную при запуске Python).

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

См. также

Функцию Py_EncodeLocale().

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

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

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

Для кодирования и декодирования имён файлов и других строк окружения в качестве кодировки следует использовать Py_FileSystemDefaultEncoding, а в качестве обработчика ошибок — Py_FileSystemDefaultEncodeErrors (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.

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

Если Py_FileSystemDefaultEncoding не задан, используется кодировка локали.

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

См. также

Функцию Py_DecodeLocale().

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

PyObject *PyUnicode_DecodeFSDefault(const char *str)

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

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

Если Py_FileSystemDefaultEncoding не задан, используется кодировка локали.

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

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

PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)

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

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

Если Py_FileSystemDefaultEncoding не задан, используется кодировка локали.

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

См. также

Функцию Py_EncodeLocale().

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

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

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

Кодеки UTF-8

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

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

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

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

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

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

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

PyObject *PyUnicode_AsUTF8String(PyObject *unicode)

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

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

Добавлено в версии 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_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.

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