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

Тип Юникода¶

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

type Py_UCS4¶

type Py_UCS2¶

type Py_UCS1¶

Part of the Stable ABI.

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

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

type Py_UNICODE¶

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

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

type PyASCIIObject¶

type PyCompactUnicodeObject¶

type PyUnicodeObject¶

Эти подтипы PyObject представляют объект Python Unicode. Почти во всех случаях их не следует использовать напрямую, поскольку все функции API, работающие с объектами Unicode, принимают и возвращают указатели PyObject.

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

PyTypeObject PyUnicode_Type¶

Part of the Stable ABI.

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

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

int PyUnicode_Check(PyObject *o)¶

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

int PyUnicode_CheckExact(PyObject *o)¶

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

int PyUnicode_READY(PyObject *o)¶

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

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

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

Deprecated since version 3.10, will be removed in version 3.12: Этот API будет удален с помощью PyUnicode_FromUnicode().

Py_ssize_t PyUnicode_GET_LENGTH(PyObject *o)¶

Возвращает длину строки Unicode в кодовых точках. o должен быть объектом Unicode в «каноническом» представлении (не проверяется).

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

Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *o)¶

Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *o)¶

Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *o)¶

Возвращает указатель на каноническое представление, приведенное к целочисленным типам UCS1, UCS2 или UCS4 для прямого доступа к символам. Не проверяется, имеет ли каноническое представление правильный размер символа; используйте PyUnicode_KIND() для выбора правильного макроса. Убедитесь, что PyUnicode_READY() был вызван перед обращением к этому макросу.

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

PyUnicode_WCHAR_KIND¶

PyUnicode_1BYTE_KIND¶

PyUnicode_2BYTE_KIND¶

PyUnicode_4BYTE_KIND¶

Возвращаемые значения макроса PyUnicode_KIND().

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

Deprecated since version 3.10, will be removed in version 3.12: PyUnicode_WCHAR_KIND устарел.

unsigned int PyUnicode_KIND(PyObject *o)¶

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

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

void *PyUnicode_DATA(PyObject *o)¶

Возвращает указатель void на необработанный буфер Unicode. o должен быть объектом Unicode в «каноническом» представлении (не проверяется).

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

void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)¶

Запись в каноническое представление data (как получено с помощью PyUnicode_DATA()). Этот макрос не делает никаких проверок на вменяемость и предназначен для использования в циклах. Вызывающая сторона должна кэшировать значение kind и указатель data, полученные при других вызовах макроса. index - это индекс в строке (начинается с 0), а value - новое значение кодовой точки, которое должно быть записано в это место.

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

Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)¶

Считывание кодовой точки из канонического представления data (полученного с помощью PyUnicode_DATA()). Никаких проверок или вызовов готовности не выполняется.

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

Py_UCS4 PyUnicode_READ_CHAR(PyObject *o, Py_ssize_t index)¶

Считывание символа из объекта Unicode o, который должен быть в «каноническом» представлении. Это менее эффективно, чем PyUnicode_READ(), если вы выполняете несколько последовательных считываний.

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

PyUnicode_MAX_CHAR_VALUE(o)¶

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

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

Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)¶

Возвращает размер устаревшего представления Py_UNICODE, в единицах кода (включает суррогатные пары как 2 единицы). o должен быть объектом Unicode (не проверяется).

Deprecated since version 3.3, will be removed in version 3.12: Часть Unicode API старого образца, пожалуйста, перейдите на использование PyUnicode_GET_LENGTH().

Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)¶

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

Deprecated since version 3.3, will be removed in version 3.12: Часть Unicode API старого образца, пожалуйста, перейдите на использование PyUnicode_GET_LENGTH().

Py_UNICODE *PyUnicode_AS_UNICODE(PyObject *o)¶

const char *PyUnicode_AS_DATA(PyObject *o)¶

Возвращает указатель на Py_UNICODE представление объекта. Возвращаемый буфер всегда завершается дополнительной нулевой точкой кода. Он также может содержать встроенные нулевые точки кода, что приведет к усечению строки при использовании в большинстве функций языка Си. Форма AS_DATA приводит указатель к const char*. Аргумент o должен быть объектом Unicode (не проверяется).

Изменено в версии 3.3: Теперь этот макрос неэффективен - поскольку во многих случаях представление Py_UNICODE не существует и должно быть создано - и может не сработать (вернуть NULL с набором исключений). Попробуйте перенести код на использование новых макросов PyUnicode_nBYTE_DATA() или используйте PyUnicode_WRITE() или PyUnicode_READ().

