Объекты и кодеки Unicode

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

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

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

Из-за перехода между старыми и новыми API-интерфейсами объекты Unicode могут находиться в двух состояниях в зависимости от того, как они были созданы:

  • «канонические» объекты Unicode - это все объекты, созданные с помощью не устаревшего Unicode API. Они используют наиболее эффективное представление, разрешенное реализацией.

  • «устаревшие» объекты Unicode были созданы с помощью одного из устаревших API (обычно: c:func:PyUnicode_FromUnicode) и содержат только Py_UNICODE*; вам нужно будет вызвать PyUnicode_READY() для них, прежде чем вызывать какие-либо другие. другой API.

Примечание

«Устаревший» объект Unicode будет удален в Python 3.12 с устаревшими API. С тех пор все объекты Unicode будут «каноническими». Дополнительную информацию смотрите в разделе PEP 623.

Тип Unicode

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

type Py_UCS4
type Py_UCS2
type Py_UCS1
Part of the Стабильный ABI.

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

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

type Py_UNICODE

Это typedef типа wchar_t, который является 16-разрядным или 32-разрядным типом в зависимости от платформы.

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

type PyASCIIObject
type PyCompactUnicodeObject
type PyUnicodeObject

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

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

PyTypeObject PyUnicode_Type
Part of the Стабильный ABI.

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

Следующие API-интерфейсы представляют собой макросы C и статические встроенные функции для быстрой проверки и доступа к внутренним данным объектов Unicode, доступным только для чтения:

int PyUnicode_Check(PyObject *obj)

Возвращает значение true, если объект obj является объектом Unicode или экземпляром подтипа Unicode. Эта функция всегда выполняется успешно.

int PyUnicode_CheckExact(PyObject *obj)

Возвращает значение true, если объект obj является объектом Unicode, но не экземпляром подтипа. Эта функция всегда выполняется успешно.

int PyUnicode_READY(PyObject *unicode)

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

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

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

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

Py_ssize_t PyUnicode_GET_LENGTH(PyObject *unicode)

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

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

Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *unicode)
Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *unicode)
Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *unicode)

Возвращает указатель на каноническое представление, приведенное к целочисленным типам UCS1, UCS2 или UCS4 для прямого доступа к символам. Проверка правильности размера символов в каноническом представлении не выполняется; используйте PyUnicode_KIND() для выбора правильного макроса. Убедитесь, что PyUnicode_READY() был вызван, прежде чем обращаться к нему.

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

PyUnicode_WCHAR_KIND
PyUnicode_1BYTE_KIND
PyUnicode_2BYTE_KIND
PyUnicode_4BYTE_KIND

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

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

Утратил актуальность с версии 3.10, будет удален в версии 3.12: PyUnicode_WCHAR_KIND является устаревшим.

int PyUnicode_KIND(PyObject *unicode)

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

Считывает кодовую точку из канонического представления данных (полученного с помощью 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: Часть старого интерфейса Unicode API, пожалуйста, перейдите на использование: c:func:PyUnicode_GET_LENGTH.

Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *unicode)

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

Утратил актуальность с версии 3.3, будет удален в версии 3.12: Часть старого интерфейса Unicode API, пожалуйста, перейдите на использование: c:func: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: Являясь частью устаревшего Unicode API, пожалуйста, перейдите на использование семейства макросов PyUnicode_nBYTE_DATA().

int PyUnicode_IsIdentifier(PyObject *unicode)
Part of the Стабильный 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, преобразованный в нижний регистр.

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

Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4 ch)

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

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

Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4 ch)

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

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

int Py_UNICODE_TODECIMAL(Py_UCS4 ch)

Возвращает символ ch, преобразованный в десятичное положительное целое число. Верните -1, если это невозможно. Этот макрос не вызывает исключений.

int Py_UNICODE_TODIGIT(Py_UCS4 ch)

Возвращает символ ch, преобразованный в однозначное целое число. Верните -1, если это невозможно. Этот макрос не вызывает исключений.

double Py_UNICODE_TONUMERIC(Py_UCS4 ch)

Верните символ ch, преобразованный в double. Верните -1.0, если это невозможно. Этот макрос не вызывает исключений.

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

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_UCS 4. high и low являются соответственно начальными и конечными суррогатами в суррогатной паре.

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

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

PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)
Возвращаемое значение: Новая ссылка.

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

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

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

PyObject *PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)
Возвращаемое значение: Новая ссылка.

Создайте новый объект Unicode с заданным видом (возможные значения PyUnicode_1BYTE_KIND и т.д., возвращаемые с помощью PyUnicode_KIND()). Буфер должен указывать на массив единиц размера по 1, 2 или 4 байта на символ, в зависимости от типа.

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

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

