Объекты Unicode и кодеки

Тип Unicode

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

Py_UCS4

Py_UCS2

Py_UCS1

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

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

Py_UNICODE

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

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

PyASCIIObject

PyCompactUnicodeObject

PyUnicodeObject

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

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

PyTypeObject PyUnicode_Type

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

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

int PyUnicode_Check(PyObject *o)

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

int PyUnicode_CheckExact(PyObject *o)

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

int PyUnicode_READY(PyObject *o)

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

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

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

Устарело начиная с версии 3.10, будет удалено в версии 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.

Устарело начиная с версии 3.10, будет удалено в версии 3.12: PyUnicode_WCHAR_KIND устарел.

unsigned int PyUnicode_KIND(PyObject *o)

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

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

void* PyUnicode_DATA(PyObject *o)

Возвращает указатель на сырой буфер 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()). Проверки или вызовы ready не выполняются.

Добавлена в версии 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 (не проверяется).

Устарело начиная с версии 3.3, будет удалено в версии 3.12: Часть API Unicode старого стиля, пожалуйста, перейдите к использованию PyUnicode_GET_LENGTH().

Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)

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

Устарело начиная с версии 3.3, будет удалено в версии 3.12: Часть API Unicode старого стиля, пожалуйста, перейдите к использованию PyUnicode_GET_LENGTH().

Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)

const char* PyUnicode_AS_DATA(PyObject *o)

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

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

Устарело начиная с версии 3.3, будет удалено в версии 3.12: Часть API Unicode старого стиля, пожалуйста, перейдите к использованию семейства макросов PyUnicode_nBYTE_DATA().

int PyUnicode_IsIdentifier(PyObject *o)

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

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

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

Юникод предоставляет множество различных свойств символов. Наиболее часто используемые из них доступны через эти макросы, которые отображаются на 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 печатаемым символом. Непечатаемые символы — это те символы, которые определены в базе данных символов Юникода как «Другие» или «Разделители», за исключением 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 — соответственно, старший и младший суррогаты в паре суррогатов.

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

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

PyObject* PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)

Значение возврата: Новая ссылка.

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

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

Новая в версии 3.3.

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

Значение возврата: Новая ссылка.

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

Новая в версии 3.3.

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

Значение возврата: Новая ссылка.

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

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

PyObject *PyUnicode_FromString(const char *u)

Значение возврата: Новая ссылка.

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

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

Значение возврата: Новая ссылка.

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

Символы формата	Тип	Комментарий
%%	n/a	Буквальное значение %.
%c	int	Один символ, представленный как целочисленное значение C.
%d	int	Эквивалентно printf("%d"). 1
%u	unsigned int	Эквивалентно printf("%u"). 1
%ld	long	Эквивалентно printf("%ld"). 1
%li	long	Эквивалентно printf("%li"). 1
%lu	unsigned long	Эквивалентно printf("%lu"). 1
%lld	long long	Эквивалентно printf("%lld"). 1
%lli	long long	Эквивалентно printf("%lli"). 1
%llu	unsigned long long	Эквивалентно printf("%llu"). 1
%zd	Py_ssize_t	Эквивалентно printf("%zd"). 1
%zi	Py_ssize_t	Эквивалентно printf("%zi"). 1
%zu	size_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*	Объект Юникода.
%V	PyObject*, const char*	Объект Юникода (который может быть 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)

Значение возврата: Новая ссылка.

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

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

Значение возврата: Новая ссылка.

Декодирование закодированного объекта obj в объект Юникода.

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

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

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

Py_ssize_t PyUnicode_GetLength(PyObject *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)

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

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

Новая в версии 3.3.

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)

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

Новая в версии 3.3.

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

Значение возврата: Новая ссылка.

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

Новая в версии 3.3.

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

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

Новая в версии 3.3.

Py_UCS4* PyUnicode_AsUCS4Copy(PyObject *u)

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

Новая в версии 3.3.

Устаревшие Py_UNICODE API

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

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

Значение возврата: Новый ссылка.

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

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

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

Устарел с версии 3.3, будет удалён в версии 3.12: Часть API старого стиля Unicode, пожалуйста, переместитесь на использование PyUnicode_FromKindAndData(), PyUnicode_FromWideChar() или PyUnicode_New().

Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)

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

Устарел с версии 3.3, будет удалён в версии 3.12: Часть API старого стиля Unicode, пожалуйста, переместитесь на использование PyUnicode_AsUCS4(), PyUnicode_AsWideChar(), PyUnicode_ReadChar() или аналогичные новые API.

Устарел с версии 3.3, будет удалён в версии 3.10.

PyObject* PyUnicode_TransformDecimalToASCII(Py_UNICODE *s, Py_ssize_t size)

Значение возврата: Новый ссылка.

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

Устарел с версии 3.3, будет удалён в версии 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* может содержать встроенные нулевые кодовые точки, что приведёт к усечению строки при использовании в большинстве функций C.

Новая в версии 3.3.

Устарел с версии 3.3, будет удалён в версии 3.12: Часть API старого стиля Unicode, пожалуйста, переместитесь на использование PyUnicode_AsUCS4(), PyUnicode_AsWideChar(), PyUnicode_ReadChar() или аналогичные новые API.

Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode)

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

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

Пожалуйста, перейдите на использование PyUnicode_AsUCS4Copy() или аналогичные новые API.

Py_ssize_t PyUnicode_GetSize(PyObject *unicode)

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

Устарел с версии 3.3, будет удалён в версии 3.12: Часть API старого стиля Unicode, пожалуйста, перейдите на использование PyUnicode_GET_LENGTH().

PyObject* PyUnicode_FromObject(PyObject *obj)

