Unicode Objects and Codecs

Unicode Type

These are the basic Unicode object types used for the Unicode implementation in Python:

type Py_UCS4

type Py_UCS2

type Py_UCS1

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

These types are typedefs for unsigned integer types wide enough to contain characters of 32 bits, 16 bits and 8 bits, respectively. When dealing with single Unicode characters, use Py_UCS4.

Added in version 3.3.

type Py_UNICODE

This is a typedef of wchar_t, which is a 16-bit type or 32-bit type depending on the platform.

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

type PyASCIIObject

type PyCompactUnicodeObject

type PyUnicodeObject

These subtypes of PyObject represent a Python Unicode object. In almost all cases, they shouldn’t be used directly, since all API functions that deal with Unicode objects take and return PyObject pointers.

Added in version 3.3.

PyTypeObject PyUnicode_Type

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

This instance of PyTypeObject represents the Python Unicode type. It is exposed to Python code as str.

The following APIs are C macros and static inlined functions for fast checks and access to internal read-only data of Unicode objects:

int PyUnicode_Check(PyObject *obj)

Return true if the object obj is a Unicode object or an instance of a Unicode subtype. This function always succeeds.

int PyUnicode_CheckExact(PyObject *obj)

Return true if the object obj is a Unicode object, but not an instance of a subtype. This function always succeeds.

int PyUnicode_READY(PyObject *unicode)

Returns 0. This API is kept only for backward compatibility.

Added in version 3.3.

Deprecated since version 3.10: This API does nothing since Python 3.12.

Py_ssize_t PyUnicode_GET_LENGTH(PyObject *unicode)

Return the length of the Unicode string, in code points. unicode has to be a Unicode object in the “canonical” representation (not checked).

Added in version 3.3.

Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *unicode)

Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *unicode)

Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *unicode)

Return a pointer to the canonical representation cast to UCS1, UCS2 or UCS4 integer types for direct character access. No checks are performed if the canonical representation has the correct character size; use PyUnicode_KIND() to select the right function.

Added in version 3.3.

PyUnicode_1BYTE_KIND

PyUnicode_2BYTE_KIND

PyUnicode_4BYTE_KIND

Return values of the PyUnicode_KIND() macro.

Added in version 3.3.

Изменено в версии 3.12: PyUnicode_WCHAR_KIND было удалено.

int PyUnicode_KIND(PyObject *unicode)

Return one of the PyUnicode kind constants (see above) that indicate how many bytes per character this Unicode object uses to store its data. unicode has to be a Unicode object in the “canonical” representation (not checked).

Added in version 3.3.

void *PyUnicode_DATA(PyObject *unicode)

Return a void pointer to the raw Unicode buffer. unicode has to be a Unicode object in the “canonical” representation (not checked).

Added in version 3.3.

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

Write into a canonical representation data (as obtained with PyUnicode_DATA()). This function performs no sanity checks, and is intended for usage in loops. The caller should cache the kind value and data pointer as obtained from other calls. index is the index in the string (starts at 0) and value is the new code point value which should be written to that location.

Added in version 3.3.

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

Read a code point from a canonical representation data (as obtained with PyUnicode_DATA()). No checks or ready calls are performed.

Added in version 3.3.

Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)

Read a character from a Unicode object unicode, which must be in the “canonical” representation. This is less efficient than PyUnicode_READ() if you do multiple consecutive reads.

Added in version 3.3.

Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *unicode)

Return the maximum code point that is suitable for creating another string based on unicode, which must be in the “canonical” representation. This is always an approximation but more efficient than iterating over the string.

Added in version 3.3.

int PyUnicode_IsIdentifier(PyObject *unicode)

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

Return 1 if the string is a valid identifier according to the language definition, section Identifiers and keywords. Return 0 otherwise.

Изменено в версии 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 можно использовать для работы с суррогатами:

int Py_UNICODE_IS_SURROGATE(Py_UCS4 ch)

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

int Py_UNICODE_IS_HIGH_SURROGATE(Py_UCS4 ch)

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