PyObject *PyUnicode_FromStringAndSize(const char *str, Py_ssize_t size)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

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

PyObject *PyUnicode_FromString(const char *str)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

PyObject *PyUnicode_FromFormat(const char *format, ...)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

Форматирование символов

Тип

Комментарий

%%

н/д

Буквальный символ %.

%c

инт

Один символ, представленный в виде C int.

%d

инт

Эквивалентно printf("%d"). [1]

%u

неподписанный int

Эквивалентно printf("%u"). [1]

%ld

длинный

Эквивалентно printf("%ld"). [1]

%li

длинный

Эквивалентно printf("%li"). [1]

%lu

неподписанный длинный

Эквивалентно printf("%lu"). [1]

%lld

долго, долго

Эквивалентно printf("%lld"). [1]

%lli

долго, долго

Эквивалентно printf("%lli"). [1]

%llu

неподписанный длинный длинный

Эквивалентно printf("%llu"). [1]

%zd

Py_ssize_t

Эквивалентно printf("%zd"). [1]

%zi

Py_ssize_t

Эквивалентно printf("%zi"). [1]

%zu

размер_t

Эквивалентно printf("%zu"). [1]

%i

инт

Эквивалентно printf("%i"). [1]

%x

инт

Эквивалентно printf("%x"). [1]

%s

постоянный символ*

Массив символов языка Си, заканчивающийся нулем.

%p

постоянная пустота*

Шестнадцатеричное представление указателя на языке Си. В основном эквивалентно printf("%p"), за исключением того, что оно гарантированно начинается с литерала 0x независимо от того, что дает printf на платформе.

%A

PyObject (объект поиска)*

Результат вызова ascii().

%U

PyObject (объект поиска)*

Объект в Юникоде.

%V

PyObject*, постоянный символ*

Объект Unicode (который может быть NULL) и завершающийся нулем массив символов C в качестве второго параметра (который будет использоваться, если первый параметр равен NULL).

%S

PyObject (объект поиска)*

Результат вызова PyObject_Str().

%R

PyObject (объект поиска)*

Результат вызова PyObject_Repr().

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

Примечание

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

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

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

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

PyObject *PyUnicode_FromFormatV(const char *format, va_list vargs)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

PyObject *PyUnicode_FromObject(PyObject *obj)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

При необходимости скопируйте экземпляр подтипа Unicode в новый объект true Unicode. Если obj уже является объектом true Unicode (а не подтипом), верните объекту новый strong reference.

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

PyObject *PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

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

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

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

Py_ssize_t PyUnicode_GetLength(PyObject *unicode)
Part of the Стабильный ABI since version 3.7.

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

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

Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t from_start, Py_ssize_t how_many)

Копирование символов из одного объекта Unicode в другой. При необходимости эта функция выполняет преобразование символов и, если возможно, возвращается к memcpy(). Возвращает -1 и устанавливает исключение при ошибке, в противном случае возвращает количество скопированных символов.

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

Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)

Заполните строку символом: введите fill_char в unicode[start:start+length].

Ошибка возникает, если fill_char больше максимального значения в строке или если строка содержит более 1 ссылки.

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

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

int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)
Part of the Стабильный ABI since version 3.7.

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

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

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

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)
Part of the Стабильный ABI since version 3.7.

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

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

PyObject *PyUnicode_Substring(PyObject *unicode, Py_ssize_t start, Py_ssize_t end)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI since version 3.7.

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

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

Py_UCS4 *PyUnicode_AsUCS4(PyObject *unicode, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)
Part of the Стабильный ABI since version 3.7.

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

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

Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)
Part of the Стабильный ABI since version 3.7.

Скопируйте строку unicode в новый буфер UCS4, который выделяется с помощью PyMem_Malloc(). Если это не удается, NULL возвращается с набором MemoryError. К возвращаемому буферу всегда добавляется дополнительная нулевая кодовая точка.

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

Устаревшие API-интерфейсы Py_UNICODE

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

Эти функции 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: Часть старого интерфейса Unicode API, пожалуйста, перейдите на использование : c:func:PyUnicode_FromKindAndData, PyUnicode_FromWideChar() или PyUnicode_New().

Py_UNICODE *PyUnicode_AsUnicode(PyObject *unicode)

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

Утратил актуальность с версии 3.3, будет удален в версии 3.12: Часть старого интерфейса Unicode API, пожалуйста, перейдите на использование 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: Часть старого интерфейса Unicode API, пожалуйста, перейдите на использование PyUnicode_AsUCS4(), PyUnicode_AsWideChar(), PyUnicode_ReadChar() или аналогичных новых API.

