Unicode Objects and Codecs

Тип 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 во время сборки.

type PyASCIIObject

type PyCompactUnicodeObject

type PyUnicodeObject

Эти подтипы PyObject представляют собой объект Python Unicode. Почти во всех случаях их не следует использовать напрямую, так как все функции 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)

Обеспечивает, что строковый объект 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 (см. выше), которая указывает, сколько байт на символ использует этот объект 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.

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 предоставляет множество различных свойств символов. Наиболее часто используемые из них доступны через эти макросы, которые сопоставлены с функциями 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 печатаемым символом. Непечатаемые символы — это символы, определенные в базе данных символов Unicode как «Другие» или «Разделитель», за исключением 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, преобразованный в целое число от 0 до 9. Возвращает -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 байта на символ, как указано в типе.

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

Новое в версии 3.3.

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

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

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

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

PyObject *PyUnicode_FromString(const char *str)

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

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

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

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

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

Символы форматирования	Тип	Комментарий
%%	n/a	Символ %.
%c	int	Один символ, представленный как C int.
%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).

1(1,2,3,4,5,6,7,8,9,10,11,12,13)

Для целочисленных спецификаторов (d, u, ld, li, lu, lld, lli, llu, zd, zi, zu, i, x): флаг 0-преобразования действует даже при заданной точности.

Изменено в версии 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)

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

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

PyObject *PyUnicode_FromObject(PyObject *obj)

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

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

Объекты, отличные от Юникода или его подтипов, вызовут TypeError.

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

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

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

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

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

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

Py_ssize_t PyUnicode_GetLength(PyObject *unicode)

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

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

Введено в версии 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)

Копирует символы из одного объекта Юникода в другой. Эта функция выполняет преобразование символов при необходимости и переходит к 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 ссылки.

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

Введено в версии 3.3.

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

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

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

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

Введено в версии 3.3.

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)

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

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

Введено в версии 3.3.

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

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

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

Введено в версии 3.3.

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

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

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

Введено в версии 3.3.

Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)

Часть стабильного API с версии 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_READY() после заполнения содержимого строки, прежде чем использовать какие-либо макросы доступа, такие как PyUnicode_KIND().

Устарело начиная с версии 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).

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

См. также

Функцию 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).

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

См. также

Функцию 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)

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

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

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

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

Копирует содержимое объекта Unicode в буфер wchar_t wstr. Максимум размер wchar_t символов копируется (исключая возможный завершающий нулевой символ). Возвращает количество скопированных wchar_t символов или -1 в случае ошибки. Обратите внимание, что результирующая строка wchar_t* может быть или не быть завершаемой нулём. Ответственность за завершение строки wchar_t* нулём лежит на вызывающей стороне, если это требуется приложением. Также обратите внимание, что строка wchar_t* может содержать нулевые символы, что приведёт к усечению строки при использовании с большинством функций C.

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

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

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

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

Новое в версии 3.2.

Изменено в версии 3.7: Генерирует исключение ValueError, если размер 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 байт UTF-8 закодированной строки str. Возвращает 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. Обработка ошибок — «strict». Возвращает NULL если кодек поднял исключение.

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

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

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

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

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

New in version 3.3.

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

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

const char *PyUnicode_AsUTF8(PyObject *unicode)

Как PyUnicode_AsUTF8AndSize(), но не сохраняет размер.

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

PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)

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

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

Кодировки Latin-1

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

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

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

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

PyObject *PyUnicode_AsLatin1String(PyObject *unicode)

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

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

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

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

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

Новое в версии 3.3.

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