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

Тип Unicode¶Unicode Type

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

Py_UNICODE¶

Этот тип представляет собой тип хранения, который используется внутри Python для хранения кодовых точек Unicode. В сборках Python по умолчанию для Py_UNICODE используется 16-битный тип, и значения Unicode хранятся внутри как UCS2. Также можно собрать версию Python UCS4 (большинство современных дистрибутивов Linux поставляются со сборками Python UCS4). В этих сборках для Py_UNICODE используется 32-битный тип, и данные 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 как 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 (не проверяется).

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

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 символом в регистре заголовка (titlecase).

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-битных систем.

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

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

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

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

PyObject *PyUnicode_FromString(const char *u)¶

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

Создаёт объект Unicode из UTF-8-закодированного нуль-терминированного буфера символов u.

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

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

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

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

Символы формата	Тип	Описание
%%	н/д	Буквальный символ %.
%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 на данной платформе.
%U	PyObject*	Unicode-объект.
%V	PyObject*, char *	Unicode-объект (может быть NULL) и завершающийся нулевым символом C-массив символов в качестве второго параметра (используется, если первый параметр равен NULL).
%S	PyObject*	Результат вызова PyObject_Unicode().
%R	PyObject*	Результат вызова PyObject_Repr().

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

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

PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)¶

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

Идентично PyUnicode_FromFormat(), за исключением того, что принимает ровно два аргумента.

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

Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)¶

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

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

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

Сокращение для PyUnicode_FromEncodedObject(obj, NULL, "strict"), которое используется во всём интерпретаторе, когда требуется приведение к Unicode.

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

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

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

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

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

Создаёт объект Unicode из буфера wchar_t w заданного размера. Возвращает NULL в случае ошибки.

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

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.

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

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

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

PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)¶

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

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

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

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

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

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.

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

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

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

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

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

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

Декодирует 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 устанавливается в текущий порядок байтов в конце входных данных.

В сборке с узкими символами (narrow build) кодовые точки за пределами 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)¶

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

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

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

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

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

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

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

PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

PyObject* PyUnicode_AsASCIIString(PyObject *unicode)¶

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

Кодирует объект Unicode с помощью ASCII и возвращает результат в виде строкового объекта 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 считаются «неопределённым отображением».

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

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

PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)¶

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

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

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

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) остаются нетронутыми и копируются как есть.

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

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

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

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

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

PyObject* PyUnicode_AsMBCSString(PyObject *unicode)¶

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

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

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