Deprecated since version 3.3, will be removed in version 3.12: Часть Unicode API старого образца, пожалуйста, перейдите на использование семейства макросов PyUnicode_nBYTE_DATA().

int PyUnicode_IsIdentifier(PyObject *o)¶

Part of the Stable ABI.

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

Изменено в версии 3.9: Функция больше не вызывает Py_FatalError(), если строка не готова.

Свойства символов Юникода¶

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

int Py_UNICODE_ISSPACE(Py_UCS4 ch)¶

Возвращает 1 или 0 в зависимости от того, является ли ch символом пробела.

int Py_UNICODE_ISLOWER(Py_UCS4 ch)¶

Возвращает 1 или 0 в зависимости от того, является ли ch строчным символом.

int Py_UNICODE_ISUPPER(Py_UCS4 ch)¶

Возвращает 1 или 0 в зависимости от того, является ли ch прописным символом.

int Py_UNICODE_ISTITLE(Py_UCS4 ch)¶

Возвращает 1 или 0 в зависимости от того, является ли ch символом заглавной буквы.

int Py_UNICODE_ISLINEBREAK(Py_UCS4 ch)¶

Возвращает 1 или 0 в зависимости от того, является ли ch символом перевода строки.

int Py_UNICODE_ISDECIMAL(Py_UCS4 ch)¶

Возвращает 1 или 0 в зависимости от того, является ли ch десятичным символом.

int Py_UNICODE_ISDIGIT(Py_UCS4 ch)¶

Возвращает 1 или 0 в зависимости от того, является ли ch цифровым символом.

int Py_UNICODE_ISNUMERIC(Py_UCS4 ch)¶

Возвращает 1 или 0 в зависимости от того, является ли ch числовым символом.

int Py_UNICODE_ISALPHA(Py_UCS4 ch)¶

Возвращает 1 или 0 в зависимости от того, является ли ch буквенным символом.

int Py_UNICODE_ISALNUM(Py_UCS4 ch)¶

Возвращает 1 или 0 в зависимости от того, является ли ch буквенно-цифровым символом.

int Py_UNICODE_ISPRINTABLE(Py_UCS4 ch)¶

Возвращает 1 или 0 в зависимости от того, является ли ch непечатаемым символом. Непечатаемые символы - это символы, определенные в базе данных символов Unicode как «Другой» или «Разделитель», за исключением пробела ASCII (0x20), который считается печатаемым. (Обратите внимание, что непечатаемые символы в данном контексте - это те, которые не должны экранироваться при вызове repr() в строке. Это никак не влияет на обработку строк, записанных в sys.stdout или sys.stderr).

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

Py_UCS4 Py_UNICODE_TOLOWER(Py_UCS4 ch)¶

Возвращает символ ch, преобразованный в нижний регистр.

Не рекомендуется, начиная с версии 3.3: Эта функция использует простые сопоставления регистров.

Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4 ch)¶

Возвращает символ ch, преобразованный в верхний регистр.

Не рекомендуется, начиная с версии 3.3: Эта функция использует простые сопоставления регистров.

Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4 ch)¶

Возвращает символ ch, преобразованный в заглавный регистр.

Не рекомендуется, начиная с версии 3.3: Эта функция использует простые сопоставления регистров.

int Py_UNICODE_TODECIMAL(Py_UCS4 ch)¶

Возвращает символ ch, преобразованный в десятичное положительное целое число. Верните -1, если это невозможно. Этот макрос не вызывает исключений.

int Py_UNICODE_TODIGIT(Py_UCS4 ch)¶

Возвращает символ ch, преобразованный в одноразрядное целое число. Верните -1, если это невозможно. Этот макрос не вызывает исключений.

double Py_UNICODE_TONUMERIC(Py_UCS4 ch)¶

Возвращает символ ch, преобразованный в двойное число. Верните -1.0, если это невозможно. Этот макрос не вызывает исключений.

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

Py_UNICODE_IS_SURROGATE(ch)¶

Проверьте, является ли ch суррогатом (0xD800 <= ch <= 0xDFFF).

Py_UNICODE_IS_HIGH_SURROGATE(ch)¶

Проверьте, является ли ch высоким суррогатом (0xD800 <= ch <= 0xDBFF).

