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

Тип Unicode¶Unicode Type

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

Py_UCS4¶

Py_UCS2¶

Py_UCS1¶

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

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

Py_UNICODE¶

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

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

PyASCIIObject¶

PyCompactUnicodeObject¶

PyUnicodeObject¶

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

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

PyTypeObject PyUnicode_Type¶

Этот экземпляр PyTypeObject представляет тип Unicode в Python. Он доступен коду 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 kind (см. выше), которые показывают, сколько байт на символ использует этот объект Unicode для хранения данных. o должен быть объектом Unicode в «каноническом» представлении (не проверяется).

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

void* PyUnicode_DATA(PyObject*o)¶

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

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

void PyUnicode_WRITE(intkind, void*data, Py_ssize_tindex, Py_UCS4value)¶

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

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

Py_UCS4 PyUnicode_READ(intkind, void*data, Py_ssize_tindex)¶

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

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

Py_UCS4 PyUnicode_READ_CHAR(PyObject*o, Py_ssize_tindex)¶

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

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

PyUnicode_MAX_CHAR_VALUE(o)¶

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

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

Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)¶

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

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

Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)¶

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

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

Py_UNICODE* PyUnicode_AS_UNICODE(PyObject*o)¶

const char* PyUnicode_AS_DATA(PyObject*o)¶

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

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

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

int PyUnicode_IsIdentifier(PyObject *o)¶

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

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

Свойства символов Unicode¶Unicode Character Properties

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

int Py_UNICODE_ISSPACE(Py_UCS4ch)¶

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

int Py_UNICODE_ISLOWER(Py_UCS4ch)¶

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

int Py_UNICODE_ISUPPER(Py_UCS4ch)¶

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

int Py_UNICODE_ISTITLE(Py_UCS4ch)¶

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

int Py_UNICODE_ISLINEBREAK(Py_UCS4ch)¶

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

int Py_UNICODE_ISDECIMAL(Py_UCS4ch)¶

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

int Py_UNICODE_ISDIGIT(Py_UCS4ch)¶

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

int Py_UNICODE_ISNUMERIC(Py_UCS4ch)¶

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

int Py_UNICODE_ISALPHA(Py_UCS4ch)¶

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

int Py_UNICODE_ISALNUM(Py_UCS4ch)¶

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

int Py_UNICODE_ISPRINTABLE(Py_UCS4ch)¶

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

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

Py_UCS4 Py_UNICODE_TOLOWER(Py_UCS4ch)¶

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

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

Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4ch)¶

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

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

Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4ch)¶

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

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

int Py_UNICODE_TODECIMAL(Py_UCS4ch)¶

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

int Py_UNICODE_TODIGIT(Py_UCS4ch)¶

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

double Py_UNICODE_TONUMERIC(Py_UCS4ch)¶

Возвращает символ ch, преобразованный в double. Возвращает -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 и доступ к ним¶Creating and accessing Unicode strings

Для создания объектов 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 с заданным видом (возможные значения: PyUnicode_1BYTE_KIND и т.д., возвращаемые PyUnicode_KIND()). Буфер должен указывать на массив из size единиц по 1, 2 или 4 байта на символ, в зависимости от вида.

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

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

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

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

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

PyObject *PyUnicode_FromString(const char *u)¶

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

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

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

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

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

Символы формата	Тип	Описание
%%	н/д	Буквальный символ %.
%c	int	Один символ, представленный как C int.
%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 и возбуждает исключение при ошибке.

Новое в версии 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.

Устаревшие API Py_UNICODE¶Deprecated Py_UNICODE APIs

Эти функции 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: Часть старого стиля Unicode API, перейдите на использование 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: Часть старого стиля Unicode API, перейдите на использование PyUnicode_AsUCS4(), PyUnicode_AsWideChar(), PyUnicode_ReadChar() или аналогичных новых API.

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

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

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

Создаёт объект Unicode, заменяя все десятичные цифры в буфере Py_UNICODE указанного размера size на цифры 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: Часть старого стиля Unicode API, перейдите на использование 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.

Кодировка локали¶Locale Encoding

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

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

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

Decode a string from UTF-8 on Android and VxWorks, or from the current locale encoding on other platforms. The supported error handlers are "strict" and "surrogateescape" (PEP 383). The decoder uses "strict" error handler if errors is NULL. str must end with a null character but cannot contain embedded null characters.

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

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

См. также

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

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

