Объекты и кодеки Юникода¶

Объекты Юникода¶

Начиная с реализации PEP 393 в Python 3.3, объекты Unicode внутри используют различные представления, чтобы обеспечить работу с полным диапазоном символов Unicode и при этом не занимать много памяти. Существуют специальные случаи для строк, когда все кодовые точки меньше 128, 256 или 65536; в противном случае кодовые точки должны быть меньше 1114112 (это полный диапазон Unicode).

Представление UTF-8 создается по требованию и кэшируется в объекте Unicode.

Примечание

Представление Py_UNICODE было удалено из Python 3.12 вместе с устаревшими API. Для получения дополнительной информации смотрите PEP 623.

Тип Юникода¶

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

type Py_UCS4¶
type Py_UCS2¶
type Py_UCS1¶: Часть Стабильный ABI.
Эти типы являются типизациями для беззнаковых целых типов, достаточно широких, чтобы содержать символы размером 32 бита, 16 бит и 8 бит соответственно. При работе с одиночными символами Юникода используйте Py_UCS4.

Added in version 3.3.

type Py_UNICODE¶: Это типизация wchar_t, которая является 16-битным или 32-битным типом в зависимости от платформы.

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

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

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

Added in version 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 сохраняется только для обратной совместимости.

Added in version 3.3.

Не рекомендуется, начиная с версии 3.10: Этот API ничего не делает, начиная с версии Python 3.12.

Py_ssize_t PyUnicode_GET_LENGTH(PyObject *unicode)¶: Возвращает длину строки Unicode в кодовых точках. unicode должен быть объектом Unicode в «каноническом» представлении (не проверяется).

Added in version 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() для выбора нужной функции.

Added in version 3.3.

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

Added in version 3.3.

Изменено в версии 3.12: PyUnicode_WCHAR_KIND был удален.

int PyUnicode_KIND(PyObject *unicode)¶: Возвращает одну из констант вида PyUnicode (см. выше), которая указывает, сколько байт на символ использует этот объект Unicode для хранения своих данных. unicode должен быть объектом Unicode в «каноническом» представлении (не проверяется).

Added in version 3.3.

void *PyUnicode_DATA(PyObject *unicode)¶: Возвращает указатель void на необработанный буфер Unicode. unicode должен быть объектом Unicode в «каноническом» представлении (не проверяется).

Added in version 3.3.

void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)¶: Запись в каноническое представление данных (как получено с помощью PyUnicode_DATA()). Эта функция не выполняет никаких проверок на правильность и предназначена для использования в циклах. Вызывающая сторона должна кэшировать значение kind и указатель data, полученные при других вызовах. index - это индекс в строке (начинается с 0), а value - новое значение кодовой точки, которое должно быть записано в это место.

Added in version 3.3.

Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)¶: Считывание кодовой точки из канонического представления data (как получено с помощью PyUnicode_DATA()). Никаких проверок или вызовов готовности не выполняется.

Added in version 3.3.

Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)¶: Считывание символа из объекта Unicode unicode, который должен быть в «каноническом» представлении. Это менее эффективно, чем PyUnicode_READ(), если вы выполняете несколько последовательных считываний.

Added in version 3.3.

Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *unicode)¶: Возвращает максимальную точку кода, которая подходит для создания другой строки на основе unicode, которая должна быть в «каноническом» представлении. Это всегда приближение, но более эффективное, чем итерация по строке.

Added in version 3.3.

int PyUnicode_IsIdentifier(PyObject *unicode)¶: Часть Стабильный ABI.
Верните 1, если строка является допустимым идентификатором в соответствии с определением языка, раздел Идентификаторы и ключевые слова. В противном случае возвращается 0.

Изменено в версии 3.9: Функция больше не вызывает Py_FatalError(), если строка не готова.

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

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

Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4 ch)¶: Возвращает символ ch, преобразованный в верхний регистр.

Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4 ch)¶: Возвращает символ ch, преобразованный в заглавный регистр.

int Py_UNICODE_TODECIMAL(Py_UCS4 ch)¶: Возвращает символ ch, преобразованный в десятичное положительное целое число. Верните -1, если это невозможно. Эта функция не вызывает исключений.

