Объекты и кодеки 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
Эквивалентно
printf("%zd")
. [1]%zi
Эквивалентно
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_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, который был интернирован, либо новую («принадлежащую») ссылку на ранее интернированный строковый объект с тем же значением.