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

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

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

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

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

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

Примечание

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

Юникод тип

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

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

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

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

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

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

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

PyTypeObject PyUnicode_Type: Данный экземпляр PyTypeObject представляет тип Юникод. Он отображается в коде Python как str.

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

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

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

int PyUnicode_READY(PyObject *o)

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

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

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

Устарело с версии 3.10, будет удалено в 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.

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

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

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

void* PyUnicode_DATA(PyObject *o): Возвращает пустой указатель на необработанный буфер Юникод. 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 должен быть объектом Юникод (не проверяется).

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

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

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

Устарело с версии 3.3, будет удалено в 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 печатным символом. Непечатаемые символы — это символы, определённые в базе данных символов Юникод как «Другой» или «Разделитель», за исключением пробела 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, преобразованный в двойной формат. Если это невозможно, возвращает -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.
Создать Юникод объект из буфера u, закодированного в кодировке UTF-8, с завершающим нулем.

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

Return value: New reference.

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

Форматные символы	Тип	Комментарий
`%%`		Литеральный символ %.
`%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

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

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

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

Return value: New reference.

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

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

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

Устарело с версии 3.3, будет удалено в 3.12 версии.: Часть старого интерфейса Юникод API, пожалуйста, перейдите на использование PyUnicode_FromKindAndData(), PyUnicode_FromWideChar() или PyUnicode_New().

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

Устарело с версии 3.3, будет удалено в 3.12 версии.: Часть старого интерфейса Юникод API, пожалуйста, перейдите на использование PyUnicode_AsUCS4(), PyUnicode_AsWideChar(), PyUnicode_ReadChar() или аналогичных новых API.

Устарело с версии 3.3, будет удалено в 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.

Устарело с версии 3.3, будет удалено в 3.12 версии.: Часть старого интерфейса Юникод 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 единицы).

Устарело с версии 3.3, будет удалено в 3.12 версии.: Часть старого стиля Юникод API, пожалуйста, перейдите на использование PyUnicode_GET_LENGTH().

PyObject* PyUnicode_FromObject(PyObject *obj)

Return value: New reference.

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

Объекты, отличные от Юникод или его подтипов, вызовут 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 должен заканчиваться нулевым символом, но не может содержать встроенные нулевые символы.

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

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

См.также

Функция Py_DecodeLocale().

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

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

PyObject* PyUnicode_DecodeLocale(const char *str, const char *errors): 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", если errors — это NULL. Возвращает объект bytes. unicode не может содержать встроенные нулевые символы.

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

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

См.также

Функция Py_EncodeLocale().

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

Изменено в версии 3.7: Функция теперь также использует текущую кодировку локали для обработчика ошибок surrogateescape, за исключением 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.
Создать Юникод объект из буфера wchar_t w данного size. Передача -1 в качестве size означает, что функция должна сама вычислить длину, используя wcslen. Возвращает NULL в случае ошибки.

Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *w, Py_ssize_t size): Скопировать содержимое объекта Юникод в буфер wchar_t w. Копируется не более 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. Эту переменную следует рассматривать как доступную только для чтения: в некоторых системах она будет указателем на статическую строку, в других она будет изменяться во время выполнения (например, когда приложение вызывает setlocale).

Обработка ошибок устанавливается ошибками, которые также могут иметь значение 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, если кодек вызвал исключение.

Устарело с версии 3.3, будет удалено в 4.0 версии.: Часть старого API Py_UNICODE; пожалуйста, перейдите на использование 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 байтов строки s в кодировке UTF-8. Возвращает 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; в этом случае размер не сохраняется. К возвращаемому буферу всегда добавляется дополнительный нулевой байт (не включён в size), независимо от того, есть ли какие-либо другие нулевые кодовые точки.

В случае ошибки возвращается 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, если кодек вызвал исключение.

Устарело с версии 3.3, будет удалено в 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) определяет обработку ошибок. По умолчанию это «строгий».

Если 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

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

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

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

Устарело с версии 3.3, будет удалено в 4.0 версии.: Часть старого API Py_UNICODE; перейдите на использование 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, выходная строка всегда будет начинаться с метки Юникод BOM (U+FEFF). В двух других режимах метка BOM не добавляется.

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

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

Устарело с версии 3.3, будет удалено в 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.
Создать Юникод объект, декодируя size байта строки s в кодировке UTF-7. Возвращает 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 отличен от нуля, «Set O» (знаки препинания, которые не имеют другого особого значения) будут закодированы в base-64. Если base64WhiteSpace отличен от нуля, пробелы будут закодированы в base-64. Для кодека Python «utf-7» оба установлены в ноль.

Устарело с версии 3.3, будет удалено в 4.0 версии.: Часть старого API Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsEncodedString().

Кодеки Unicode-Escape

API-интерфейсы кодеков «Юникод 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 с помощью Юникод- Escape и возвращает объект байтов. Возвращает NULL, если кодек вызвал исключение.

Устарело с версии 3.3, будет удалено в 4.0 версии.: Часть старого API Py_UNICODE; пожалуйста, перейдите на использование 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 байтов строки s, закодированной в Raw-Unicode-Escape. Возвращает 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, если кодек вызвал исключение.

Устарело с версии 3.3, будет удалено в 4.0 версии.: Часть старого API Py_UNICODE; перейдите на использование 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, если кодек вызвал исключение.

Устарело с версии 3.3, будет удалено в 4.0 версии.: Часть старого API Py_UNICODE; перейдите на использование 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 байта строки в кодировке ASCII s. Возвращает 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, если кодек вызвал исключение.

Устарело с версии 3.3, будет удалено в 4.0 версии.: Часть старого API Py_UNICODE; пожалуйста, перейдите на использование 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, если кодек вызвал исключение.

Устарело с версии 3.3, будет удалено в 4.0 версии.: Часть старого API Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsCharmapString() или PyUnicode_AsEncodedString().

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

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

Return value: New reference.

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

Таблица сопоставления должна сопоставлять порядковые целые числа Юникод с порядковыми целыми числами Юникод или 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, когда кодек вызвал исключение.

Устарело с версии 3.3, будет удалено в 4.0 версии.: Часть старого API Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_Translate() или общий API на основе кодеков

Кодеки MBCS для Windows

API-интерфейсы кодеков MBCS. В настоящее время они доступны только в Windows и используют конвертеры Win32 MBCS для реализации преобразований. Обратите внимание, что 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, если кодек вызвал исключение.

Устарело с версии 3.3, будет удалено в 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_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction): Возвращает 1, если substr соответствует str[start: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, и возвращает соответственно истину или ложь.

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