Содержание страницы

Объекты Unicode и кодеки¶Unicode Objects and Codecs

Объекты Unicode¶Unicode Objects

Тип Unicode¶Unicode Type

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

Py_UNICODE¶: Этот тип представляет тип хранения, который используется внутри Python в качестве основы для хранения порядковых номеров символов Unicode. В стандартной сборке Python используется 16-битный тип для Py_UNICODE, и значения Unicode хранятся внутри в UCS2. Также возможна сборка Python с UCS4 (большинство современных дистрибутивов Linux поставляются с UCS4-сборками Python). В таких сборках используется 32-битный тип для Py_UNICODE, и данные Unicode хранятся внутри в UCS4. На платформах, где wchar_t доступен и совместим с выбранным вариантом сборки Unicode Python, Py_UNICODE является псевдонимом typedef для wchar_t для улучшения совместимости с нативной платформой. На всех остальных платформах Py_UNICODE является псевдонимом typedef для unsigned short (UCS2) или unsigned long (UCS4).

Обратите внимание, что сборки Python с UCS2 и UCS4 не являются двоично совместимыми. Учитывайте это при написании расширений или интерфейсов.

PyUnicodeObject¶: Этот подтип PyObject представляет объект Unicode в Python.

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

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

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

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

Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)¶: Возвращает размер объекта. o должен быть PyUnicodeObject (не проверяется).

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

Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)¶: Возвращает указатель на внутренний буфер Py_UNICODE объекта. o должен быть PyUnicodeObject (не проверяется).

const char* PyUnicode_AS_DATA(PyObject *o)¶: Возвращает указатель на внутренний буфер объекта. o должен быть PyUnicodeObject (не проверяется).

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

Свойства символов Unicode¶Unicode Character Properties

Unicode предоставляет множество различных свойств символов. Наиболее востребованные из них доступны через следующие макросы, которые сопоставляются с функциями на 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 печатаемым символом. Непечатаемые символы – это символы, определённые в базе данных Unicode как «Other» или «Separator», за исключением пробела ASCII (0x20), который считается печатаемым. (Обратите внимание, что печатаемые символы в этом контексте – это те, которые не должны экранироваться при вызове repr() для строки. Это не влияет на обработку строк, записываемых в sys.stdout или sys.stderr.)

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

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

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

Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)¶: Возвращает символ ch, приведённый к регистру заголовка.

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, если это невозможно. Этот макрос не вызывает исключений.

Простой Py_UNICODE¶Plain Py_UNICODE

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

PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)¶: Возвращаемое значение: новая ссылка.
Создаёт объект Unicode из буфера Py_UNICODE u указанного размера. u может быть NULL, что делает содержимое неопределённым. Ответственность за заполнение нужными данными лежит на пользователе. Буфер копируется в новый объект. Если буфер не равен NULL, возвращаемое значение может быть разделяемым объектом. Поэтому изменение результирующего объекта Unicode допускается только когда u равно NULL.

PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)¶: Создаёт объект Unicode из буфера char u. Байты интерпретируются как кодировка UTF-8. u также может быть NULL, что делает содержимое неопределённым. Ответственность за заполнение нужными данными лежит на пользователе. Буфер копируется в новый объект. Если буфер не равен NULL, возвращаемое значение может быть разделяемым объектом. Поэтому изменение результирующего объекта Unicode допускается только когда u равно NULL.

PyObject *PyUnicode_FromString(const char *u)¶: Создаёт объект Unicode из UTF-8-кодированного символьного буфера с завершающим нулём u.

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

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

