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

Тип Unicode

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

type Py_UCS4

type Py_UCS2

type Py_UCS1

Часть Стабильной ABI.

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

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

type Py_UNICODE

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

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

type PyASCIIObject

type PyCompactUnicodeObject

type PyUnicodeObject

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

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

PyTypeObject PyUnicode_Type

Часть Стабильной ABI.

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

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

int PyUnicode_Check(PyObject *o)

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

int PyUnicode_CheckExact(PyObject *o)

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

int PyUnicode_READY(PyObject *o)

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

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

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

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

Часть Стабильной ABI.

Возвращает 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 соответственно — старший и младший суррогаты в паре суррогатов.

Создание и доступ к строкам 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)

Значение возврата: Новая ссылка. Часть Стабильной ABI.

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

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

PyObject *PyUnicode_FromString(const char *u)

Значение возврата: Новая ссылка. Часть Стабильной ABI.

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

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

Значение возврата: Новая ссылка. Часть Стабильной ABI.

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

Значение возврата: Новая ссылка. Часть Стабильной ABI.

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

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

Значение возврата: Новая ссылка. Часть Стабильной ABI.

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

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

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

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

Py_ssize_t PyUnicode_GetLength(PyObject *unicode)

Часть Стабильной ABI начиная с версии 3.7.

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

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

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

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

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

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

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

Возвращает ошибку, если fill_char больше максимального символа строки, или если строка имеет более одной ссылки.

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

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

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

Часть Стабильной ABI начиная с версии 3.7.

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

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

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

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)

Часть Стабильной ABI начиная с версии 3.7.

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

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

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

Значение возврата: Новая ссылка. Часть Стабильной ABI начиная с версии 3.7.

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

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

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

Часть Стабильной ABI начиная с версии 3.7.

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

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

Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *u)

Часть Стабильной ABI начиная с версии 3.7.

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

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

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

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

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

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

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

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

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

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_ssize_t PyUnicode_GetSize(PyObject *unicode)

Часть Стабильной ABI.

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

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

PyObject *PyUnicode_FromObject(PyObject *obj)

Значение возврата: Новая ссылка. Часть Стабильной ABI.

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

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

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

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

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

Возвращаемое значение: Новая ссылка. Часть Стабильной ABI с версии 3.7.

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

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

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

См. также

Функцию Py_DecodeLocale().

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

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

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

Возвращаемое значение: Новая ссылка. Часть Стабильной ABI с версии 3.7.

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

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

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

Возвращаемое значение: Новая ссылка. Часть Стабильной ABI с версии 3.7.

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

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

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

См. также

Функцию 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)

Часть Стабильной ABI.

Преобразователь 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)

Часть Стабильной ABI.

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

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

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

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

Значение возврата: Новая ссылка. Часть Стабильной ABI.

Декодирование строки из кодировки и обработчика ошибок файловой системы.

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

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

См. также

Функцию Py_DecodeLocale().

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

PyObject *PyUnicode_DecodeFSDefault(const char *s)

Значение возврата: Новая ссылка. Часть Стабильной ABI.

Декодирует строку с нулевым завершением из кодировки и обработчика ошибок файловой системы.

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

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

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

PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)

Значение возврата: Новая ссылка. Часть Стабильной ABI.

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

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

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

См. также

Функцию Py_EncodeLocale().

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

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

Поддержка wchar_t

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

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

Значение возврата: Новая ссылка. Часть Стабильной ABI.

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

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

Часть Стабильной ABI.

Копирование содержимого объекта 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)

Часть Стабильной ABI с версии 3.7.

Преобразование объекта 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)

Значение возврата: новая ссылка. Часть стабильной ABI.

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

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

Значение возврата: новая ссылка. Часть стабильной ABI.

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

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

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

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

Значение возврата: новая ссылка. Часть стабильной ABI.

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

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

Значение возврата: новая ссылка. Часть стабильной ABI.

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

PyObject *PyUnicode_AsUTF8String(PyObject *unicode)

Значение возврата: новая ссылка. Часть стабильной ABI.

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

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

Часть стабильной ABI начиная с версии 3.10.

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

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

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

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

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

Изменено в версии 3.10: Эта функция входит в ограниченный API.

const char *PyUnicode_AsUTF8(PyObject *unicode)

Аналогично PyUnicode_AsUTF8AndSize(), но не сохраняет размер.

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

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

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

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

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

Значение возврата: Новая ссылка. Часть Стабильной ABI.

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

Значение возврата: Новая ссылка. Часть Стабильной ABI.

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

PyObject *PyUnicode_AsUTF32String(PyObject *unicode)

Значение возврата: Новая ссылка. Часть Стабильной ABI.

Возвращает строку байтов Python, используя кодировку 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)

Значение возврата: Новая ссылка. Часть Стабильной ABI.

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

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

Значение возврата: Новая ссылка. Часть Стабильной ABI.

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

PyObject *PyUnicode_AsUTF16String(PyObject *unicode)

Значение возврата: Новая ссылка. Часть Стабильной ABI.

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

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

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

Возвращает объект Python bytes, содержащий закодированное в UTF-16 значение данных 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 определено, одно значение 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)

Значение возврата: Новая ссылка. Часть Стабильной ABI.

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

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

Значение возврата: Новая ссылка. Часть Стабильной ABI.

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

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

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

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

Значение возврата: новая ссылка. Часть Стабильной ABI.

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

PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)

Значение возврата: новая ссылка. Часть Стабильной ABI.

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

Значение возврата: новая ссылка. Часть Стабильной ABI.

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

PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)

Значение возврата: новая ссылка. Часть Стабильной ABI.

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

Значение возврата: новая ссылка. Часть Стабильной ABI.

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

PyObject *PyUnicode_AsLatin1String(PyObject *unicode)

Значение возврата: новая ссылка. Часть Стабильной ABI.

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

Значение возврата: новая ссылка. Часть Стабильной ABI.

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

PyObject *PyUnicode_AsASCIIString(PyObject *unicode)

Значение возврата: новая ссылка. Часть Стабильной ABI.

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

Значение возврата: новая ссылка. Часть Стабильной ABI.

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

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

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

Значение возврата: новая ссылка. Часть Стабильной ABI.

Закодировать объект 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 заданного size с использованием объекта 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)

Значение возврата: новая ссылка. Часть Стабильной ABI.

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

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

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

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

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

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

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

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

Кодеки MBCS для Windows

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

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

Значение возврата: новая ссылка. Часть Стабильной ABI в Windows начиная с версии 3.7.

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

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

Значение возврата: новая ссылка. Часть Стабильной ABI в Windows начиная с версии 3.7.

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

PyObject *PyUnicode_AsMBCSString(PyObject *unicode)

Значение возврата: новая ссылка. Часть Стабильной ABI в Windows начиная с версии 3.7.

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

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

Значение возврата: новая ссылка. Часть Стабильной ABI в Windows начиная с версии 3.7.

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

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

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

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

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

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

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