Значение возврата: Новый ссылка.

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

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

Кодировка локали

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

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

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

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

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

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

См. также

Функцию Py_DecodeLocale().

Новая в версии 3.3.

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

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

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

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

Новая в версии 3.3.

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

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

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

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

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

См. также

Функцию Py_EncodeLocale().

Новая в версии 3.3.

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

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

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

int PyUnicode_FSConverter(PyObject* obj, void* result)

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

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

Изменено в версии 3.6: Принимает объект объект пути.

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

int PyUnicode_FSDecoder(PyObject* obj, void* result)

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

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

Изменено в версии 3.6: Принимает объект объект пути.

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

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

Декодирует строку, используя Py_FileSystemDefaultEncoding и обработчик ошибок Py_FileSystemDefaultEncodeErrors.

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

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

См. также

Функцию Py_DecodeLocale().

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

PyObject* PyUnicode_DecodeFSDefault(const char *s)

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

Декодирует строку с нулевым завершением, используя Py_FileSystemDefaultEncoding и обработчик ошибок Py_FileSystemDefaultEncodeErrors.

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

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

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

PyObject* PyUnicode_EncodeFSDefault(PyObject *unicode)

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

Кодирует объект 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)

Значение возврата: Новая ссылка.

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

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

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

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

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

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

Введено в версии 3.2.

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

Общие кодеки

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

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

Значение возврата: Новая ссылка.

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

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

Значение возврата: Новая ссылка.

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

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

Значение возврата: Новая ссылка.

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

Устарело начиная с версии 3.3, будет удалено в версии 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)

Значение возврата: Новая ссылка.

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

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

Значение возврата: Новая ссылка.

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

PyObject* PyUnicode_AsUTF8String(PyObject *unicode)

Значение возврата: Новая ссылка.

Кодирует объект Unicode в UTF-8 и возвращает результат как объект Python bytes. Обработка ошибок - "strict". Возвращает NULL если кодек вызвал исключение.

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

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

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

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

Введено в версии 3.3.

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

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)

Значение возврата: Новая ссылка.

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

Устарело начиная с версии 3.3, будет удалено в версии 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)

Значение возврата: новая ссылка.

Декодировать 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)

Значение возврата: новая ссылка.

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

PyObject* PyUnicode_AsUTF32String(PyObject *unicode)

Значение возврата: новая ссылка.

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

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

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

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

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

Устарело начиная с версии 3.3, будет удалено в версии 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)

Значение возврата: новая ссылка.

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

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

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

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

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

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

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

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

Значение возврата: новая ссылка.

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

PyObject* PyUnicode_AsUTF16String(PyObject *unicode)

Значение возврата: новая ссылка.

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

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

Значение возврата: новая ссылка.

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

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

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

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

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

Устарело начиная с версии 3.3, будет удалено в версии 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)

Значение возврата: новая ссылка.

Создать объект 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, хвостовые неполные секции UTF-7 base-64 не будут обрабатываться как ошибка. Эти байты не будут декодированы, и количество декодированных байтов будет сохранено в 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».

Устарело начиная с версии 3.3, будет удалено в версии 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)

Значение возврата: новая ссылка.

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

PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)

Значение возврата: новая ссылка.

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

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

Значение возврата: новая ссылка.

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

Устарело начиная с версии 3.3, будет удалено в версии 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)

Значение возврата: Новая ссылка.

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

PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)

Значение возврата: Новая ссылка.

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

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

Значение возврата: Новая ссылка.

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

Устарело начиная с версии 3.3, будет удалено в версии 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)

Значение возврата: Новая ссылка.

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

PyObject* PyUnicode_AsLatin1String(PyObject *unicode)

Значение возврата: Новая ссылка.

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

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

Значение возврата: Новая ссылка.

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

Устарело начиная с версии 3.3, будет удалено в версии 3.11: Часть старого API Py_UNICODE; пожалуйста, перейдите к использованию PyUnicode_AsLatin1String() или PyUnicode_AsEncodedString().

Кодировки ASCII

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

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

Значение возврата: Новая ссылка.

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

PyObject* PyUnicode_AsASCIIString(PyObject *unicode)

Значение возврата: Новая ссылка.

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

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

Значение возврата: Новая ссылка.

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

Устарело начиная с версии 3.3, будет удалено в версии 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)

Значение возврата: Новая ссылка.

Создаёт объект 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)

Значение возврата: Новая ссылка.

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

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

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

Значение возврата: Новая ссылка.

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

Устарело начиная с версии 3.3, будет удалено в версии 3.11: Часть старого API Py_UNICODE; пожалуйста, перейдите к использованию PyUnicode_AsCharmapString() или PyUnicode_AsEncodedString().

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

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

Значение возврата: Новая ссылка.

Переводит строку, применяя к ней таблицу отображения символов, и возвращает результирующий объект 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)

Значение возврата: Новая ссылка.

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

Устарело начиная с версии 3.3, будет удалено в версии 3.11: Часть старого API Py_UNICODE; пожалуйста, перейдите к использованию PyUnicode_Translate(). или API общей кодировки

Кодеки MBCS для Windows

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

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

Значение возврата: Новая ссылка.

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

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

Значение возврата: Новая ссылка.

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

PyObject* PyUnicode_AsMBCSString(PyObject *unicode)

Значение возврата: Новая ссылка.

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

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

Значение возврата: Новая ссылка.

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

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

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

Значение возврата: Новая ссылка.

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

Устарело начиная с версии 3.3, будет удалено в версии 4.0: Часть старого API Py_UNICODE; перейдите к использованию PyUnicode_AsMBCSString(), PyUnicode_EncodeCodePage() или PyUnicode_AsEncodedString().

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