Py_ssize_t PyUnicode_GetSize(PyObject *unicode)
Part of the Стабильный ABI.

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

Утратил актуальность с версии 3.3, будет удален в версии 3.12: Часть старого интерфейса Unicode API, пожалуйста, перейдите на использование: c:func:PyUnicode_GET_LENGTH.

Языковая кодировка

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

PyObject *PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t length, const char *errors)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI since version 3.7.

Расшифруйте строку из UTF-8 на Android и VxWorks или из текущей языковой кодировки на других платформах. Поддерживаемыми обработчиками ошибок являются "strict" и "surrogateescape" (PEP 383). Декодер использует обработчик ошибок "strict", если значение errors равно NULL. str должен заканчиваться нулевым символом, но не может содержать встроенных нулевых символов.

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

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

См.также

Функция Py_DecodeLocale().

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

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

PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI since version 3.7.

Аналогично PyUnicode_DecodeLocaleAndSize(), но вычисляем длину строки, используя strlen().

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

PyObject *PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI since version 3.7.

Закодируйте объект Unicode в UTF-8 на Android и VxWorks или в текущей языковой кодировке на других платформах. Поддерживаемыми обработчиками ошибок являются "strict" и "surrogateescape" (PEP 383). Кодировщик использует обработчик ошибок "strict", если значение errors равно NULL. Возвращает объект bytes. unicode не может содержать встроенных нулевых символов.

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

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

См.также

Функция 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)
Part of the Стабильный ABI.

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

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

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

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

int PyUnicode_FSDecoder(PyObject *obj, void *result)
Part of the Стабильный ABI.

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

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

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

PyObject *PyUnicode_DecodeFSDefaultAndSize(const char *str, Py_ssize_t size)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

Расшифруйте строку из filesystem encoding and error handler.

Если значение Py_FileSystemDefaultEncoding не задано, вернитесь к языковой кодировке.

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

См.также

Функция Py_DecodeLocale().

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

PyObject *PyUnicode_DecodeFSDefault(const char *str)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

Расшифруйте строку, заканчивающуюся нулем, из filesystem encoding and error handler.

Если значение Py_FileSystemDefaultEncoding не задано, вернитесь к языковой кодировке.

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

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

PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)
Возвращаемое значение: Новая ссылка. Part of the Стабильный 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)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *wstr, Py_ssize_t size)
Part of the Стабильный ABI.

Скопируйте содержимое объекта Unicode в буфер wchar_t wstr. Копируются символы не более размера wchar_t (за исключением, возможно, завершающего нулевого символа). Возвращает количество скопированных символов wchar_t или -1 в случае ошибки.

Когда значение wstr равно NULL, вместо этого возвращайте значение size, которое потребуется для хранения всего unicode, включая завершающий null.

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

wchar_t *PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)
Part of the Стабильный ABI since version 3.7.

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

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

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

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

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

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

Многие из приведенных ниже API-интерфейсов принимают два аргумента encoding и errors и имеют ту же семантику, что и встроенные str() string object constructor.

Установка значения encoding на NULL приводит к использованию кодировки по умолчанию, которая является UTF-8. Вызовы файловой системы должны использовать PyUnicode_FSConverter() для кодирования имен файлов. При этом используется внутренняя переменная Py_FileSystemDefaultEncoding. Эта переменная должна быть доступна только для чтения: в некоторых системах это будет указатель на статическую строку, в других она будет изменяться во время выполнения (например, когда приложение вызывает setlocale).

Обработка ошибок задается параметром errors, для которого также может быть установлено значение NULL, что означает использование обработки по умолчанию, определенной для кодека. Обработка ошибок по умолчанию для всех встроенных кодеков является «строгой» (значение ValueError).

Все кодеки используют схожий интерфейс. Для простоты описаны только отклонения от приведенных ниже общих описаний.

Универсальные кодеки

Это общие API-интерфейсы кодеков:

PyObject *PyUnicode_Decode(const char *str, Py_ssize_t size, const char *encoding, const char *errors)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

Создайте объект Unicode, расшифровав размер байт закодированной строки str. encoding и errors имеют то же значение, что и одноименные параметры во встроенной функции str(). Используемый кодек ищется с помощью реестра кодеков Python. Возвращает NULL, если кодек вызвал исключение.

PyObject *PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)
Возвращаемое значение: Новая ссылка. Part of the Стабильный 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)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