Py_UNICODE_IS_LOW_SURROGATE(ch)¶

Проверьте, является ли ch низким суррогатом (0xDC00 <= ch <= 0xDFFF).

Py_UNICODE_JOIN_SURROGATES(high, low)¶

Объединяет два суррогатных символа и возвращает одно значение Py_UCS4. high и low - это соответственно ведущий и последующий суррогаты в паре суррогатов.

Создание и доступ к строкам Unicode¶

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

PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)¶

Return value: New reference.

Создайте новый объект Unicode. maxchar должно быть истинным максимальным значением кодовой точки, которая будет помещена в строку. В качестве приближения его можно округлить до ближайшего значения в последовательности 127, 255, 65535, 1114111.

Это рекомендуемый способ выделения нового объекта Unicode. Объекты, созданные с помощью этой функции, не изменяют размер.

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

PyObject *PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)¶

Return value: New reference.

Создает новый объект Unicode с заданным kind (возможные значения PyUnicode_1BYTE_KIND и т.д., как возвращается PyUnicode_KIND()). Буфер* должен указывать на массив единиц size размером 1, 2 или 4 байта на символ, в зависимости от вида.

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

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

Return value: New reference. Part of the Stable ABI.

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

Если u равно NULL, эта функция ведет себя как PyUnicode_FromUnicode() с буфером, установленным в NULL. Это использование устарело в пользу PyUnicode_New(), и будет удалено в Python 3.12.

PyObject *PyUnicode_FromString(const char *u)¶

Return value: New reference. Part of the Stable ABI.

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

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

Return value: New reference. Part of the Stable ABI.

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

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

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

Примечание

Единицей измерения ширины форматера является количество символов, а не байтов. Единицей измерения точности является количество байт для "%s" и "%V" (если аргумент PyObject* равен NULL), и количество символов для "%A", "%U", "%S", "%R" и "%V" (если аргумент PyObject* не равен NULL).

1(1,2,3,4,5,6,7,8,9,10,11,12,13)

Для целочисленных спецификаторов (d, u, ld, li, lu, lld, lli, llu, zd, zi, zu, i, x): флаг 0-преобразования действует, даже если задана точность.

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

Изменено в версии 3.3: Добавлена поддержка "%li", "%lli" и "%zi".

Изменено в версии 3.4: Добавлена поддержка ширины и точности форматера для "%s", "%A", "%U", "%V", "%S", "%R".

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

Return value: New reference. Part of the Stable ABI.

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

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

Return value: New reference. Part of the Stable ABI.

Декодировать закодированный объект obj в объект Unicode.

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

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

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

Py_ssize_t PyUnicode_GetLength(PyObject *unicode)¶

Part of the Stable ABI since version 3.7.

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

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

Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t from_start, Py_ssize_t how_many)¶

Копирование символов из одного объекта Unicode в другой. Эта функция выполняет преобразование символов, когда это необходимо, и возвращается к memcpy(), если это возможно. Возвращает -1 и устанавливает исключение при ошибке, в противном случае возвращает количество скопированных символов.

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

Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)¶

Заполните строку символом: запишите fill_char в unicode[start:start+length].

Неудача, если fill_char больше, чем максимальный символ строки, или если строка имеет более 1 ссылки.

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

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

int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)¶

Part of the Stable ABI since version 3.7.

Запись символа в строку. Строка должна быть создана с помощью PyUnicode_New(). Поскольку строки Unicode должны быть неизменяемыми, строка не должна быть общей или хэшированной.

Эта функция проверяет, что unicode является объектом Unicode, что индекс не выходит за границы, и что объект может быть безопасно изменен (т.е. что количество его ссылок равно единице).

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

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)¶

Part of the Stable ABI since version 3.7.

Считывание символа из строки. Эта функция проверяет, что unicode является объектом Unicode и индекс не выходит за границы, в отличие от версии макроса PyUnicode_READ_CHAR().

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

PyObject *PyUnicode_Substring(PyObject *str, Py_ssize_t start, Py_ssize_t end)¶

Return value: New reference. Part of the Stable ABI since version 3.7.

Возвращает подстроку str, начиная с символьного индекса start (включено) до символьного индекса end (исключено). Отрицательные индексы не поддерживаются.

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

Py_UCS4 *PyUnicode_AsUCS4(PyObject *u, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)¶

Part of the Stable ABI since version 3.7.

