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

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

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

Представления Py_UNICODE* и UTF-8 создаются по запросу и кэшируются в юникод объекте. Представление Py_UNICODE* является устаревшим и неэффективным; его следует избегать в ситуациях, чувствительных к производительности или памяти.

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

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

Примечание

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

Юникод тип¶

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

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

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

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

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

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

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

PyTypeObject PyUnicode_Type¶: Сущность PyTypeObject представляет тип Python юникод. Подвергается воздействию Python кодом как str.

Следующие API действительно являются макросами C и могут использоваться для выполнения быстрых проверок и доступа к внутренним данным объектов юникода только для чтения:

int PyUnicode_Check(PyObject *o)¶: Возвращает true, если o объекта является объектом юникода или сущностью подтипа юникода.

int PyUnicode_CheckExact(PyObject *o)¶: Возвращает true, если o объекта является объектом юникода, но не сущностью подтипа.

int PyUnicode_READY(PyObject *o)¶

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

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

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

Deprecated since version 3.10, will be removed in version 3.12: Этот API будет удален вместе с PyUnicode_FromUnicode().

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

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

Py_UCS1* PyUnicode_1BYTE_DATA(PyObject *o)¶
Py_UCS2* PyUnicode_2BYTE_DATA(PyObject *o)¶
Py_UCS4* PyUnicode_4BYTE_DATA(PyObject *o)¶: Возвращает указатель на каноническое представление, приведенное к 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.

Deprecated since version 3.10, will be removed in version 3.12: PyUnicode_WCHAR_KIND устарел.

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

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

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

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

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

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

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

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

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

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

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

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

int PyUnicode_ClearFreeList()¶: Очистить свободный список. Возвращает общее количество освобожденных элементов.

Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)¶: Возвращает размер устаревшего представления Py_UNICODE, в кодовых единицах (это включает суррогатные пары как 2 юнита). o должен быть объектом юникода (не установлен).

Deprecated since version 3.3, will be removed in version 3.12: Часть API-интерфейса Unicode старого стиля, мигрируйте к использованию PyUnicode_GET_LENGTH().

Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)¶: Возвращает размер устаревшего представления Py_UNICODE в байтах. o должен быть объектом юникода (не установлен).

Deprecated since version 3.3, will be removed in version 3.12: Часть API-интерфейса Unicode старого стиля, перейдите к использованию PyUnicode_GET_LENGTH().

Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)¶
const char* PyUnicode_AS_DATA(PyObject *o)¶: Возвращает указатель на Py_UNICODE представление объекта. Возвращенный буфер всегда завершается дополнительной нулевой кодовой точкой. Он также может содержать внедренные нулевые кодовые точки, что приведет к усечению строки при использовании в большинстве C функций. Форма AS_DATA помещает указатель на const char *. Аргумент o должен быть объектом юникода (не проверено).

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

Deprecated since version 3.3, will be removed in version 3.12: Часть API-интерфейса юникод старого стиля, перейдите к использованию семейства макросов PyUnicode_nBYTE_DATA().

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

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

int Py_UNICODE_ISSPACE(Py_UNICODE ch)¶: Возвращает 1 или 0 в зависимости от того, является ли ch пробельным символом.

int Py_UNICODE_ISLOWER(Py_UNICODE ch)¶: Возвращает 1 или 0 в зависимости от того, является ли ch строчным символом.

int Py_UNICODE_ISUPPER(Py_UNICODE ch)¶: Возвращает 1 или 0 в зависимости от того, является ли ch символом в верхнем регистре.

int Py_UNICODE_ISTITLE(Py_UNICODE ch)¶: Возвращает 1 или 0 в зависимости от того, является ли ch заглавным символом.

int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)¶: Возвращает 1 или 0 в зависимости от того, является ли ch символ перевода на новую строку.

int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)¶: Возвращает 1 или 0 в зависимости от того, является ли ch десятичным символом.

int Py_UNICODE_ISDIGIT(Py_UNICODE ch)¶: Возвращает 1 или 0 в зависимости от того, является ли ch цифровым символом.

int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)¶: Возвращает 1 или 0 в зависимости от того, является ли ch числовым символом.

int Py_UNICODE_ISALPHA(Py_UNICODE ch)¶: Возвращает 1 или 0 в зависимости от того, является ли ch алфавитным символом.

