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

Тип Unicode¶Unicode Type

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

type Py_UCS4¶

type Py_UCS2¶

type Py_UCS1¶

Часть Stable ABI.

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

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

type Py_UNICODE¶

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

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

type PyASCIIObject¶

type PyCompactUnicodeObject¶

type PyUnicodeObject¶

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

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

PyTypeObject PyUnicode_Type¶

Часть Stable ABI.

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

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

int PyUnicode_Check(PyObject *obj)¶

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

int PyUnicode_CheckExact(PyObject *obj)¶

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

int PyUnicode_READY(PyObject *unicode)¶

Возвращает 0. Этот API сохранён только для обратной совместимости.

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

Устарело с версии 3.10: Этот API ничего не делает, начиная с Python 3.12.

Py_ssize_t PyUnicode_GET_LENGTH(PyObject *unicode)¶

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

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

Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *unicode)¶

Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *unicode)¶

Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *unicode)¶

Возвращает указатель на каноническое представление, приведённый к целочисленным типам UCS1, UCS2 или UCS4 для прямого доступа к символам. Не выполняется проверок, имеет ли каноническое представление правильный размер символа; используйте PyUnicode_KIND(), чтобы выбрать подходящую функцию.

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

PyUnicode_1BYTE_KIND¶

PyUnicode_2BYTE_KIND¶

PyUnicode_4BYTE_KIND¶

Возвращает значения макроса PyUnicode_KIND().

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

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

int PyUnicode_KIND(PyObject *unicode)¶

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

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

void *PyUnicode_DATA(PyObject *unicode)¶

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

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

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

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

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

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

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

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

Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)¶

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

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

Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *unicode)¶

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

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

int PyUnicode_IsIdentifier(PyObject *unicode)¶

Часть Stable ABI.

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

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

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

Unicode предоставляет множество различных свойств символов. Наиболее востребованные из них доступны через следующие макросы, которые сопоставляются с функциями на 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 символом в регистре заголовка (titlecase).

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 печатным символом в смысле str.isprintable().

Эти 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, преобразованный в число двойной точности (double). Возвращает -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].

Создание строк 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. Объекты, созданные с помощью этой функции, не подлежат изменению размера.

При ошибке устанавливает исключение и возвращает NULL.

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

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

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

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

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

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

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

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

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

Эта функция вызывает SystemError в следующих случаях:

• size < 0

• str равен NULL и size > 0

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

PyObject *PyUnicode_FromString(const char *str)¶

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

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

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

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

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

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

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*.

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

Спецификатор преобразования	Тип	Описание
%	н/д	Литеральный символ %.
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)¶

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

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

PyObject *PyUnicode_FromObject(PyObject *obj)¶

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

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

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

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

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

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

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

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

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

const char *PyUnicode_GetDefaultEncoding(void)¶

Часть Stable ABI.

Возвращает имя кодировки строк по умолчанию, "utf-8". См. sys.getdefaultencoding().

Возвращаемую строку не нужно освобождать, она действует до завершения интерпретатора.

Py_ssize_t PyUnicode_GetLength(PyObject *unicode)¶

Часть Stable ABI начиная с версии 3.7.

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

При ошибке устанавливает исключение и возвращает -1.

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

Часть Stable ABI начиная с версии 3.7.

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

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

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

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

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)¶

Часть Stable ABI начиная с версии 3.7.

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

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

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

PyObject *PyUnicode_Substring(PyObject *unicode, Py_ssize_t start, Py_ssize_t end)¶

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

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

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

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

Часть Stable ABI начиная с версии 3.7.

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

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

Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)¶

Часть Stable ABI начиная с версии 3.7.

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

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

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

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

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

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

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

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

См. также

Функция Py_DecodeLocale().

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

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

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

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

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

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

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

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

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

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

См. также

Функция Py_EncodeLocale().

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

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

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

Functions encoding to and decoding from the filesystem encoding and error handler (PEP 383 and PEP 529).

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

int PyUnicode_FSConverter(PyObject *obj, void *result)¶

Часть Stable ABI.

PyArg_Parse* converter: encode str objects – obtained directly or through the os.PathLike interface – to bytes using PyUnicode_EncodeFSDefault(); bytes objects are output as-is. result must be an address of a C variable of type PyObject* (or PyBytesObject*). On success, set the variable to a new strong reference to a bytes object which must be released when it is no longer used and return a non-zero value (Py_CLEANUP_SUPPORTED). Embedded null bytes are not allowed in the result. On failure, return 0 with an exception set.

Если obj равно NULL, функция освобождает сильную ссылку, сохраненную в переменной, на которую указывает result, и возвращает 1.

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

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

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

int PyUnicode_FSDecoder(PyObject *obj, void *result)¶

Часть Stable ABI.

PyArg_Parse* converter: decode bytes objects – obtained either directly or indirectly through the os.PathLike interface – to str using PyUnicode_DecodeFSDefaultAndSize(); str objects are output as-is. result must be an address of a C variable of type PyObject* (or PyUnicodeObject*). On success, set the variable to a new strong reference to a Unicode object which must be released when it is no longer used and return a non-zero value (Py_CLEANUP_SUPPORTED). Embedded null characters are not allowed in the result. On failure, return 0 with an exception set.

Если obj равно NULL, освободите сильную ссылку на объект, на который указывает result, и верните 1.

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

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

PyObject *PyUnicode_DecodeFSDefaultAndSize(const char *str, Py_ssize_t size)¶

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

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

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

См. также

Функция Py_DecodeLocale().

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

PyObject *PyUnicode_DecodeFSDefault(const char *str)¶

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

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

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

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

PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)¶

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

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

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

См. также

Функция Py_EncodeLocale().

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

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

Поддержка wchar_t¶wchar_t Support

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

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

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

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

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

Часть Stable 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)¶

Часть Stable 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* содержит нулевые символы.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

PyObject *PyUnicode_AsUTF8String(PyObject *unicode)¶

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

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

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

Часть Stable 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(), но не сохраняет размер.

Предупреждение

Эта функция не имеет специального поведения для нулевых символов, встроенных в unicode. В результате строки, содержащие нулевые символы, останутся в возвращаемой строке, что некоторые функции C могут интерпретировать как конец строки, приводя к усечению. Если усечение является проблемой, рекомендуется использовать PyUnicode_AsUTF8AndSize() вместо этого.

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

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

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

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

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

Возвращаемое значение: новая ссылка. Часть Stable 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)¶

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

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

PyObject *PyUnicode_AsUTF32String(PyObject *unicode)¶

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

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

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

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

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

Возвращаемое значение: новая ссылка. Часть Stable 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)¶

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

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

PyObject *PyUnicode_AsUTF16String(PyObject *unicode)¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)¶

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

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

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

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

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

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

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

PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)¶

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

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

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

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

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

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

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

PyObject *PyUnicode_AsLatin1String(PyObject *unicode)¶

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

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

Кодеки ASCII¶ASCII Codecs

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

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

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

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

PyObject *PyUnicode_AsASCIIString(PyObject *unicode)¶

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

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

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

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

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

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

Возвращаемое значение: новая ссылка. Часть Stable 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)¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Создаёт объект Unicode путём декодирования size байтов строки str, закодированной в MBCS. Возвращает 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_DecodeCodePageStateful(int code_page, const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶

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

Аналогично PyUnicode_DecodeMBCSStateful(), но использует кодовую страницу, указанную в code_page.

PyObject *PyUnicode_AsMBCSString(PyObject *unicode)¶

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

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

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

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

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

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

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