PyObject *PyUnicode_DecodeUTF8Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

PyObject *PyUnicode_AsUTF8String(PyObject *unicode)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

Закодируйте объект Unicode, используя UTF-8, и верните результат в виде объекта Python bytes. Обработка ошибок является «строгой». Верните NULL, если кодек вызвал исключение.

const char *PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)
Part of the Стабильный ABI since version 3.10.

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

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

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

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

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

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

const char *PyUnicode_AsUTF8(PyObject *unicode)

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

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

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

Кодеки UTF-32

Это API-интерфейсы кодека UTF-32:

PyObject *PyUnicode_DecodeUTF32(const char *str, Py_ssize_t size, const char *errors, int *byteorder)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

Декодируйте размер байт из строки буфера, закодированной в UTF-32, и верните соответствующий объект Unicode. ошибки (если не``NULL``) определяет обработку ошибок. По умолчанию используется значение «строгий».

Если значение byteorder не равно``NULL``, декодер начинает декодирование с использованием заданного порядка байтов:

*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian

Если *byteorder равно нулю, а первые четыре байта входных данных представляют собой метку порядка байтов (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)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

PyObject *PyUnicode_AsUTF32String(PyObject *unicode)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

Возвращает строку байтов Python, используя кодировку UTF-32 в обычном порядке байтов. Строка всегда начинается с метки спецификации. Обработка ошибок является «строгой». Возвращает NULL, если кодек вызвал исключение.

Кодеки UTF-16

Это API-интерфейсы кодека UTF-16:

PyObject *PyUnicode_DecodeUTF16(const char *str, Py_ssize_t size, const char *errors, int *byteorder)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

Декодируйте размер байт из строки буфера, закодированной в UTF-16, и верните соответствующий объект Unicode. ошибки (если не``NULL``) определяет обработку ошибок. По умолчанию используется значение «строгий».

Если значение byteorder не равно``NULL``, декодер начинает декодирование с использованием заданного порядка байтов:

*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian

Если *byteorder равно нулю, а первые два байта входных данных представляют собой метку порядка байтов (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)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

PyObject *PyUnicode_AsUTF16String(PyObject *unicode)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

Возвращает строку байтов Python, используя кодировку UTF-16 в обычном порядке байтов. Строка всегда начинается с метки спецификации. Обработка ошибок является «строгой». Возвращает NULL, если кодек вызвал исключение.

Кодеки UTF-7

Это API-интерфейсы кодека UTF-7:

PyObject *PyUnicode_DecodeUTF7(const char *str, Py_ssize_t size, const char *errors)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

PyObject *PyUnicode_DecodeUTF7Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

Если значение consumed равно NULL, ведите себя следующим образом:c:func:PyUnicode_DecodeUTF7. Если значение consumed не равно NULL, завершающие неполные разделы UTF-7 base64 не будут рассматриваться как ошибка. Эти байты не будут декодированы, а количество декодированных байт будет сохранено в использованном.

Escape-кодеки в Юникоде

Это API-интерфейсы кодека «Unicode Escape»:

PyObject *PyUnicode_DecodeUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

Создайте объект Unicode, расшифровав размер байт строки, закодированной в Unicode-Escape, str. Верните NULL, если кодек вызвал исключение.

PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
Возвращаемое значение: Новая ссылка. Part of the Стабильный 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)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
Возвращаемое значение: Новая ссылка. Part of the Стабильный 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)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

PyObject *PyUnicode_AsLatin1String(PyObject *unicode)
Возвращаемое значение: Новая ссылка. Part of the Стабильный 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)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

PyObject *PyUnicode_AsASCIIString(PyObject *unicode)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

Кодеки для отображения символов

Этот кодек уникален тем, что его можно использовать для реализации множества различных кодеков (и именно это было сделано для получения большинства стандартных кодеков, включенных в пакет encodings). Кодек использует сопоставления для кодирования и декодирования символов. Предоставляемые объекты отображения должны поддерживать интерфейс отображения __getitem__(); словари и последовательности работают хорошо.

Это API-интерфейсы кодеков отображения:

PyObject *PyUnicode_DecodeCharmap(const char *str, Py_ssize_t length, PyObject *mapping, const char *errors)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

Если отображение равно NULL, то будет применено декодирование латиницей-1. Else отображение должно отображать порядковые номера байтов (целые числа в диапазоне от 0 до 255) в строки Unicode, целые числа (которые затем интерпретируются как порядковые номера Unicode) или None. Несопоставленные байты данных - те, которые вызывают LookupError, а также те, которые сопоставляются с None, 0xFFFE или '\ufffe', рассматриваются как неопределенные сопоставления и вызывают ошибку.