Копирует строку u в буфер UCS4, включая нулевой символ, если установлено значение copy_null. Возвращает NULL и устанавливает исключение при ошибке (в частности, SystemError, если buflen меньше длины u). При успехе возвращается buffer.

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

Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *u)¶

Part of the Stable ABI since version 3.7.

Скопировать строку u в новый буфер UCS4, выделенный с помощью PyMem_Malloc(). Если это не удается, возвращается NULL с установленным MemoryError. В возвращаемый буфер всегда добавляется дополнительная нулевая кодовая точка.

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

Утратившие силу API Py_UNICODE¶

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

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

Return value: New reference.

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

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

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

Deprecated since version 3.3, will be removed in version 3.12: Часть Unicode API старого образца, пожалуйста, перейдите на использование PyUnicode_FromKindAndData(), PyUnicode_FromWideChar() или PyUnicode_New().

Py_UNICODE *PyUnicode_AsUnicode(PyObject *unicode)¶

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

Deprecated since version 3.3, will be removed in version 3.12: Часть Unicode API старого образца, пожалуйста, перейдите на использование PyUnicode_AsUCS4(), PyUnicode_AsWideChar(), PyUnicode_ReadChar() или аналогичных новых API.

PyObject *PyUnicode_TransformDecimalToASCII(Py_UNICODE *s, Py_ssize_t size)¶

Return value: New reference.

Создать объект Unicode путем замены всех десятичных цифр в буфере Py_UNICODE заданного размера на ASCII цифры 0–9 в соответствии с их десятичным значением. Верните NULL, если произойдет исключение.

Deprecated since version 3.3, will be removed in version 3.11: Часть API старого образца Py_UNICODE; пожалуйста, перейдите на использование Py_UNICODE_TODECIMAL().

Py_UNICODE *PyUnicode_AsUnicodeAndSize(PyObject *unicode, Py_ssize_t *size)¶

Подобно PyUnicode_AsUnicode(), но сохраняет длину массива Py_UNICODE() (исключая дополнительный нулевой терминатор) в size. Обратите внимание, что результирующая строка Py_UNICODE* может содержать встроенные нулевые точки кода, что приведет к усечению строки при использовании в большинстве функций языка Си.

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

Deprecated since version 3.3, will be removed in version 3.12: Часть Unicode API старого образца, пожалуйста, перейдите на использование PyUnicode_AsUCS4(), PyUnicode_AsWideChar(), PyUnicode_ReadChar() или аналогичных новых API.

Py_ssize_t PyUnicode_GetSize(PyObject *unicode)¶

Part of the Stable ABI.

Возвращает размер устаревшего представления Py_UNICODE, в единицах кода (включает суррогатные пары как 2 единицы).

Deprecated since version 3.3, will be removed in version 3.12: Часть Unicode API старого образца, пожалуйста, перейдите на использование PyUnicode_GET_LENGTH().

PyObject *PyUnicode_FromObject(PyObject *obj)¶

Return value: New reference. Part of the Stable ABI.

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

Объекты, отличные от Unicode или его подтипов, вызовут ошибку TypeError.

Кодирование локали¶

Текущая кодировка локали может быть использована для декодирования текста из операционной системы.

PyObject *PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t len, const char *errors)¶

Return value: New reference. Part of the Stable ABI since version 3.7.

Декодирование строки из UTF-8 на Android и VxWorks или из текущей кодировки локали на других платформах. Поддерживаемые обработчики ошибок - "strict" и "surrogateescape" (PEP 383). Декодер использует обработчик ошибок "strict", если errors имеет значение NULL. str должен заканчиваться нулевым символом, но не может содержать встроенных нулевых символов.

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

Эта функция игнорирует Python UTF-8 Mode.

См.также

Функция Py_DecodeLocale().

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

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

PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors)¶

Return value: New reference. Part of the Stable ABI since version 3.7.

Аналогично PyUnicode_DecodeLocaleAndSize(), но длина строки вычисляется с помощью strlen().

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

PyObject *PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)¶

Return value: New reference. Part of the Stable ABI since version 3.7.

Кодирование объекта Unicode в UTF-8 на Android и VxWorks или в текущую кодировку локали на других платформах. Поддерживаемые обработчики ошибок - "strict" и "surrogateescape" (PEP 383). Кодер использует обработчик ошибок "strict", если errors равно NULL. Возвращает объект bytes. unicode не может содержать встроенные нулевые символы.

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