int Py_UNICODE_ISALNUM(Py_UNICODE ch)¶: Возвращает 1 или 0 в зависимости от того, является ли ch буквенно-цифровым символом.

int Py_UNICODE_ISPRINTABLE(Py_UNICODE ch)¶: Возвращает 1 или 0 в зависимости от того, является ли ch печатаемым символом. Непечатаемые символы - это символы, определенные в базе данных юникод символ как «Other» или «Separator», за исключением пространства ASCII (0x20), которое считается печатаемым. (Обратите внимание, что печатаемые символы в этом контексте - это символы, которые не следует удалять при вызове repr() на строке. Он не имеет отношения к обработке строки, написанных на sys.stdout или sys.stderr.)

API можно использовать для быстрых прямых преобразований символов:

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

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

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

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

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

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

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

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

double Py_UNICODE_TONUMERIC(Py_UNICODE 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_UCS4 значение. high и low являются соответственно передним и задним суррогатами в суррогатной паре.

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

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

PyObject* PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)¶

Return value: New reference.

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

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

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

PyObject* PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)¶: Return value: New reference.
Создание нового объекта юникода с заданным kind (возможные значения - PyUnicode_1BYTE_KIND и т.д., как возвращенный PyUnicode_KIND()). buffer должен указывать на массив из size единиц размером 1, 2 или 4 байта в символ в соответствии с типом.

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

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

Return value: New reference.

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

Если u NULL, эта функция ведет себя как PyUnicode_FromUnicode() с буфером, имеющим значение NULL. Это использование устаревает в пользу PyUnicode_New().

PyObject *PyUnicode_FromString(const char *u)¶: Return value: New reference.
Создайте объект Unicode из буфера символов u с нулевым завершением в кодировке UTF-8.

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

Return value: New reference.

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

..% Должно быть точно так же, как таблица в PyErr_Format. ..% Описания %zd и %zu неверны, но правда сложна ..% потому что не все компиляторы поддерживают модификатор ширины %z – мы подделываем его ..% при необходимости с помощью интерполяции PY_FORMAT_SIZE_T. ..% подобные комментарии относятся к модификатору ширины %ll и

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

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

Примечание

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

[1]	(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13) Для целочисленных спецификаторов (d, u, ld, li, lu, lld, lli, llu, zd, zi, zu, i, x) флаг 0-преобразования действует даже при задании точности.

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

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

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

PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)¶: Return value: New reference.
Идентичен PyUnicode_FromFormat() за исключением того, что он занимает ровно два аргумента.

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

Return value: New reference.

Декодирование объекта кодированный, obj юникод объекта.

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

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

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

Py_ssize_t PyUnicode_GetLength(PyObject *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)¶: Копирование символов из одного объекта юникода в другой. При необходимости эта функция выполняет преобразование символов и по возможности возвращается к 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)¶

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

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

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

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

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

PyObject* PyUnicode_Substring(PyObject *str, Py_ssize_t start, Py_ssize_t end)¶: Return value: New reference.
Возвращает подстроки str, с индекса start символа (включенного) в индекс end символ, (исключен). Отрицательные индексы не поддерживаются.

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

Py_UCS4* PyUnicode_AsUCS4(PyObject *u, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)¶: Скопировать строку u в буфер UCS4, включая пустой символ, если copy_null установлен. Возвращает NULL и устанавливает исключение при ошибке (в частности, SystemError, если buflen меньше длины u). buffer возвращается при успехе.

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

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

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

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

Deprecated since version 3.3, will be removed in version 4.0.

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

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

Return value: New reference.

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

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

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

Deprecated since version 3.3, will be removed in version 3.12: Часть старого стиля Unicode API, пожалуйста, перейдите на использование PyUnicode_FromKindAndData(), PyUnicode_FromWideChar() или PyUnicode_New().

Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)¶: Возвращает указатель только для чтения на внутренний буфер Py_UNICODE объекта юникода или NULL при ошибке. Создает Py_UNICODE* представление объекта, если оно еще не доступно. Буфер всегда завершается дополнительной нулевой кодовой точкой. Обратите внимание, что результирующая Py_UNICODE строка может также содержать внедренные нулевые кодовые точки, что приведет к усечению строки при используемый в большинстве функций C.