PyObject *PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

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

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

PyObject *PyUnicode_Translate(PyObject *unicode, PyObject *table, const char *errors)
Возвращаемое значение: Новая ссылка. Part of the Стабильный 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)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI on Windows since version 3.7.

Создайте объект Unicode, расшифровав размер байт строки, закодированной в MBCS, str. Верните NULL, если кодек вызвал исключение.

PyObject *PyUnicode_DecodeMBCSStateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI on Windows since version 3.7.

Если значение consumed равно NULL, ведите себя следующим образом PyUnicode_DecodeMBCS(). Если значение consumed не равно NULL, PyUnicode_DecodeMBCSStateful() не будет декодировать завершающий начальный байт, и количество декодированных байт будет сохранено в consumed.

PyObject *PyUnicode_AsMBCSString(PyObject *unicode)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI on Windows since version 3.7.

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

PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI on Windows since version 3.7.

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

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

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

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

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

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

PyObject *PyUnicode_Concat(PyObject *left, PyObject *right)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

Объедините две строки, получив новую строку в Юникоде.

PyObject *PyUnicode_Split(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

Разделите строку, чтобы получить список строк в Юникоде. Если sep равно NULL, то разделяются все подстроки, содержащие пробелы. В противном случае разделы выполняются на заданном разделителе. Будет выполнено не более maxsplit разбиений. Если значение отрицательное, ограничение не устанавливается. Разделители не включаются в результирующий список.

PyObject *PyUnicode_Splitlines(PyObject *unicode, int keepends)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

Разделите строку в Юникоде на разделители строк, возвращая список строк в Юникоде. CRLF считается разделителем на одну строку. Если значение keepends равно 0, символы разрыва строки не включаются в результирующие строки.

PyObject *PyUnicode_Join(PyObject *separator, PyObject *seq)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

Соедините последовательность строк, используя заданный разделитель *, и верните результирующую строку в Юникоде.

Py_ssize_t PyUnicode_Tailmatch(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
Part of the Стабильный 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)
Part of the Стабильный 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)
Part of the Стабильный ABI since version 3.7.

Возвращает первую позицию символа ch в unicode[start:end], используя заданное направление (направление == 1 означает выполнение прямого поиска, направление == -1 - обратного поиска). Возвращаемое значение является индексом первого совпадения; значение -1 указывает на то, что совпадение найдено не было, а -2 указывает на то, что произошла ошибка и было установлено исключение.

Добавлено в версии 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)
Part of the Стабильный ABI.

Возвращает количество непересекающихся вхождений substr в unicode[start:end]. Возвращает -1, если произошла ошибка.

PyObject *PyUnicode_Replace(PyObject *unicode, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

Замените не более maxcount вхождений substr в unicode на replstr и верните результирующий объект Unicode. maxcount == -1 означает заменить все вхождения.

int PyUnicode_Compare(PyObject *left, PyObject *right)
Part of the Стабильный ABI.

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

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

int PyUnicode_CompareWithASCIIString(PyObject *unicode, const char *string)
Part of the Стабильный ABI.

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

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

PyObject *PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

  • 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)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

Возвращает новый строковый объект из format и args; это аналогично format % args.

int PyUnicode_Contains(PyObject *unicode, PyObject *substr)
Part of the Стабильный ABI.

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

substr должен содержать одноэлементную строку в Юникоде. -1 возвращается, если произошла ошибка.

void PyUnicode_InternInPlace(PyObject **p_unicode)
Part of the Стабильный ABI.

Вставьте аргумент *p_unicode на место. Аргумент должен быть адресом переменной-указателя, указывающей на строковый объект Python в Юникоде. Если существует интернированная строка, которая совпадает с *p_unicode, она присваивает ей значение *p_unicode (освобождая ссылку на старый объект string и создавая новый strong reference для интернированного объекта string), в противном случае он оставляет : c:expr:*p_unicode в покое и интернирует его (создавая новый strong reference). (Уточнение: несмотря на то, что сейчас много говорят о ссылках, думайте об этой функции как о нейтральной по отношению к ссылкам; вы являетесь владельцем объекта после вызова тогда и только тогда, когда он принадлежал вам до вызова.)

PyObject *PyUnicode_InternFromString(const char *str)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

Комбинация PyUnicode_FromString() и PyUnicode_InternInPlace(), возвращающая либо новый строковый объект Unicode, который был интернирован, либо новую («принадлежащую») ссылку на ранее интернированный строковый объект с тем же значением.

Вернуться на верх