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

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

Объекты Unicode¶Unicode Objects

Это основные типы объектов 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(void)¶: Очищает список свободных элементов. Возвращает общее количество освобождённых элементов.

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

Для создания объектов 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)¶: Create a Unicode Object from the char buffer u. The bytes will be interpreted as being UTF-8 encoded. u may also be NULL which causes the contents to be undefined. It is the user’s responsibility to fill in the needed data. The buffer is copied into the new object. If the buffer is not NULL, the return value might be a shared object. Therefore, modification of the resulting Unicode object is only allowed when u is NULL.

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

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

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

Символы формата	Тип	Описание
`%%`	н/д	Буквальный символ %.
`%c`	int	Одиночный символ, представленный как C int.
`%d`	int	Полностью эквивалентно `printf("%d")`.
`%u`	беззнаковый int	Полностью эквивалентно `printf("%u")`.
`%ld`	long	Полностью эквивалентно `printf("%ld")`.
`%lu`	беззнаковый long	Полностью эквивалентно `printf("%lu")`.
`%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_Unicode()`.
`%R`	PyObject*	Результат вызова `PyObject_Repr()`.

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

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

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

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

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

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

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

Строки и другие объекты, совместимые с символьными буферами, декодируются в соответствии с заданной кодировкой и с использованием обработки ошибок, определённой параметром 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.

PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)¶: Возвращаемое значение: новая ссылка.
Создаёт объект Unicode из буфера wchar_t w указанного размера. Если передать -1 в качестве размера, функция должна сама вычислить длину с помощью 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 заканчивается нулевым символом, если это требуется приложению.

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

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

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

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

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

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

Это общие 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 указанного размера и возвращает объект строки Python. Параметры encoding и errors имеют тот же смысл, что и одноимённые параметры метода Unicode encode(). Используемый кодек ищется в реестре кодеков Python. Возвращает NULL, если кодек возбудил исключение.

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

Это 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 указанного размера с использованием UTF-8 и возвращает объект строки Python. Возвращает NULL, если кодек возбудил исключение.

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

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

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

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

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

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

а затем переключается, если первые четыре байта входных данных являются маркером порядка байт (BOM) и заданный порядок байт является порядком хост-системы. Этот BOM не копируется в результирующую строку Unicode. После завершения в *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 не равен 0, вывод записывается в соответствии со следующим порядком байтов:

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 с native порядком байтов. Строка всегда начинается с маркера BOM. Обработка ошибок – «strict». Возвращает NULL, если кодек вызвал исключение.

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

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

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

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

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

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

и затем переключается, если первые два байта входных данных являются маркером порядка байтов (BOM), а указанный порядок байтов является native. Этот BOM не копируется в результирующую строку Unicode. После завершения *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, содержащий значение Unicode-данных из s, закодированное в UTF-16. Если byteorder не равен 0, вывод записывается в соответствии со следующим порядком байтов:

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 с native порядком байтов. Строка всегда начинается с маркера BOM. Обработка ошибок – «strict». Возвращает NULL, если кодек вызвал исключение.

Это 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 заданного размера с использованием Unicode-Escape и возвращает объект строки Python. Возвращает NULL, если кодек вызвал исключение.

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

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

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

Это 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 заданного размера с помощью Latin-1 и возвращает строковый объект Python. Возвращает NULL, если кодек вызвал исключение.

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

Это 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 заданного размера с помощью ASCII и возвращает строковый объект Python. Возвращает NULL, если кодек вызвал исключение.

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

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

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

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

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

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

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

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 заданного размера, используя заданный 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 заданной длины, применяя к нему таблицу символов table, и возвращает полученный объект Unicode. Возвращает NULL, когда кодек вызвал исключение.

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

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

Это 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 заданного размера, используя MBCS, и возвращает объект строки Python. Возвращает NULL, если кодек вызвал исключение.

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

Методы и слот-функции¶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 для меньше чем, равно и больше соответственно.

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