Deprecated since version 3.3, will be removed in version 3.12: Часть старого стиля Unicode API, пожалуйста, перейдите на использование PyUnicode_AsUCS4(), PyUnicode_AsWideChar(), PyUnicode_ReadChar() или аналогичных новых API.

Deprecated since version 3.3, will be removed in version 3.10.

PyObject* PyUnicode_TransformDecimalToASCII(Py_UNICODE *s, Py_ssize_t size)¶: Return value: New reference.
Создание объекта юникод, заменив все десятичные цифры Py_UNICODE буфере данного size цифрами ASCII 0-9 в соответствии с их десятичными значениями. Возвращает NULL, если возникает исключение.

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

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

Deprecated since version 3.3, will be removed in version 3.12: Часть старого стиля Unicode API, пожалуйста, перейдите на использование PyUnicode_AsUCS4(), PyUnicode_AsWideChar(), PyUnicode_ReadChar() или аналогичных новых API.

Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode)¶

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

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

Выполнить миграцию с использованием PyUnicode_AsUCS4Copy() или аналогичных новых API.

Py_ssize_t PyUnicode_GetSize(PyObject *unicode)¶: Возвращает размер запрещаемого представления Py_UNICODE, в кодовых единицах (это включает суррогатные пары как 2 единицы).

Deprecated since version 3.3, will be removed in version 3.12: Часть старого стиля Unicode API, пожалуйста, перейдите на использование PyUnicode_GET_LENGTH().

PyObject* PyUnicode_FromObject(PyObject *obj)¶

Return value: New reference.

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

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

Кодировка языкового стандарта¶

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

PyObject* PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t len, const char *errors)¶

Return value: New reference.

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

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

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

См.также

Функция Py_DecodeLocale().

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

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

PyObject* PyUnicode_DecodeLocale(const char *str, const char *errors)¶: Return value: New reference.
Аналогично PyUnicode_DecodeLocaleAndSize(), но вычисляет длину строки с помощью strlen().

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

PyObject* PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)¶

Return value: New reference.

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

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

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

См.также

Функция Py_EncodeLocale().

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

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

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

Чтобы закодировать и расшифровать имена файлов и другую строковую среду, Py_FileSystemDefaultEncoding должен использоваться для кодировки, и Py_FileSystemDefaultEncodeErrors должен использоваться как ошибкой обработчик (PEP 383 и PEP 529). Чтобы кодировать имена файлов для bytes во время парсинга аргументов, конвертер "O&" должен использоваться, передавая PyUnicode_FSConverter() как функцию преобразования:

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

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

Изменено в версии 3.6: Принимает путеподобный объект.

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

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

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

Изменено в версии 3.6: Принимает путеподобный объект.

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

Return value: New reference.

Расшифровать строку, используя Py_FileSystemDefaultEncoding и ошибку обработчика Py_FileSystemDefaultEncodeErrors.

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

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

См.также

Функция Py_DecodeLocale().

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

PyObject* PyUnicode_DecodeFSDefault(const char *s)¶

Return value: New reference.

Декодировать нуль завершенную строку, используя Py_FileSystemDefaultEncoding и обработчик ошибки Py_FileSystemDefaultEncodeErrors.

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

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

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

PyObject* PyUnicode_EncodeFSDefault(PyObject *unicode)¶

Return value: New reference.

Закодировать объект юникода для 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 *w, Py_ssize_t size)¶: Return value: New reference.
Создание объект юникода из w буфера wchar_t данного size. Передача -1 в качестве size указывающая на то, что функция должна сама вычислять длину, используя wcslen. Возвращает NULL при отказе.

Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *w, Py_ssize_t size)¶: Скопировать содержимое объекта юникода в w буфере wchar_t. Копируется не более size wchar_t символов (за исключением возможного конечного нулевого символ окончания). Возвращает количество wchar_t скопированных символов или -1 в случае ошибки. Обратите внимание, что результирующая wchar_t* строка может быть или не быть нулевой. На вызывающем лежит обязанность убедиться в том, что wchar_t* строка имеет нулевое значение в случае, если это требуется приложением. Также следует отметить, что wchar_t* строка может содержать нулевые символы, что приведет к усечению строки при использовании с большинством C функций.

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

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

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

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

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

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

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

Многие следующие API берут два аргумента кодировки и ошибки, и у них есть та же семантика, как у встроенной str() строки возвращающий конструктор.

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

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

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

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