int Py_UNICODE_TODIGIT(Py_UCS4 ch)¶: Возвращает символ ch, преобразованный в одноразрядное целое число. Верните -1, если это невозможно. Эта функция не вызывает исключений.

double Py_UNICODE_TONUMERIC(Py_UCS4 ch)¶: Возвращает символ ch, преобразованный в двойное число. Верните -1.0, если это невозможно. Эта функция не вызывает исключений.

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

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

int Py_UNICODE_IS_HIGH_SURROGATE(Py_UCS4 ch)¶: Проверьте, является ли ch суррогатом высокого уровня (0xD800 <= ch <= 0xDBFF).

int Py_UNICODE_IS_LOW_SURROGATE(Py_UCS4 ch)¶: Проверьте, является ли ch суррогатом низкого уровня (0xDC00 <= ch <= 0xDFFF).

Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)¶: Объединяет два суррогатных символа и возвращает одно значение Py_UCS4. high и low - это соответственно ведущий и последующий суррогаты в паре суррогатов. high должно находиться в диапазоне [0xD800; 0xDBFF], а low - в диапазоне [0xDC00; 0xDFFF].

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

Чтобы создать объекты Unicode и получить доступ к их основным свойствам последовательности, используйте эти API:

PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)¶

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

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

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

Added in version 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 байта на символ, в зависимости от вида.

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

Added in version 3.3.

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

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

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

Эта функция поднимает SystemError, когда:

size < 0,
str равно NULL и size > 0

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

PyObject *PyUnicode_FromString(const char *str)¶: Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Создание объекта Unicode из нуль-терминированного char-буфера str, закодированного в UTF-8.

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

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

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

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

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

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

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

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

Модификатор	Типы
`l`	long или unsigned long
`ll`	long long или unsigned long long
`j`	`intmax_t` или `uintmax_t`
`z`	`size_t` или `ssize_t`
`t`	`ptrdiff_t`

Модификатор длины l для последующих преобразований s или V указывает, что тип аргумента равен const wchar_t*.

Спецификаторами преобразования являются:

Спецификатор преобразования	Тип	Комментарий
`%`	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 (не подтипом), верните объекту новый strong reference.

Объекты, отличные от Unicode или его подтипов, приведут к появлению TypeError.

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

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

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

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

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

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

Py_ssize_t PyUnicode_GetLength(PyObject *unicode)¶: Часть Стабильный ABI с версии 3.7.
Возвращает длину объекта Unicode в кодовых точках.

Added in version 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 и устанавливает исключение при ошибке, в противном случае возвращает количество скопированных символов.

Added in version 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 и вызывает исключение при ошибке.

Added in version 3.3.

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

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

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

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

Added in version 3.3.

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)¶: Часть Стабильный ABI с версии 3.7.
Считывание символа из строки. Эта функция проверяет, что unicode является объектом Unicode и индекс не выходит за границы, в отличие от PyUnicode_READ_CHAR(), которая не выполняет проверку ошибок.

Added in version 3.3.

PyObject *PyUnicode_Substring(PyObject *unicode, Py_ssize_t start, Py_ssize_t end)¶: Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.7.
Возвращает подстроку unicode, начиная с символьного индекса start (включено) и заканчивая символьным индексом end (исключено). Отрицательные индексы не поддерживаются.

Added in version 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.

Added in version 3.3.

Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)¶: Часть Стабильный ABI с версии 3.7.
Скопируйте строку unicode в новый буфер UCS4, выделенный с помощью PyMem_Malloc(). Если это не удается, возвращается NULL с установленным MemoryError. В возвращаемый буфер всегда добавляется дополнительная нулевая точка кода.

Added in version 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() для декодирования строки из filesystem encoding and error handler.

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

См.также

Функция Py_DecodeLocale().

Added in version 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().

Added in version 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() для кодирования строки в filesystem encoding and error handler.

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

См.также

Функция Py_EncodeLocale().

Added in version 3.3.

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

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

Функции кодирования в filesystem encoding and error handler и декодирования из PEP 383 (PEP 383 и PEP 529).

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