Символы формата	Тип	Описание
`%%`	н/д	Буквальный символ %.
`%c`	int	Одиночный символ, представленный как C int.
`%d`	int	Полностью эквивалентно `printf("%d")`.
`%u`	беззнаковый int	Полностью эквивалентно `printf("%u")`.
`%ld`	long	Полностью эквивалентно `printf("%ld")`.
`%lu`	беззнаковый long	Полностью эквивалентно `printf("%lu")`.
`%lld`	long long	Полностью эквивалентно `printf("%lld")`.
`%llu`	беззнаковый long long	Полностью эквивалентно `printf("%llu")`.
`%zd`	Py_ssize_t	Полностью эквивалентно `printf("%zd")`.
`%zu`	size_t	Полностью эквивалентно `printf("%zu")`.
`%i`	int	Полностью эквивалентно `printf("%i")`.
`%x`	int	Полностью эквивалентно `printf("%x")`.
`%s`	char*	Нуль-терминированный массив символов C.
`%p`	void*	Шестнадцатеричное представление указателя C. В основном эквивалентно `printf("%p")` за исключением того, что гарантированно начинается с литерала `0x` независимо от того, что выдает `printf` на данной платформе.
`%A`	PyObject*	Результат вызова `ascii()`.
`%U`	PyObject*	Unicode-объект.
`%V`	PyObject, char	Unicode-объект (может быть NULL) и завершающийся нулевым символом C-массив символов в качестве второго параметра (используется, если первый параметр равен NULL).
`%S`	PyObject*	Результат вызова `PyObject_Str()`.
`%R`	PyObject*	Результат вызова `PyObject_Repr()`.

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

Примечание

Спецификаторы формата "%lld" и "%llu" доступны только при определённом HAVE_LONG_LONG.

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

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

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

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

Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode)¶

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

Новое в версии 3.2.

Py_ssize_t PyUnicode_GetSize(PyObject *unicode)¶: Возвращает длину объекта Unicode.

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

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

Преобразует закодированный объект obj в объект Unicode и возвращает ссылку с увеличенным счётчиком ссылок.

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

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

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

PyObject* PyUnicode_FromObject(PyObject *obj)¶: Возвращаемое значение: новая ссылка.
Shortcut for PyUnicode_FromEncodedObject(obj, NULL, "strict") which is used throughout the interpreter whenever coercion to Unicode is needed.

Если платформа поддерживает wchar_t и предоставляет заголовочный файл wchar.h, Python может напрямую взаимодействовать с этим типом с помощью следующих функций. Поддержка оптимизируется, если собственный тип Py_UNICODE Python идентичен системному wchar_t.

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

Для кодирования и декодирования имён файлов и других строк окружения в качестве кодировки следует использовать Py_FileSystemEncoding, а в качестве обработчика ошибок – "surrogateescape" (PEP 383). Для кодирования имён файлов при разборе аргументов следует использовать преобразователь "O&", передавая PyUnicode_FSConverter() в качестве функции преобразования:

int PyUnicode_FSConverter(PyObject* obj, void* result)¶

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

Новое в версии 3.1.

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

int PyUnicode_FSDecoder(PyObject* obj, void* result)¶

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

Новое в версии 3.2.

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

Декодирует строку, используя Py_FileSystemDefaultEncoding и обработчик ошибок 'surrogateescape', или 'strict' в Windows.

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

Изменено в версии 3.2: Используется обработчик ошибок 'strict' в Windows.

PyObject* PyUnicode_DecodeFSDefault(const char *s)¶

Декодирует строку, завершающуюся нулевым символом, используя Py_FileSystemDefaultEncoding и обработчик ошибок 'surrogateescape', или 'strict' в Windows.

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

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

Изменено в версии 3.2: Используется обработчик ошибок 'strict' в Windows.

PyObject* PyUnicode_EncodeFSDefault(PyObject *unicode)¶

Кодирует объект Unicode в Py_FileSystemDefaultEncoding с обработчиком ошибок 'surrogateescape', или 'strict' в Windows, и возвращает bytes. Обратите внимание, что результирующий объект bytes может содержать нулевые байты.

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

Новое в версии 3.2.

Поддержка wchar_t¶wchar_t Support

Поддержка wchar_t на платформах, которые её поддерживают:

PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)¶: Возвращаемое значение: новая ссылка.
Создаёт объект Unicode из буфера wchar_t w заданного размера size. Передача -1 в качестве size означает, что функция должна сама вычислить длину, используя wcslen. В случае ошибки возвращает NULL.

Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size)¶: Копирует содержимое объекта Unicode в буфер 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)¶

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

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