Общее API кодировки:

PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)¶: Return value: New reference.
Создать объект юникод, расшифровав байты size кодированный строки s. encoding и errors имеют то же значение, что и одноименные параметры в встроенной функции str(). кодировки, подлежащий использовании, просматривается с помощью реестра Python кодировки. Возвращает NULL, если кодировка создала исключение.

PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)¶: Return value: New reference.
Закодировать юникод объект и вернуть результат как байтовый объект Python. encoding и errors имеют то же значение, что и одноименные параметры в методе юникода encode(). Используемая кодировка просматривается с помощью реестра Python кодировок. Возвращает NULL, если кодировка создала исключение.

PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)¶: Return value: New reference.
Закодировать Py_UNICODE буфера s данного size и возвращает объект байтов Python. encoding и errors имеют то же значение, что и одноименные параметры в методе юникода encode(). Используемая кодировка просматривается с помощью реестра Python кодировок. Возвращает NULL, если кодировка создала исключение.

Deprecated since version 3.3, will be removed in version 4.0: Часть старого стиля Py_UNICODE API; выполнить миграцию с использованием PyUnicode_AsEncodedString().

Кодировки UTF-8¶

API UTF-8 кодировки:

PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)¶: Return value: New reference.
Создать юникод объект, расшифровав байты size UTF-8 кодированной строки s. Возвращает NULL, если кодировка создала исключение.

PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶: Return value: New reference.
Если consumed NULL, весли себя как PyUnicode_DecodeUTF8(). Если consumed не NULL, завершающие неполные последовательности байтов UTF-8 не будут рассматриваться как ошибка. Эти байты не будут декодированы, и количество байтов, которые были декодированы, будет сохранено в consumed.

PyObject* PyUnicode_AsUTF8String(PyObject *unicode)¶: Return value: New reference.
Закодировать объект юникод с помощью UTF-8 и возвращает результат как объект Python байтов. Обработка ошибок «strict». Возвращает NULL, если кодировка создала исключение.

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

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

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

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

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

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

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

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

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

PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)¶: Return value: New reference.
Закодировать Py_UNICODE буфер s данного size, используя UTF-8 и вернуть объект байтов Python. Возвращает NULL, если кодировка создала исключение.

Deprecated since version 3.3, will be removed in version 4.0: Часть старого стиля Py_UNICODE API; перейдите на использование PyUnicode_AsUTF8String(), PyUnicode_AsUTF8AndSize() или PyUnicode_AsEncodedString().

Кодировки UTF-32¶

API UTF-32 кодировки:

PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)¶

Return value: New reference.

Расшифровать байты size из кодированный буферной строки UTF-32 и вернуть соответствующий юникод объект. errors (если не-NULL) определяет обработку ошибок. По умолчанию он имеет значение «strict».

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

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

Если *byteorder равно нулю, и первые четыре байта входных данных являются меткой порядка байтов (BOM), декодер переключается на этот порядок байтов, и BOM не копируется в результирующий строка юникода. Если *byteorder равно -1 или 1, на выход копируется любая метка порядка байтов.

После завершения *byteorder устанавливается в текущий порядок байтов в конце входных данных.

Если byteorder NULL, кодировка запускается в режиме собственного порядка.

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

PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)¶: Return value: New reference.
Если consumed NULL, вести себя как PyUnicode_DecodeUTF32(). Если consumed не является NULL, PyUnicode_DecodeUTF32Stateful() не будет рассматривать завершающие неполные последовательности байтов UTF-32 (например, число байтов, не разделяемое на четыре) как ошибку. Эти байты не будут декодированы, и количество байтов, которые были декодированы, будут сохранены в consumed.

PyObject* PyUnicode_AsUTF32String(PyObject *unicode)¶: Return value: New reference.
Возвращает Python байтовую строку с помощью UTF-32 кодировки в собственном порядке байтов. Этот строка всегда начинается с отметки спецификации. Обработка ошибок «strict». Возвращает NULL, если кодировка создала исключение.

PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)¶

Return value: New reference.

Возвращает объект байтов Python, содержащее UTF-32 кодированные значения данных юникода в s. Вывод записывается в соответствии со следующим порядком байтов:

byteorder == -1: little endian
byteorder == 0:  native byte order (writes a BOM mark)
byteorder == 1:  big endian