Encode a Unicode object to UTF-8 on Android and VxWorks, or to the current locale encoding on other platforms. The supported error handlers are "strict" and "surrogateescape" (PEP 383). The encoder uses "strict" error handler if errors is NULL. Return a bytes object. unicode cannot contain embedded null characters.

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

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

См. также

Функция Py_EncodeLocale().

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

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

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

Для кодирования и декодирования имён файлов и других строк окружения в качестве кодировки следует использовать 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 Support

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

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

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

Создаёт объект Unicode из буфера wchar_t w указанного размера size. Передача -1 в качестве size указывает, что функция должна сама вычислить длину, используя 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* содержит нулевые символы.

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

Это общие 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 и возвращает результат в виде объекта bytes. Параметры encoding и errors имеют тот же смысл, что и одноимённые параметры метода encode() объекта Unicode. Используемый кодек ищется с помощью реестра кодеков Python. Возвращает NULL, если кодек возбудил исключение.

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

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

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

Устарело с версии 3.3, будет удалено в версии 3.11: Часть старого API Py_UNICODE; переходите на использование PyUnicode_AsEncodedString().

Кодеки UTF-8¶UTF-8 Codecs

Это 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 и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает NULL, если кодек вызвал исключение.

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

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

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

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

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

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

const char* PyUnicode_AsUTF8(PyObject *unicode)¶

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

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

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

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

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

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

Устарело с версии 3.3, будет удалено в версии 3.11: Часть старого API Py_UNICODE; переходите на использование PyUnicode_AsUTF8String(), PyUnicode_AsUTF8AndSize() или PyUnicode_AsEncodedString().

Кодеки UTF-32¶UTF-32 Codecs

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

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

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

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

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

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

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

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

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

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

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

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

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

PyObject* PyUnicode_AsUTF32String(PyObject *unicode)¶

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

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

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

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

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

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

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

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

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

Устарело с версии 3.3, будет удалено в версии 3.11: Часть старого API Py_UNICODE; переходите на использование PyUnicode_AsUTF32String() или PyUnicode_AsEncodedString().

Кодеки UTF-32¶UTF-16 Codecs

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

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

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

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

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

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

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

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

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

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

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

Если 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¶UTF-7 Codecs

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

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

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

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

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

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

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

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

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

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

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

Устарело с версии 3.3, будет удалено в версии 3.11: Часть старого API Py_UNICODE; переходите на использование PyUnicode_AsEncodedString().

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

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

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

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

Создаёт объект Unicode, декодируя size байтов строки s, закодированной в Unicode-Escape. Возвращает 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 указанного size с помощью Unicode-Escape и возвращает объект bytes. Возвращает NULL, если кодек вызвал исключение.

Устарело с версии 3.3, будет удалено в версии 3.11: Часть старого API Py_UNICODE; переходите на использование PyUnicode_AsUnicodeEscapeString().

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

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

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

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

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

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

Устарело с версии 3.3, будет удалено в версии 3.11: Часть старого API Py_UNICODE; переходите на использование PyUnicode_AsRawUnicodeEscapeString() или PyUnicode_AsEncodedString().

Кодеки Latin-1¶Latin-1 Codecs

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

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

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

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

PyObject* PyUnicode_AsLatin1String(PyObject *unicode)¶

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

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

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

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

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

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

Кодеки ASCII¶ASCII Codecs

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

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

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

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

PyObject* PyUnicode_AsASCIIString(PyObject *unicode)¶

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

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

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

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

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

Устарело с версии 3.3, будет удалено в версии 3.11: Часть старого API Py_UNICODE; переходите на использование PyUnicode_AsASCIIString() или PyUnicode_AsEncodedString().

Кодеки с таблицей символов¶Character Map Codecs

Этот кодек особенный тем, что его можно использовать для реализации множества различных кодеков (именно так и были получены большинство стандартных кодеков, входящих в пакет 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. Обработка ошибок – «strict». Возвращает 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 заданного размера, применяя таблицу mapping символов, и возвращает результирующий объект Unicode. Возвращает NULL, когда кодек вызвал исключение.

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

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

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

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

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

Создаёт объект Unicode, декодируя size байт строки s, закодированной в MBCS. Возвращает 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 и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает NULL, если кодек вызвал исключение.

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

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

Кодирует объект Unicode с помощью указанной кодовой страницы и возвращает объект 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().

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