Новое в версии 3.2.

Встроенные кодеки¶Built-in Codecs

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

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

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

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

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

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

Это общие API кодеков:

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

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

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

Кодеки UTF-8¶UTF-8 Codecs

Это API кодеков UTF-8:

PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)¶: Возвращаемое значение: новая ссылка.
Создаёт объект Unicode путём декодирования size байт строки, закодированной в UTF-8, s. Возвращает NULL, если кодек возбудил исключение.

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

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

PyObject* PyUnicode_AsUTF8String(PyObject *unicode)¶: Возвращаемое значение: новая ссылка.
Кодирует объект Unicode с использованием UTF-8 и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает NULL, если кодек возбудил исключение.

Кодеки UTF-32¶UTF-32 Codecs

Это API кодеков UTF-32:

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

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

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

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

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

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

В сборке с узким представлением кодовые точки за пределами BMP будут декодироваться как суррогатные пары.

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

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

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

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

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

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

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

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

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

PyObject* PyUnicode_AsUTF32String(PyObject *unicode)¶: Возвращает Python-строку байт в кодировке UTF-32 с собственным порядком байтов. Строка всегда начинается с маркера BOM. Обработка ошибок – «strict». Возвращает NULL, если кодек сгенерировал исключение.

Кодеки UTF-32¶UTF-16 Codecs

Это API кодеков UTF-32:

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

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

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

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

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

Если *byteorder равен нулю и первые два байта входных данных являются меткой порядка байтов (BOM), декодер переключается на этот порядок байтов, и BOM не копируется в результирующую строку Unicode. Если *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)¶: Возвращаемое значение: новая ссылка.
Если consumed равен NULL, ведёт себя как PyUnicode_DecodeUTF16(). Если consumed не равен NULL, PyUnicode_DecodeUTF16Stateful() не будет считать неполные конечные последовательности байтов UTF-16 (например, нечётное количество байтов или разбитая суррогатная пара) ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в consumed.

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

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

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

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

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

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

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

PyObject* PyUnicode_AsUTF16String(PyObject *unicode)¶: Возвращаемое значение: новая ссылка.
Возвращает Python-строку байт в кодировке UTF-16 с собственным порядком байтов. Строка всегда начинается с маркера BOM. Обработка ошибок – «strict». Возвращает NULL, если кодек сгенерировал исключение.

Кодеки UTF-7¶UTF-7 Codecs

Это API кодеков UTF-7:

PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)¶: Создаёт объект Unicode путём декодирования size байт строки в кодировке UTF-7 s. Возвращает NULL, если кодек сгенерировал исключение.

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

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

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

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

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

Это API кодеков «Unicode Escape»:

PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)¶: Возвращаемое значение: новая ссылка.
Создаёт объект Unicode путём декодирования size байт строки в кодировке Unicode-Escape s. Возвращает NULL, если кодек сгенерировал исключение.

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

PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)¶: Возвращаемое значение: новая ссылка.
Кодирует объект Unicode с использованием Unicode-Escape и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает NULL, если кодек вызвал исключение.

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

Это API кодеков «Raw Unicode Escape»:

PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)¶: Возвращаемое значение: новая ссылка.
Создаёт объект Unicode путём декодирования size байт строки s, закодированной в Raw-Unicode-Escape. Возвращает NULL, если кодек вызвал исключение.

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

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

Кодеки Latin-1¶Latin-1 Codecs

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

PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)¶: Возвращаемое значение: новая ссылка.
Создаёт объект Unicode путём декодирования size байт строки s, закодированной в Latin-1. Возвращает NULL, если кодек вызвал исключение.

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

PyObject* PyUnicode_AsLatin1String(PyObject *unicode)¶: Возвращаемое значение: новая ссылка.
Кодирует объект Unicode с помощью Latin-1 и возвращает результат как объект bytes Python. Обработка ошибок – “strict”. Возвращает NULL, если кодек вызвал исключение.