int PyUnicode_FSConverter(PyObject *obj, void *result)¶: Часть Стабильный ABI.
Конвертер ParseTuple: кодирует объекты str - полученные напрямую или через интерфейс os.PathLike - в bytes с помощью PyUnicode_EncodeFSDefault(); объекты bytes выводятся как есть. Результатом должен быть PyBytesObject*, который должен быть освобожден, когда он больше не используется.

Added in version 3.1.

Изменено в версии 3.6: Принимает path-like object.

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

int PyUnicode_FSDecoder(PyObject *obj, void *result)¶: Часть Стабильный ABI.
Конвертер ParseTuple: декодирует объекты bytes - полученные прямо или косвенно через интерфейс os.PathLike - в str с помощью PyUnicode_DecodeFSDefaultAndSize(); объекты str выводятся как есть. Результатом должен быть PyUnicodeObject*, который должен быть освобожден, когда он больше не используется.

Added in version 3.2.

Изменено в версии 3.6: Принимает path-like object.

PyObject *PyUnicode_DecodeFSDefaultAndSize(const char *str, Py_ssize_t size)¶

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

Декодируйте строку из filesystem encoding and error handler.

Если вам нужно декодировать строку из текущей кодировки локали, используйте PyUnicode_DecodeLocaleAndSize().

См.также

Функция Py_DecodeLocale().

Изменено в версии 3.6: Теперь используется filesystem error handler.

PyObject *PyUnicode_DecodeFSDefault(const char *str)¶

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

Декодирование нуль-терминированной строки из filesystem encoding and error handler.

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

Изменено в версии 3.6: Теперь используется filesystem error handler.

PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)¶

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

Перекодируйте объект Unicode в filesystem encoding and error handler и верните bytes. Обратите внимание, что результирующий объект bytes может содержать нулевые байты.

Если вам нужно перекодировать строку в кодировку текущей локали, используйте PyUnicode_EncodeLocale().

См.также

Функция Py_EncodeLocale().

Added in version 3.2.

Изменено в версии 3.6: Теперь используется filesystem error handler.

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, включая завершающий null.

Обратите внимание, что результирующая строка wchar_t* может быть нуль-терминированной, а может и не быть. Ответственность за то, чтобы строка wchar_t* была нуль-терминированной, лежит на вызывающей стороне, если это требуется приложению. Также обратите внимание, что строка wchar_t* может содержать нулевые символы, что приведет к ее усечению при использовании с большинством функций языка Си.

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

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

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

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

Added in version 3.2.

Изменено в версии 3.7: Вызывает ошибку ValueError, если size равен NULL и строка wchar_t* содержит нулевые символы.

Встроенные кодеки¶

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

Многие из следующих API принимают два аргумента encoding и errors, и имеют ту же семантику, что и встроенный конструктор строковых объектов str().

Установка кодировки в NULL приводит к использованию кодировки по умолчанию, которая является UTF-8. Вызовы файловой системы должны использовать PyUnicode_FSConverter() для кодировки имен файлов. Здесь используется внутренняя кодировка filesystem encoding and error handler.

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

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

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

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

При ошибке создайте исключение, установите size в -1 (если он не NULL) и верните NULL.

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

Added in version 3.3.

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

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

const char *PyUnicode_AsUTF8(PyObject *unicode)¶: Как PyUnicode_AsUTF8AndSize(), но не хранит размер.

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

PyObject *PyUnicode_AsLatin1String(PyObject *unicode)¶: Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Закодируйте объект Unicode с помощью Latin-1 и верните результат в виде объекта Python bytes. Обработка ошибок «строгая». Возвращается NULL, если кодек вызвал исключение.

Кодеки ASCII¶

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

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) со строками Юникода, целыми числами (которые затем интерпретируются как ординалы Юникода) или None. Не отображенные байты данных - те, которые вызывают LookupError, а также те, которые отображаются в None, 0xFFFE или '\ufffe', - рассматриваются как неопределенные отображения и вызывают ошибку.

PyObject *PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)¶

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

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

Объект mapping должен отображать целые порядковые числа Unicode на объекты байтов, целые числа в диапазоне от 0 до 255 или None. Не отображенные символьные ординалы (те, которые приводят к LookupError), а также отображенные на None рассматриваются как «неопределенное отображение» и вызывают ошибку.

Следующий API кодека отличается тем, что отображает Unicode в Unicode.

