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

Объекты 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 представляет тип Python Unicode. Он доступен из кода Python как unicode и types.UnicodeType.

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

int PyUnicode_Check(PyObject *o)¶

Возвращает true, если объект o является объектом Unicode или экземпляром подтипа Unicode.

Изменено в версии 2.2: Теперь допускаются подтипы.

int PyUnicode_CheckExact(PyObject *o)¶

Возвращает true, если объект o является объектом Unicode, но не экземпляром подтипа.

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

Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)¶

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

Изменено в версии 2.5:Эта функция возвращала тип int. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

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()¶

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

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

Свойства символов 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 буквенно-цифровым символом.

Эти 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.

Изменено в версии 2.5: Раньше эта функция использовала тип int для size. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

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

Py_ssize_t PyUnicode_GetSize(PyObject *unicode)¶

Возвращает длину объекта Unicode.

Изменено в версии 2.5: эта функция возвращала тип int. Возможно, потребуется изменить код для корректной поддержки 64-битных систем.

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.

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

wchar_t support for platforms which support it:

PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)¶

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

Создаёт объект Unicode из буфера wchar_t w заданного размера. Возвращает 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 заканчивается нулевым символом, если это требуется приложению.

Изменено в версии 2.5: эта функция возвращала тип int и использовала тип int для size. Возможно, потребуется изменить код для корректной поддержки 64-битных систем.

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

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

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

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

Кодеки 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.

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

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, если кодек возбудил исключение.

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

Это 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

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

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

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

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

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

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

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.

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

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, если кодек сгенерировал исключение.

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

PyObject* PyUnicode_AsUTF32String(PyObject *unicode)¶

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

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

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

Это 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

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

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

Изменено в версии 2.5: эта функция использовала тип int для size и тип int * для consumed. Возможно, потребуется изменить код для корректной поддержки 64-битных систем.

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

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

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

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, если кодек вызвал исключение.

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

PyObject* PyUnicode_AsLatin1String(PyObject *unicode)¶: Возвращаемое значение: новая ссылка.
Кодирует объект Unicode с помощью Latin-1 и возвращает результат в виде строкового объекта 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 заданного размера с помощью ASCII и возвращает строковый объект Python. Возвращает NULL, если кодек вызвал исключение.

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

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

Это 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 считаются «неопределённым отображением».

Изменено в версии 2.4: Разрешена строка Unicode в качестве аргумента отображения.

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) – это класс кодировок, а не одна конкретная. Целевая кодировка определяется пользовательскими настройками на машине, где выполняется кодек.

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

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.

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

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 & 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 разделений. Если отрицательное, ограничение не устанавливается. Разделители не включаются в результирующий список.

Изменено в версии 2.5: Эта функция использовала тип int для maxsplit. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

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, если произошла ошибка.

Изменено в версии 2.5: Эта функция использовала тип int для start и end. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

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, если произошла ошибка.

Изменено в версии 2.5: Эта функция возвращала тип int и использовала тип int для start и end. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)¶

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

Заменяет не более maxcount вхождений substr в str на replstr и возвращает результирующий объект Unicode. maxcount == -1 означает замену всех вхождений.

Изменено в версии 2.5: Эта функция использовала тип int для maxcount. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

int PyUnicode_Compare(PyObject *left, PyObject *right)¶: Сравнивает две строки и возвращает -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.