Кодеки ASCII¶ASCII Codecs

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

PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)¶: Возвращаемое значение: новая ссылка.
Создаёт объект Unicode путём декодирования size байт строки s, закодированной в ASCII. Возвращает NULL, если кодек вызвал исключение.

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

PyObject* PyUnicode_AsASCIIString(PyObject *unicode)¶: Возвращаемое значение: новая ссылка.
Кодирует объект Unicode с помощью ASCII и возвращает результат как объект bytes Python. Обработка ошибок – “strict”. Возвращает NULL, если кодек вызвал исключение.

Кодеки с таблицей символов¶Character Map Codecs

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

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

Отображения для кодирования должны сопоставлять отдельные символы Unicode отдельным строковым символам, целым числам (которые затем интерпретируются как кодовые точки Latin-1) или None (что означает «неопределённое отображение» и вызывает ошибку).

Объекты отображения должны поддерживать только интерфейс отображения __getitem__.

Если при поиске символа возникает LookupError, символ копируется как есть; это означает, что его порядковое значение будет интерпретироваться как кодовая точка Unicode или Latin-1 соответственно. Из-за этого отображения должны содержать только те соответствия, которые переводят символы в другие кодовые точки.

Это API кодеков отображения:

PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors)¶: Возвращаемое значение: новая ссылка.
Создаёт объект Unicode, декодируя size байт закодированной строки s с помощью заданного объекта mapping. Возвращает NULL, если кодек вызвал исключение. Если mapping равен NULL, выполняется декодирование Latin-1. В противном случае это может быть словарь, отображающий байты, или строка Unicode, которая интерпретируется как таблица поиска. Значения байтов, превышающие длину строки, и «символ» U+FFFE считаются «неопределённым отображением».

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

PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)¶: Возвращаемое значение: новая ссылка.
Кодирует объект Unicode с помощью заданного объекта mapping и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает NULL, если кодек вызвал исключение.

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

PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *table, const char *errors)¶

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

Переводит буфер Py_UNICODE заданного размера size, применяя к нему символьное отображение table, и возвращает результирующий объект Unicode. Возвращает NULL, если кодек вызвал исключение.

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

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

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

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

PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)¶: Возвращаемое значение: новая ссылка.
Создаёт объект Unicode, декодируя size байтов строки, закодированной в MBCS, из s. Возвращает NULL, если кодек вызвал исключение.

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

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

PyObject* PyUnicode_AsMBCSString(PyObject *unicode)¶: Возвращаемое значение: новая ссылка.
Кодирует объект Unicode с помощью MBCS и возвращает результат в виде объекта bytes Python. Обработка ошибок – "strict". Возвращает NULL, если кодек вызвал исключение.

Методы и слоты¶Methods & Slots

Методы и слот-функции¶Methods and Slot Functions

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

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

PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)¶: Возвращаемое значение: новая ссылка.
Объединяет две строки, возвращая новую строку Unicode.

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

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

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

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

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

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

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

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

int 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_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)¶: Возвращаемое значение: новая ссылка.
Заменяет не более maxcount вхождений substr в str на replstr и возвращает результирующий объект Unicode. maxcount == -1 означает замену всех вхождений.

int PyUnicode_Compare(PyObject *left, PyObject *right)¶: Сравнивает две строки и возвращает -1, 0, 1 для случаев «меньше», «равно» и «больше» соответственно.

int PyUnicode_CompareWithASCIIString(PyObject *uni, char *string)¶: Сравнивает объект Unicode uni со строкой string и возвращает -1, 0, 1 для случаев меньше, равно и больше соответственно. Рекомендуется передавать только строки в кодировке ASCII, но если строка содержит не-ASCII символы, функция интерпретирует её как ISO-8859-1.

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

Выполняет расширенное сравнение двух строк unicode и возвращает одно из следующих значений:

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

Обратите внимание, что сравнения с Py_EQ и Py_NE могут вызвать UnicodeWarning, если преобразование аргументов в Unicode завершится ошибкой с UnicodeDecodeError.

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

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

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

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

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

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

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