int Py_UNICODE_IS_LOW_SURROGATE(Py_UCS4 ch)

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

Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)

Объединяет два символа-суррогата и возвращает одно значение Py_UCS4. high и low — соответственно, ведущий и хвостовой суррогаты в паре суррогатов. high должен находиться в диапазоне [0xD800; 0xDBFF], а low — в диапазоне [0xDC00; 0xDFFF].

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

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

PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)

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

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

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

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

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

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

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

При необходимости входной buffer копируется и преобразуется в каноническое представление. Например, если buffer — это строка UCS4 (PyUnicode_4BYTE_KIND) и она содержит только символы в диапазоне UCS1, она будет преобразована в UCS1 (PyUnicode_1BYTE_KIND).

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

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

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

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

Эта функция вызывает SystemError когда:

• size < 0,
• str является NULL и size > 0

Изменено в версии 3.12: str == NULL с size > 0 больше не разрешено.

PyObject *PyUnicode_FromString(const char *str)

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

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

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

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

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

Спецификатор преобразования содержит два или более символов и имеет следующие компоненты, которые должны следовать в таком порядке:

1. Символ '%', обозначающий начало спецификатора.
2. Флаги преобразования (необязательные), которые влияют на результат некоторых типов преобразований.
3. Минимальная ширина поля (необязательная). Если указана как '*' (звездочка), фактическая ширина указывается в следующем аргументе, который должен быть типа int, а объект для преобразования следует за минимальной шириной поля и необязательной точностью.
4. Точность (необязательная), указывается как '.' (точка) за которой следует точность. Если указана как '*' (звездочка), фактическая точность указывается в следующем аргументе, который должен быть типа int, а значение для преобразования следует за точностью.
5. Модификатор длины (необязательный).
6. Тип преобразования.

Символы флагов преобразования:

Флаг	Значение
0	Преобразование будет дополнено нулями для числовых значений.
-	Преобразованное значение выравнивается влево (переопределяет флаг 0 если оба заданы).

Модификаторы длины для следующих целочисленных преобразований (d, i, o, u, x, или X) задают тип аргумента (int по умолчанию):

Модификатор	Типы
l	long или unsigned long
ll	long long или unsigned long long
j	intmax_t или uintmax_t
z	size_t или ssize_t
t	ptrdiff_t

Модификатор длины l для следующих преобразований s или V указывает, что тип аргумента является const wchar_t*.

Спецификаторы преобразования:

Спецификатор преобразования	Тип	Комментарий
%	n/a	Буквальный символ %.
d, i	Устанавливается модификатором длины	Десятичное представление знакового целочисленного значения C.
u	Устанавливается модификатором длины	Десятичное представление беззнакового целочисленного значения C.
o	Устанавливается модификатором длины	Восьмеричное представление беззнакового целочисленного значения C.
x	Устанавливается модификатором длины	Шестнадцатеричное представление беззнакового целочисленного значения C (строчные буквы).
X	Устанавливается модификатором длины	Шестнадцатеричное представление беззнакового целочисленного значения C (заглавные буквы).
c	int	Один символ.
s	const char* или const wchar_t*	Нуль-терминированная строка C-стиля.
p	const void*	Шестнадцатеричное представление указателя C. По большей части эквивалентно printf("%p"), за исключением того, что гарантируется, что оно начнётся с буквальной строки 0x независимо от того, что даёт платформа printf.
A	PyObject*	Результат вызова ascii().
U	PyObject*	Объект Unicode.
V	PyObject*, const char* или const wchar_t*	Объект Unicode (который может быть NULL) и нуль-терминированная строка C-стиля в качестве второго параметра (которая будет использована, если первый параметр NULL).
S	PyObject*	Результат вызова PyObject_Str().
R	PyObject*	Результат вызова PyObject_Repr().

Примечание

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

Примечание

В отличие от C printf(), флаг 0 имеет эффект даже при указании точности для целочисленных преобразований (d, i, u, o, x, или X).

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

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

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