Эта функция игнорирует Python UTF-8 Mode.

См.также

Функция Py_EncodeLocale().

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

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

Кодирование файловой системы¶

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

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

Part of the Stable ABI.

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

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

Изменено в версии 3.6: Принимает path-like object.

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

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

Part of the Stable ABI.

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

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

Изменено в версии 3.6: Принимает path-like object.

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

Return value: New reference. Part of the Stable ABI.

Декодирование строки из filesystem encoding and error handler.

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

Py_FileSystemDefaultEncoding инициализируется при запуске из кодировки локали и не может быть изменена позже. Если вам нужно декодировать строку из текущей кодировки локали, используйте PyUnicode_DecodeLocaleAndSize().

См.также

Функция Py_DecodeLocale().

Изменено в версии 3.6: Используйте обработчик ошибок Py_FileSystemDefaultEncodeErrors.

PyObject *PyUnicode_DecodeFSDefault(const char *s)¶

Return value: New reference. Part of the Stable ABI.

Декодирование нуль-терминированной строки из filesystem encoding and error handler.

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

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

Изменено в версии 3.6: Используйте обработчик ошибок Py_FileSystemDefaultEncodeErrors.

PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)¶

Return value: New reference. Part of the Stable ABI.

Перекодируйте объект Unicode в Py_FileSystemDefaultEncoding с помощью обработчика ошибок Py_FileSystemDefaultEncodeErrors и верните bytes. Обратите внимание, что полученный объект bytes может содержать нулевые байты.

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

Py_FileSystemDefaultEncoding инициализируется при запуске из кодировки локали и не может быть изменена позже. Если вам нужно закодировать строку в текущей кодировке локали, используйте PyUnicode_EncodeLocale().

См.также

Функция Py_EncodeLocale().

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

Изменено в версии 3.6: Используйте обработчик ошибок Py_FileSystemDefaultEncodeErrors.

wchar_t Поддержка¶

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

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

Return value: New reference. Part of the Stable ABI.

Создать объект Unicode из wchar_t буфера w заданного размера. Передача -1 в качестве size означает, что функция должна сама вычислить длину, используя wcslen. При неудаче возвращается NULL.

Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *w, Py_ssize_t size)¶

Part of the Stable ABI.

Скопировать содержимое объекта Unicode в буфер w wchar_t. Копируется не более size wchar_t символов (исключая возможно идущий следом нулевой символ завершения). Возвращается количество скопированных wchar_t символов или -1 в случае ошибки. Обратите внимание, что результирующая строка wchar_t* может быть нуль-терминированной или нет. Ответственность за то, чтобы строка wchar_t* была нуль-терминированной, лежит на вызывающей стороне, если этого требует приложение. Также обратите внимание, что строка wchar_t* может содержать нулевые символы, что приведет к усечению строки при использовании с большинством функций языка Си.

wchar_t *PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)¶

Part of the Stable ABI since version 3.7.

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

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

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

Изменено в версии 3.7: Вызывает ошибку ValueError, если size равен NULL и строка wchar_t* содержит нулевые символы.

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

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

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

Return value: New reference. Part of the Stable ABI.

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

PyObject *PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)¶

Return value: New reference. Part of the Stable ABI.

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

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

Return value: New reference.

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

Deprecated since version 3.3, will be removed in version 3.11: Часть API старого образца Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsEncodedString().

Кодеки UTF-8¶

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

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

Return value: New reference. Part of the Stable ABI.

Создать объект Unicode путем декодирования size байт строки s, закодированной в UTF-8. Верните NULL, если кодек вызвал исключение.

PyObject *PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶

Return value: New reference. Part of the Stable ABI.

Если consumed равно NULL, ведет себя как PyUnicode_DecodeUTF8(). Если consumed не NULL, то неполные последовательности байтов UTF-8 не будут рассматриваться как ошибка. Эти байты не будут декодированы, а количество байтов, которые были декодированы, будет сохранено в consumed.

PyObject *PyUnicode_AsUTF8String(PyObject *unicode)¶

Return value: New reference. Part of the Stable ABI.

Кодирует объект Unicode с помощью UTF-8 и возвращает результат в виде объекта Python bytes. Обработка ошибок «строгая». Верните NULL, если кодек вызвал исключение.

const char *PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)¶

Part of the Stable ABI since version 3.10.