Если 0 порядок байтов, строка вывода всегда начинается с отметки спецификации юникода (U+FEFF). В двух других режимах метка спецификации не добавляется.

Если Py_UNICODE_WIDE не определено, суррогатные пары будут выводиться как одна кодовая точка.

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

Deprecated since version 3.3, will be removed in version 4.0: Часть старого стиля Py_UNICODE API; выполните миграцию с использованием PyUnicode_AsUTF32String() или PyUnicode_AsEncodedString().

Кодировки UTF-16¶

API UTF-16 кодировки:

PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)¶

Return value: New reference.

Расшифровать байты size из буферной строки UTF-16 кодированный и возвращает соответствующий объект юникода. errors (если не-NULL) определяет обработку ошибок. По умолчанию он имеет значение «strict».

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

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

Если *byteorder равно нулю, и первые два байта входных данных являются меткой порядка байтов (BOM), декодер переключается на этот порядок байтов, и BOM не копируется в результирующую строку юникода. Если *byteorder равно -1 или 1, любая метка порядка байтов копируется в выходной файл (где это приведет либо к \ufeff, либо к \ufffe символу).

После завершения *byteorder устанавливается в текущем порядоке байтов в конце входных данных.

Если byteorder NULL, кодировка запускается в режиме собственного порядка.

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

PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)¶: Return value: New reference.
Если consumed NULL, вести себя как PyUnicode_DecodeUTF16(). Если consumed не NULL, PyUnicode_DecodeUTF16Stateful() не будет рассматривать завершающие неполные последовательности UTF-16 байтов (например, нечетное число байтов или разделенную суррогатную пару) как ошибку. Эти байты не будут декодированы, и количество байтов, которые были декодированы, будет сохранено в consumed.

PyObject* PyUnicode_AsUTF16String(PyObject *unicode)¶: Return value: New reference.
Возвращает Python байтовую строку с помощью UTF-16 кодировки в собственном порядке байтов. Эта строка всегда начинается с отметки спецификации. Обработка ошибок «strict». Возвращает NULL, если кодировка создала исключение.

PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)¶

Return value: New reference.

Возвращает объект байтов Python, содержащий UTF-16 кодированный значение данных юникода в s. Вывод записывается в соответствии со следующим порядком байтов:

byteorder == -1: little endian
byteorder == 0:  native byte order (writes a BOM mark)
byteorder == 1:  big endian

Если byteorder 0, выводная строка всегда начинается с отметки спецификации юникода (U+FEFF). В двух других режимах метка спецификации не добавляется.

Если Py_UNICODE_WIDE определено, одна Py_UNICODE значение может быть представлена как суррогатная пара. Если она не определена, каждое Py_UNICODE значение интерпретируется как UCS-2 символ.

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

Deprecated since version 3.3, will be removed in version 4.0: Часть старого стиля Py_UNICODE API; выполните миграцию с использованием PyUnicode_AsUTF16String() или PyUnicode_AsEncodedString().

Кодировки UTF-7¶

API UTF-7 кодировки:

PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)¶: Return value: New reference.
Создать объект Unicode, расшифровав байты size UTF-7 кодированный строкой s. Возвращает NULL, если кодировка создала исключение.

PyObject* PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶: Return value: New reference.
Если consumed NULL, вести себя как PyUnicode_DecodeUTF7(). Если consumed не NULL, завершение неполного UTF-7 base-64 раздела не будет рассматриваться как ошибка. Эти байты не будут декодированы, и количество байтов, которые были декодированы, будет сохранено в consumed.

PyObject* PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)¶

Return value: New reference.

Закодировать буфер Py_UNICODE заданного размера с помощью UTF-7 и вернуть объект байтов Python. Возвращает NULL, если кодировка создала исключение.

Если base64SetO ненулевое, в base-64 будет кодироваться «Set O» (пунктуация, не имеющая специального значения). Если base64WhiteSpace не равно нулю, пробел будет кодироваться в base-64. Для Python кодировки «utf-7» оба значения равны нулю.

Deprecated since version 3.3, will be removed in version 4.0: Часть старого стиля Py_UNICODE API; выполните миграцию с использованием PyUnicode_AsEncodedString().

Кодеки Unicode-Escape¶

API кодировки «Unicode Escape»:

PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)¶: Return value: New reference.
Создать юникод объект, расшифровав байты size кодированный строки s Unicode-escape. Возвращает NULL, если кодировка создал исключение.

PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)¶: Return value: New reference.
Закодировать объект юникод с помощью Unicode-Escape и возвратить результат в виде байтового объекта. Обработка ошибок - «strict». Возвращает NULL, если кодировка создала исключение.

PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)¶: Return value: New reference.
Закодировать буфер Py_UNICODE данного size с помощью Unicode-Escape и вернуть объект байтов. Возвращает NULL, если кодировка создала исключение.

Deprecated since version 3.3, will be removed in version 4.0: Часть старого стиля Py_UNICODE API; выполнить миграцию с использованием PyUnicode_AsUnicodeEscapeString().

Кодировка Raw-Unicode-Escape¶

API кодировки «Raw Unicode Escape»:

PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)¶: Return value: New reference.
Создать юникод объект, расшифровав байты size Raw-Unicode-Escape кодированной строки s. Возвращает NULL, если кодировка создала исключение.

PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)¶: Return value: New reference.
Закодировать объект юникода с помощью Raw-Unicode-Escape и возвращает результат в виде байтового объекта. Обработка ошибок - «strict». Возвращает NULL, если кодировка создала исключение.

PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)¶: Return value: New reference.
Закодировать буфер Py_UNICODE данного size с помощью Raw-Unicode-Escape и вернуть байтовый объект. Возвращает NULL, если кодировка создала исключение.

Deprecated since version 3.3, will be removed in version 4.0: Часть старого стиля Py_UNICODE API; выполните миграцию с использованием PyUnicode_AsRawUnicodeEscapeString() или PyUnicode_AsEncodedString().

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

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

PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)¶: Return value: New reference.
Создать юникод объект, расшифровав size байтов Latin-1 кодированную строку s. Возвращает NULL, если кодировка создала исключение.

PyObject* PyUnicode_AsLatin1String(PyObject *unicode)¶: Return value: New reference.
Закодировать юникод объекта с помощью Latin-1 и возвращает результат как байтовый объект Python. Обработка ошибок «strict». Возвращает NULL, если кодировка создала исключение.

PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)¶: Return value: New reference.
Закодировать буфер Py_UNICODE данного size, используя Latin-1 и возвращая байтовый объект Python. Возвращает NULL, если кодировка создала исключение.

Deprecated since version 3.3, will be removed in version 4.0: Часть старого стиля Py_UNICODE API; выполните миграцию с использованием PyUnicode_AsLatin1String() или PyUnicode_AsEncodedString().

Кодировки ASCII¶

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

PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)¶: Return value: New reference.
Создать юникод объект, расшифровать size байт кодированной строки s ASCII. Возвращает NULL, если кодировка создала исключение.

PyObject* PyUnicode_AsASCIIString(PyObject *unicode)¶: Return value: New reference.
Закодировать объект юникода с помощью ASCII и возвращает результат как объект Python байтов. Обработка ошибок «strict». Возвращает NULL, если кодировка создала исключение.

PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)¶: Return value: New reference.
Закодировать буфер Py_UNICODE данного size с помощью ASCII и вернуть объект байтов Python. Возвращает NULL, если кодировка создала исключение.

Deprecated since version 3.3, will be removed in version 4.0: Часть старого стиля Py_UNICODE API; выполните миграцию с использованием PyUnicode_AsASCIIString() или PyUnicode_AsEncodedString().

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

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

API кодировки сопоставления:

PyObject* PyUnicode_DecodeCharmap(const char *data, Py_ssize_t size, PyObject *mapping, const char *errors)¶

Return value: New reference.

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

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

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

Return value: New reference.

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

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

PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)¶: Return value: New reference.
Закодировать буфер Py_UNICODE данного size с помощью данного объекта mapping и возвращает результат в виде байтового объекта. Возвращает NULL, если кодировка создала исключение.

Deprecated since version 3.3, will be removed in version 4.0: Часть старого стиля Py_UNICODE API; выполните миграцию с использованием PyUnicode_AsCharmapString() или PyUnicode_AsEncodedString().

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

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

Return value: New reference.

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

Таблица сопоставления должна сопоставлять порядковые целые числа Unicode с порядковыми целыми числами Unicode или None (вызывая удаление символа).