PyObject *PyUnicode_Translate(PyObject *unicode, PyObject *table, const char *errors)¶

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

Переведите строку, применив к ней таблицу сопоставления символов, и верните полученный объект Unicode. Возвращает NULL, если кодек вызвал исключение.

Таблица сопоставления должна сопоставлять целые порядковые числа Юникода с целыми порядковыми числами Юникода или 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 on 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 on Windows с версии 3.7.
Если consumed равно NULL, ведите себя как PyUnicode_DecodeMBCS(). Если consumed не NULL, то PyUnicode_DecodeMBCSStateful() не будет декодировать ведущий байт, а количество байтов, которые были декодированы, будет сохранено в consumed.

PyObject *PyUnicode_AsMBCSString(PyObject *unicode)¶: Возвращаемое значение: Новая ссылка. Часть Стабильный ABI on Windows с версии 3.7.
Закодируйте объект Unicode с помощью MBCS и верните результат в виде объекта Python bytes. Обработка ошибок «строгая». Возвращается NULL, если кодек вызвал исключение.

PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)¶: Возвращаемое значение: Новая ссылка. Часть Стабильный ABI on Windows с версии 3.7.
Кодирует объект Unicode, используя указанную кодовую страницу, и возвращает объект Python bytes. Верните NULL, если кодек вызвал исключение. Используйте кодовую страницу CP_ACP для получения кодека MBCS.

Added in version 3.3.

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

Методы и функции слотов¶

Следующие API способны работать с объектами и строками Юникода на входе (в описаниях мы называем их строками) и возвращать объекты Юникода или целые числа в зависимости от ситуации.

Все они возвращают NULL или -1 при возникновении исключения.

PyObject *PyUnicode_Concat(PyObject *left, PyObject *right)¶: Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Конкатенация двух строк с получением новой строки Unicode.

PyObject *PyUnicode_Split(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)¶: Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Разделяет строку, выдавая список строк Unicode. Если sep равно NULL, то разбиение будет производиться по всем пробельным подстрокам. В противном случае разбиение происходит по заданному разделителю. Будет выполнено не более maxsplit разбиений. Если значение отрицательно, то ограничение не устанавливается. Разделители не включаются в результирующий список.

PyObject *PyUnicode_Splitlines(PyObject *unicode, int keepends)¶: Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Разделяет строку Unicode на переносы строк, возвращая список строк Unicode. CRLF считается одним переводом строки. Если keepends имеет значение 0, символы перевода строки не включаются в результирующие строки.

PyObject *PyUnicode_Join(PyObject *separator, PyObject *seq)¶: Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Объединяет последовательность строк с помощью заданного разделителя и возвращает результирующую строку Unicode.

Py_ssize_t PyUnicode_Tailmatch(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)¶: Часть Стабильный ABI.
Верните 1, если substr совпадает с unicode[start:end] в заданном хвосте (direction == -1 означает префиксное совпадение, direction == 1 - суффиксное), 0 в противном случае. Возвращает -1, если произошла ошибка.

Py_ssize_t PyUnicode_Find(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)¶: Часть Стабильный ABI.
Возвращает первую позицию substr в unicode[start:end], используя заданное направление (направление == 1 означает прямой поиск, направление == -1 - обратный поиск). Возвращаемое значение - индекс первого совпадения; значение -1 означает, что совпадение не найдено, а -2 - что произошла ошибка и было задано исключение.

Py_ssize_t PyUnicode_FindChar(PyObject *unicode, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)¶: Часть Стабильный ABI с версии 3.7.
Возвращает первую позицию символа ch в unicode[start:end], используя заданное направление (направление == 1 означает поиск вперед, направление == -1 - поиск назад). Возвращаемое значение - индекс первого совпадения; значение -1 означает, что совпадение не найдено, а -2 - что произошла ошибка и было задано исключение.

Added in version 3.3.

Изменено в версии 3.7: start и end теперь ведут себя как unicode[start:end].

Py_ssize_t PyUnicode_Count(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end)¶: Часть Стабильный ABI.
Возвращает количество непересекающихся вхождений substr в unicode[start:end]. Верните -1, если произошла ошибка.