Возвращает указатель на кодировку UTF-8 объекта Unicode и сохраняет размер кодированного представления (в байтах) в size. Аргумент size может быть NULL; в этом случае размер не сохраняется. В возвращаемый буфер всегда добавляется дополнительный нулевой байт (не включенный в size), независимо от наличия других нулевых кодовых точек.

В случае ошибки возвращается NULL с установленным исключением и не сохраняется размер.

Это кэширует UTF-8 представление строки в объекте Unicode, и последующие вызовы будут возвращать указатель на тот же буфер. Вызывающая сторона не несет ответственности за деаллокацию буфера. Буфер деаллоцируется, а указатели на него становятся недействительными при сборке мусора объекта Unicode.

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

Изменено в версии 3.7: Тип возврата теперь const char *, а не char *.

Изменено в версии 3.10: Эта функция является частью limited API.

const char *PyUnicode_AsUTF8(PyObject *unicode)¶

Как PyUnicode_AsUTF8AndSize(), но не сохраняет размер.

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

Изменено в версии 3.7: Тип возврата теперь const char *, а не char *.

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

Return value: New reference.

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

Deprecated since version 3.3, will be removed in version 3.11: Часть API старого образца Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsUTF8String(), PyUnicode_AsUTF8AndSize() или PyUnicode_AsEncodedString().

Кодеки UTF-32¶

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

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

Return value: New reference. Part of the Stable ABI.

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

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

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

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

Return value: New reference. Part of the Stable ABI.

Если consumed равно NULL, ведет себя как PyUnicode_DecodeUTF32(). Если consumed не NULL, то PyUnicode_DecodeUTF32Stateful() не будет рассматривать неполные последовательности байтов UTF-32 (например, число байтов, не кратное четырем) как ошибку. Эти байты не будут декодированы, а количество байт, которые были декодированы, будет сохранено в consumed.

PyObject *PyUnicode_AsUTF32String(PyObject *unicode)¶

Return value: New reference. Part of the Stable ABI.

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

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

Return value: New reference.

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

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

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

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

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

Deprecated since version 3.3, will be removed in version 3.11: Часть API старого образца Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsUTF32String() или PyUnicode_AsEncodedString().

Кодеки UTF-16¶

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

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

Return value: New reference. Part of the Stable ABI.

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

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

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

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

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

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

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

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

Return value: New reference. Part of the Stable ABI.

Если consumed равно NULL, ведет себя как PyUnicode_DecodeUTF16(). Если consumed не NULL, то PyUnicode_DecodeUTF16Stateful() не будет рассматривать неполные последовательности байтов UTF-16 (такие как нечетное количество байтов или разделенная суррогатная пара) как ошибку. Эти байты не будут декодированы, а количество байтов, которые были декодированы, будет сохранено в consumed.

PyObject *PyUnicode_AsUTF16String(PyObject *unicode)¶

Return value: New reference. Part of the Stable ABI.

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

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

Return value: New reference.

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

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

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

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

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

Deprecated since version 3.3, will be removed in version 3.11: Часть API старого образца Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsUTF16String() или PyUnicode_AsEncodedString().

Кодеки UTF-7¶

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

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

Return value: New reference. Part of the Stable ABI.

Создать объект Unicode путем декодирования size байт строки s, закодированной в UTF-7. Верните NULL, если кодек вызвал исключение.

PyObject *PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶

Return value: New reference. Part of the Stable ABI.

Если consumed равно NULL, ведет себя как PyUnicode_DecodeUTF7(). Если consumed не NULL, то неполные трейлинговые секции UTF-7 base-64 не будут рассматриваться как ошибка. Эти байты не будут декодированы, а количество байтов, которые были декодированы, будет сохранено в consumed.

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

Return value: New reference.

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

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

Deprecated since version 3.3, will be removed in version 3.11: Часть API старого образца Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsEncodedString().

Кодеки Unicode-Escape¶

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

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

Return value: New reference. Part of the Stable ABI.

Создать объект Unicode путем декодирования size байт кодированной Unicode-Escape строки s. Вернуть NULL, если кодек вызвал исключение.

PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)¶

Return value: New reference. Part of the Stable ABI.

Закодируйте объект Unicode с помощью Unicode-Escape и верните результат в виде объекта bytes. Обработка ошибок «строгая». Верните NULL, если кодек вызвал исключение.

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

Return value: New reference.

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

Deprecated since version 3.3, will be removed in version 3.11: Часть API старого образца Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsUnicodeEscapeString().

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

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

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