Таблицы отображения должны обеспечивать только интерфейс __getitem__(); словари и последовательности работают хорошо. Неотмеченные порядковые номера символов (те, которые вызывают LookupError) остаются нетронутыми и копируются как есть.

errors имеет обычное значение для кодеков. Это может быть NULL, который указывает на использование обработки ошибок по умолчанию.

PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)¶: Return value: New reference.
Перевести буфер Py_UNICODE данного size, применив таблицу символов mapping к нему и возвращает получающийся юникод объект. Возвращает NULL, когда кодировка создала исключение.

Deprecated since version 3.3, will be removed in version 4.0: Часть старого стиля Py_UNICODE API; выполните миграцию с использованием PyUnicode_Translate() или общий API на основе кодеков

Кодировки MBCS для Windows¶

API кодировка MBCS. В настоящее время они доступны только в Windows и используют конвертеры MBCS Win32 для реализации преобразований. Следует отметить, что MBCS (или DBCS) - это класс кодировок, а не только одна. Целевая кодировка определяется пользовательскими настройками на компьютере, на котором выполняется кодировка.

PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)¶: Return value: New reference.
Создать юникод объект, расшифровав size байтов MBCS кодированной строки s. Возвращает NULL, если кодировка создала исключение.

PyObject* PyUnicode_DecodeMBCSStateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶: Return value: New reference.
Если consumed NULL, ведет себя как PyUnicode_DecodeMBCS(). Если consumed не NULL, PyUnicode_DecodeMBCSStateful() не будет декодировать конечный байт ввода, и количество байтов, которые были декодированы, будет сохранены в consumed.

PyObject* PyUnicode_AsMBCSString(PyObject *unicode)¶: Return value: New reference.
Закодировать объект юникода с помощью MBCS и возвращает результат как объект байтов Python. Обработка ошибок «strict». Возвращает NULL, если кодировка создала исключение.

PyObject* PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)¶: Return value: New reference.
Закодировать юникод объект с помощью указанной кодовой страницы и возвращает байтовый объект Python. Возвращает NULL, если кодировка создала исключение. Используйте CP_ACP кодовую страницу для получения кодера MBCS.

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

PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)¶: Return value: New reference.
Закодировать буфер Py_UNICODE данного size с помощью MBCS и вернуть объект байтов Python. Возвращает NULL, если кодировка создала исключение.

Deprecated since version 3.3, will be removed in version 4.0: Часть старого стиля Py_UNICODE API; перейдите на использование PyUnicode_AsMBCSString(), PyUnicode_EncodeCodePage() или PyUnicode_AsEncodedString().

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

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

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

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

PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)¶: Return value: New reference.
Две конкатенированные строки создают новую юникод строку.

PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)¶: Return value: New reference.
Разделить строку, чтобы получить список юникод строк. Если sep равен NULL, разделение будет выполняться во всех подстроках с пробелами. В противном случае разбиение происходит при заданном разделителе. Будет выполнено не более maxsplit разбиений. Если отрицательный, предел не установлен. Разделители не попадают в результирующий список.

PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)¶: Return value: New reference.
Разбить строку юникода на разрывы строк, возвращая список строк юникода. CRLF считается разрывом одной строки. Если keepend 0, символы разрыва строки не включаются в результирующие строки.

PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)¶: Return value: New reference.
Соединение последовательности строк с помощью заданного separator и возвращение результирующий строки юникода.

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

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

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

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

Изменено в версии 3.7: start и end теперь настроены так, чтобы вести себя как str[start:end].

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

PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)¶: Return value: New reference.
Замена не более maxcount вхождений substr в str на replstr и возвращает результирующий объект юникода. maxcount == -1 означает замену всех вхождений.

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

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

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

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

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

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

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

Return value: New reference.

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

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)¶: Return value: New reference.
Возвращает новый объект строки из format и args; это аналогично format % args.

int PyUnicode_Contains(PyObject *container, PyObject *element)¶

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

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

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

PyObject* PyUnicode_InternFromString(const char *v)¶: Return value: New reference.
Комбинация PyUnicode_FromString() и PyUnicode_InternInPlace(), возвращающая либо новый интернированный объект юникод строки, либо новую («принадлежащую») ссылку на более ранний интернированный объект строки с тем же значением.

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