PyObject *PyUnicode_Replace(PyObject *unicode, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)¶: Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Заменяет не более maxcount вхождений substr в unicode на replstr и возвращает результирующий объект Unicode. maxcount == -1 означает замену всех вхождений.

int PyUnicode_Compare(PyObject *left, PyObject *right)¶

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

Сравните две строки и верните -1, 0, 1 для значений «меньше, чем», «равно» и «больше, чем» соответственно.

Эта функция возвращает -1 в случае неудачи, поэтому для проверки ошибок следует вызывать PyErr_Occurred().

int PyUnicode_EqualToUTF8AndSize(PyObject *unicode, const char *string, Py_ssize_t size)¶

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

Сравните объект Unicode с буфером char, который интерпретируется как кодировка UTF-8 или ASCII, и верните true (1), если они равны, или false (0) в противном случае. Если объект Unicode содержит суррогатные символы или строка C не является правильной UTF-8, возвращается false (0).

Эта функция не вызывает исключений.

Added in version 3.13.

int PyUnicode_EqualToUTF8(PyObject *unicode, const char *string)¶: Часть Стабильный ABI с версии 3.13.
Аналогично PyUnicode_EqualToUTF8AndSize(), но вычисляет длину строки с помощью strlen(). Если объект Unicode содержит нулевые символы, возвращается false (0).

Added in version 3.13.

int PyUnicode_CompareWithASCIIString(PyObject *unicode, const char *string)¶

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

Сравнивает объект Unicode, unicode, с string и возвращает -1, 0, 1 для значений меньше, равно и больше, соответственно. Лучше всего передавать только строки в кодировке ASCII, но функция интерпретирует входную строку как ISO-8859-1, если она содержит символы, отличные от ASCII.

Эта функция не вызывает исключений.

PyObject *PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)¶

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

Rich сравнивает две строки Unicode и возвращает одно из следующих значений:

NULL в случае, если возникло исключение
Py_True или Py_False для успешных сравнений
Py_NotImplemented в случае, если комбинация типов неизвестна

Возможные значения для op: Py_GT, Py_GE, Py_EQ, Py_NE, Py_LT и Py_LE.

PyObject *PyUnicode_Format(PyObject *format, PyObject *args)¶: Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Возвращает новый строковый объект из format и args; это аналогично format % args.

int PyUnicode_Contains(PyObject *unicode, PyObject *substr)¶

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

Проверяет, содержится ли substr в unicode, и возвращает true или false соответственно.

substr должен быть приведен к одноэлементной строке Unicode. Если произошла ошибка, возвращается -1.

void PyUnicode_InternInPlace(PyObject **p_unicode)¶: Часть Стабильный ABI.
Вставьте аргумент *p_unicode на место. Аргумент должен быть адресом переменной-указателя, указывающей на строковый объект Python Unicode. Если уже существует интернированная строка, совпадающая с *p_unicode, она устанавливает *p_unicode на нее (освобождая ссылку на старый строковый объект и создавая новый strong reference на интернированный строковый объект), в противном случае она оставляет *p_unicode в покое и интернирует его (создавая новый strong reference). (Пояснение: несмотря на то что много говорят о ссылках, считайте эту функцию нейтральной к ссылкам; вы владеете объектом после вызова, если и только если вы владели им до вызова).

PyObject *PyUnicode_InternFromString(const char *str)¶: Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Комбинация PyUnicode_FromString() и PyUnicode_InternInPlace(), возвращающая либо новый строковый объект Unicode, который был интернирован, либо новую («собственную») ссылку на ранее интернированный строковый объект с тем же значением.

Объекты и кодеки Юникода¶

Объекты Юникода¶

Тип Юникода¶

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

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

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

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

wchar_t Поддержка¶

Встроенные кодеки¶

Общие кодеки¶

Кодеки UTF-8¶

Кодеки UTF-32¶

Кодеки UTF-16¶

Кодеки UTF-7¶

Кодеки Unicode-Escape¶

Кодеки Raw-Unicode-Escape¶

Кодеки Latin-1¶

Кодеки ASCII¶

Кодеки для карт символов¶

Кодеки MBCS для Windows¶

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

Методы и функции слотов¶

Оглавление

Предыдущий раздел

Следующий раздел