Изменено в версии 3.12: Поддержка спецификаторов преобразования o и X. Поддержка модификаторов длины j и t. Модификаторы длины теперь применяются ко всем целочисленным преобразованиям. Модификатор длины l теперь применяется к спецификаторам преобразования s и V. Поддержка переменной ширины и точности *. Поддержка флага -.

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

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

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

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

PyObject *PyUnicode_FromObject(PyObject *obj)

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

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

Объекты, не являющиеся Unicode или его подтипами, приведут к TypeError.

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 *unicode, Py_ssize_t start, Py_ssize_t end)

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

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

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

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

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

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

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

Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)

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

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

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

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

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

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

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

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

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

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

См. также

Функцию 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() для кодирования строки в кодировку и обработчик ошибок файловой системы.

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

См. также

Функцию Py_EncodeLocale().

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

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

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

Функции кодирования и декодирования из кодировки и обработчика ошибок файловой системы (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 *str, Py_ssize_t size)

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

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

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

См. также

Функцию Py_DecodeLocale().

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

PyObject *PyUnicode_DecodeFSDefault(const char *str)

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

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

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

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

PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)

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

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

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

См. также

Функцию Py_EncodeLocale().

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

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

Поддержка wchar_t

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

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

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

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

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

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

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

Когда wstr является NULL, возвращается размер, необходимый для хранения всех unicode, включая завершающий нуль.

Обратите внимание, что результирующая строка wchar_t* может или не быть завершённой нулём. Ответственность за обеспечение завершения строки wchar_t* нулём в случае необходимости для приложения лежит на вызывающей стороне. Также обратите внимание, что строка wchar_t* может содержать нулевые символы, что приведёт к обрезанию строки при использовании с большинством функций C.

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

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

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

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

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

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

Общие кодеки

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

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

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

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

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

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

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

UTF-8 кодеки

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

PyObject *PyUnicode_DecodeUTF8(const char *str, Py_ssize_t size, const char *errors)

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

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

PyObject *PyUnicode_DecodeUTF8Stateful(const char *str, 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. Обработка ошибок — “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 *.

UTF-32 кодеки

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

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

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

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

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

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

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

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

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

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

PyObject *PyUnicode_DecodeUTF32Stateful(const char *str, 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. Обработка ошибок — “strict”. Возвращает NULL если кодек вызвал исключение.

Кодировки UTF-16

Это API кодировок UTF-16:

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

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

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

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

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

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

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

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

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

PyObject *PyUnicode_DecodeUTF16Stateful(const char *str, 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. Обработка ошибок — «strict». Возвращает NULL если кодек поднял исключение.

Кодировки UTF-7

Это API кодировок UTF-7:

PyObject *PyUnicode_DecodeUTF7(const char *str, Py_ssize_t size, const char *errors)

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

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

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

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

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

Кодировки «Unicode Escape»

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

PyObject *PyUnicode_DecodeUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)

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

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

PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)

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

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

Кодировки «Raw Unicode Escape»

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

PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)

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

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

PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)

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

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

Кодировки Latin-1

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

PyObject *PyUnicode_DecodeLatin1(const char *str, Py_ssize_t size, const char *errors)

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

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

PyObject *PyUnicode_AsLatin1String(PyObject *unicode)

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

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

Кодировки ASCII

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

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

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

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

PyObject *PyUnicode_AsASCIIString(PyObject *unicode)

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

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

Кодеки таблицы символов

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

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

PyObject *PyUnicode_DecodeCharmap(const char *str, Py_ssize_t length, PyObject *mapping, const char *errors)

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

Создать объект Unicode, декодировав size байтов закодированной строки str с помощью предоставленного объекта 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 с объектами байтов, целыми числами в диапазоне от 0 до 255 или None. Неотображенные порядковые номера символов (те, которые вызывают LookupError), а также отображенные на None обрабатываются как «неопределенное отображение» и вызывают ошибку.

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

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

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

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

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

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

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

Кодеки MBCS для Windows

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

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

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

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

PyObject *PyUnicode_DecodeMBCSStateful(const char *str, 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.

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