Return value: New reference. Part of the Stable ABI.

Создать объект Unicode путем декодирования size байт закодированной Raw-Unicode-Escape строки s. Возвращает NULL, если кодек вызвал исключение.

PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)¶

Return value: New reference. Part of the Stable ABI.

Закодируйте объект Unicode с помощью Raw-Unicode-Escape и верните результат в виде объекта bytes. Обработка ошибок «строгая». Верните NULL, если кодек вызвал исключение.

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

Return value: New reference.

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

Deprecated since version 3.3, will be removed in version 3.11: Часть API старого образца Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsRawUnicodeEscapeString() или PyUnicode_AsEncodedString().

Кодеки Latin-1¶

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

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

Return value: New reference. Part of the Stable ABI.

Создать объект Unicode путем декодирования size байт строки s в кодировке Latin-1. Верните NULL, если кодек вызвал исключение.

PyObject *PyUnicode_AsLatin1String(PyObject *unicode)¶

Return value: New reference. Part of the Stable ABI.

Закодируйте объект Unicode с помощью Latin-1 и верните результат в виде объекта Python bytes. Обработка ошибок «строгая». Верните NULL, если кодек вызвал исключение.

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

Return value: New reference.

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

Deprecated since version 3.3, will be removed in version 3.11: Часть API старого образца Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsLatin1String() или PyUnicode_AsEncodedString().

Кодеки ASCII¶

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

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

Return value: New reference. Part of the Stable ABI.

Создать объект Unicode путем декодирования size байт ASCII-кодированной строки s. Верните NULL, если кодек вызвал исключение.

PyObject *PyUnicode_AsASCIIString(PyObject *unicode)¶

Return value: New reference. Part of the Stable ABI.

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

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

Return value: New reference.

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

Deprecated since version 3.3, will be removed in version 3.11: Часть API старого образца Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsASCIIString() или PyUnicode_AsEncodedString().

Кодеки карты символов¶

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

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

PyObject *PyUnicode_DecodeCharmap(const char *data, Py_ssize_t size, PyObject *mapping, const char *errors)¶

Return value: New reference. Part of the Stable ABI.

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

Если mapping равно NULL, будет применено декодирование Latin-1. В противном случае mapping должен отображать ординалы байтов (целые числа в диапазоне от 0 до 255) в строки Unicode, целые числа (которые затем интерпретируются как ординалы Unicode) или None. Не отображенные байты данных - те, которые вызывают LookupError, а также те, которые отображаются в None, 0xFFFE или '\ufffe', рассматриваются как неопределенные отображения и вызывают ошибку.

PyObject *PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)¶

Return value: New reference. Part of the Stable ABI.

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

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

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

Return value: New reference.

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

Deprecated since version 3.3, will be removed in version 3.11: Часть API старого образца Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsCharmapString() или PyUnicode_AsEncodedString().

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

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

Return value: New reference. Part of the Stable ABI.

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

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

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

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

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

Return value: New reference.

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

Deprecated since version 3.3, will be removed in version 3.11: Часть API старого образца Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_Translate(). или generic codec based API

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

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

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

Return value: New reference. Part of the Stable ABI on Windows since version 3.7.

Создать объект Unicode путем декодирования size байт MBCS-кодированной строки s. Верните NULL, если кодек вызвал исключение.

PyObject *PyUnicode_DecodeMBCSStateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶

Return value: New reference. Part of the Stable ABI on Windows since version 3.7.

Если consumed равно NULL, ведет себя как PyUnicode_DecodeMBCS(). Если consumed не NULL, то PyUnicode_DecodeMBCSStateful() не будет декодировать ведущий байт, а количество байт, которые были декодированы, будет сохранено в consumed.

PyObject *PyUnicode_AsMBCSString(PyObject *unicode)¶

Return value: New reference. Part of the Stable ABI on Windows since version 3.7.

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

PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)¶

Return value: New reference. Part of the Stable ABI on Windows since version 3.7.

Кодирует объект Unicode с использованием указанной кодовой страницы и возвращает объект Python bytes. Верните NULL, если кодек вызвал исключение. Используйте кодовую страницу CP_ACP для получения кодека MBCS.

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

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

Return value: New reference.

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

Deprecated since version 3.3, will be removed in version 4.0: Часть API старого образца Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsMBCSString(), PyUnicode_EncodeCodePage() или PyUnicode_AsEncodedString().

Методы и слоты¶