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

Тип Юникода

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

Py_UCS4

Py_UCS2

Py_UCS1

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

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

Py_UNICODE

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

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

PyASCIIObject

PyCompactUnicodeObject

PyUnicodeObject

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

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

PyTypeObject PyUnicode_Type

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

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

int PyUnicode_Check(PyObject *o)

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

int PyUnicode_CheckExact(PyObject *o)

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

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)

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

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

int PyUnicode_KIND(PyObject *o)

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

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

void* PyUnicode_DATA(PyObject *o)

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

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

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

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

PyUnicode_MAX_CHAR_VALUE(o)

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

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

int PyUnicode_ClearFreeList()

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

Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)

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

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

Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)

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

Устарело начиная с версии 3.3, будет удалено в версии 3.12: Часть API Юникода старого стиля, пожалуйста, перейдите к использованию 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 должен быть объектом Юникода (не проверяется).

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

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

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

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

int Py_UNICODE_ISSPACE(Py_UNICODE ch)

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

int Py_UNICODE_ISLOWER(Py_UNICODE ch)

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

int Py_UNICODE_ISUPPER(Py_UNICODE ch)

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

int Py_UNICODE_ISTITLE(Py_UNICODE ch)

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

int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)

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

int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)

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

int Py_UNICODE_ISDIGIT(Py_UNICODE ch)

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

int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)

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

int Py_UNICODE_ISALPHA(Py_UNICODE ch)

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

int Py_UNICODE_ISALNUM(Py_UNICODE ch)

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

int Py_UNICODE_ISPRINTABLE(Py_UNICODE ch)

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

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

Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)

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

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

Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)

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

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

Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)

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

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

int Py_UNICODE_TODECIMAL(Py_UNICODE ch)

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

int Py_UNICODE_TODIGIT(Py_UNICODE ch)

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

double Py_UNICODE_TONUMERIC(Py_UNICODE ch)

Возвращает символ ch, преобразованный в число с плавающей точкой. Возвращает -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)

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

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

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

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

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

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

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

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

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

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

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

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

PyObject *PyUnicode_FromString(const char *u)

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

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

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

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

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

Символы формата	Тип	Примечание
%%	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*	Объект 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)

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

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

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

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

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

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

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

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

Py_ssize_t PyUnicode_GetLength(PyObject *unicode)

Возвращает длину объекта 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. Ранее для surrogateescape использовалась Py_DecodeLocale(), а для 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. Ранее для surrogateescape использовалась Py_EncodeLocale(), а для 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. Копируются не более size wchar_t символов (исключая возможный заключительный нулевой символ). Возвращает количество скопированных wchar_t символов или -1 в случае ошибки. Обратите внимание, что результирующая строка wchar_t* может быть или не быть завершаемой нулём. Ответственность вызывающей стороны – убедиться, что строка wchar_t* завершается нулём, если это требуется приложением. Также обратите внимание, что строка wchar_t* может содержать нулевые символы, что приведёт к обрезанию строки при использовании с большинством функций C.

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

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

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

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

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

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

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

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

Кодирует буфер Py_UNICODE s заданного размера size и возвращает объект Python bytes. encoding и errors имеют то же значение, что и параметры с таким же именем в методе 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, декодируя size байт строки s, закодированной в UTF-8. Возвращает 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. Обработка ошибок — "строгая". Возвращает NULL если кодек поднял исключение.

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

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

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

Кэширует UTF-8 представление строки в объекте 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 заданного размера size с помощью 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) определяет обработку ошибок. По умолчанию — "строгая".

Если 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 bytes с использованием кодировки UTF-32 в родном порядке байтов. Строка всегда начинается с маркера BOM.

Обработка ошибок — "строгая". Возвращает NULL если кодек поднял исключение.

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

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

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

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. Обработка ошибок — «strict». Возвращает 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. Обработка ошибок — «strict». Возвращает 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. Обработка ошибок — «strict». Возвращает 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. Обработка ошибок — «strict». Возвращает 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().

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