Объекты bytes

Эти функции вызывают TypeError, если ожидают параметр bytes, но вызываются с параметром, не являющимся bytes.

type PyBytesObject: Этот подтип PyObject представляет объект bytes в Python.

PyTypeObject PyBytes_Type: Часть стабильного ABI.
Этот экземпляр PyTypeObject представляет тип bytes в Python; это тот же объект, что и bytes на уровне Python.

int PyBytes_Check(PyObject *o): Возвращает true, если объект o является объектом bytes или экземпляром подтипа типа bytes. Эта функция всегда завершается успешно.

int PyBytes_CheckExact(PyObject *o): Возвращает true, если объект o является объектом bytes, но не экземпляром подтипа типа bytes. Эта функция всегда завершается успешно.

PyObject *PyBytes_FromString(const char *v): Возвращаемое значение: новая ссылка. Часть стабильного ABI. Потокобезопасность: атомарная.
В случае успеха возвращает новый объект bytes, содержащий копию строки v, а в случае ошибки — NULL. Параметр v не должен быть NULL; его значение не проверяется.

PyObject *PyBytes_FromStringAndSize(const char *v, Py_ssize_t len): Возвращаемое значение: новая ссылка. Часть стабильного ABI. Потокобезопасность: атомарная.
В случае успеха возвращает новый объект bytes, содержащий копию строки v и имеющий длину len, а в случае ошибки — NULL. Если v равен NULL, содержимое объекта bytes не инициализируется.

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

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

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

Символы формата	Тип	Комментарий
`%%`	не применимо	Литеральный символ %.
`%c`	int	Один байт, представленный как int в C.
`%d`	int	Эквивалентно `printf("%d")`. [1]
`%u`	unsigned int	Эквивалентно `printf("%u")`. [1]
`%ld`	long	Эквивалентно `printf("%ld")`. [1]
`%lu`	unsigned long	Эквивалентно `printf("%lu")`. [1]
`%zd`	`Py_ssize_t`	Эквивалентно `printf("%zd")`. [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` платформы.

Неизвестный символ формата приводит к копированию всей оставшейся части строки формата в результирующий объект без изменений; любые дополнительные аргументы отбрасываются.

PyObject *PyBytes_FromFormatV(const char *format, va_list vargs): Возвращаемое значение: новая ссылка. Часть стабильного ABI. Потокобезопасность: атомарная.
Идентична PyBytes_FromFormat(), за исключением того, что принимает ровно два аргумента.

PyObject *PyBytes_FromObject(PyObject *o): Возвращаемое значение: новая ссылка. Часть стабильного ABI. Потокобезопасность: безопасно для параллельного использования с тем же объектом.
Возвращает байтовое представление объекта o, реализующего протокол буфера.

Примечание

Если объект реализует протокол буфера, буфер нельзя изменять во время создания объекта bytes.

Py_ssize_t PyBytes_Size(PyObject *o): Часть стабильного ABI. Потокобезопасность: атомарная.
Возвращает длину байтов в объекте bytes o.

Py_ssize_t PyBytes_GET_SIZE(PyObject *o): Потокобезопасность: атомарная.
Аналогична PyBytes_Size(), но без проверки ошибок.

char *PyBytes_AsString(PyObject *o): Часть стабильного ABI. Потокобезопасность: безопасно вызывать из нескольких потоков только при внешней синхронизации.
Возвращает указатель на содержимое o. Указатель ссылается на внутренний буфер o, состоящий из len(o) + 1 байтов. Последний байт буфера всегда равен нулю независимо от наличия других нулевых байтов. Данные нельзя изменять каким-либо образом, если только объект не был только что создан с помощью PyBytes_FromStringAndSize(NULL, size). Их нельзя освобождать. Если o вообще не является объектом bytes, PyBytes_AsString() возвращает NULL и вызывает TypeError.

char *PyBytes_AS_STRING(PyObject *string): Потокобезопасность: безопасно вызывать из нескольких потоков только при внешней синхронизации.
Аналогична PyBytes_AsString(), но без проверки ошибок.

int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)

Часть стабильного ABI. Потокобезопасность: безопасно вызывать из нескольких потоков только при внешней синхронизации.

Возвращает содержимое объекта obj с нулевым завершающим байтом через выходные переменные buffer и length. В случае успеха возвращает 0.

Если length равен NULL, объект bytes не должен содержать встроенных нулевых байтов; если они есть, функция возвращает -1 и вызывает ValueError.

Буфер ссылается на внутренний буфер obj, который включает дополнительный нулевой байт в конце (не учитываемый в length). Данные нельзя изменять каким-либо образом, если только объект не был только что создан с помощью PyBytes_FromStringAndSize(NULL, size). Их нельзя освобождать. Если obj вообще не является объектом bytes, PyBytes_AsStringAndSize() возвращает -1 и вызывает TypeError.

Изменено в версии 3.5: Ранее при обнаружении встроенных нулевых байтов в объекте bytes вызывалась TypeError.

void PyBytes_Concat(PyObject **bytes, PyObject *newpart): Часть стабильного ABI. Потокобезопасность: безопасно для параллельного использования с тем же объектом.
Создает новый объект bytes в *bytes, содержащий содержимое bytes с добавленным в конец содержимым newpart; вызывающий код получает новую ссылку. Ссылка на прежнее значение bytes будет «украдена». Если новый объект создать не удастся, старая ссылка на bytes всё равно будет «украдена», значение *bytes будет установлено в NULL, а соответствующее исключение будет установлено.

Примечание

Если newpart реализует протокол буфера, буфер нельзя изменять во время создания нового объекта bytes.

void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart): Часть стабильного ABI. Потокобезопасность: безопасно для параллельного использования с тем же объектом.
Создает новый объект bytes в *bytes, содержащий содержимое bytes с добавленным в конец содержимым newpart. Эта версия освобождает сильную ссылку на newpart (то есть уменьшает счетчик ссылок на него).

Примечание

Если newpart реализует протокол буфера, буфер нельзя изменять во время создания нового объекта bytes.

PyObject *PyBytes_Join(PyObject *sep, PyObject *iterable)

Потокобезопасность: безопасно для параллельного использования с тем же объектом.

Аналогична sep.join(iterable) в Python.

sep должен быть объектом bytes в Python bytes. (Обратите внимание, что PyUnicode_Join() принимает разделитель NULL и интерпретирует его как пробел, тогда как PyBytes_Join() не принимает разделитель NULL.)

iterable должен быть итерируемым объектом, выдающим объекты, реализующие протокол буфера.

В случае успеха возвращает новый объект bytes. В случае ошибки устанавливает исключение и возвращает NULL.

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

Примечание

Если объекты iterable реализуют протокол буфера, эти буферы нельзя изменять во время создания нового объекта bytes.

int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize): Потокобезопасность: безопасно вызывать без внешней синхронизации для различных объектов.
Изменяет размер объекта bytes. newsize задает новую длину объекта bytes. Это можно представить как создание нового объекта bytes и уничтожение старого, но более эффективным способом. Передайте адрес существующего объекта bytes как lvalue (в него может быть записано новое значение) и требуемый новый размер. В случае успеха *bytes содержит объект bytes с измененным размером, а функция возвращает 0; адрес в *bytes может отличаться от исходного. Если перераспределение памяти не удается, исходный объект bytes по адресу *bytes освобождается, *bytes устанавливается в NULL, устанавливается MemoryError, а функция возвращает -1.

PyObject *PyBytes_Repr(PyObject *bytes, int smartquotes)

Часть стабильного ABI. Потокобезопасность: атомарная.

Возвращает строковое представление объекта bytes. В настоящее время эта функция используется для реализации bytes.__repr__() в Python.

Эта функция не проверяет тип; передача bytes в виде объекта, не являющегося bytes, или NULL приводит к неопределенному поведению.

Если smartquotes имеет значение true, в представлении будут использоваться двойные кавычки вместо одинарных, если в bytes присутствуют одинарные кавычки. Например, байтовая строка 'Python' будет представлена как b"'Python'", если smartquotes имеет значение true, или как b'\'Python\'', если оно равно false.

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

PyObject *PyBytes_DecodeEscape(const char *s, Py_ssize_t len, const char *errors, Py_ssize_t unicode, const char *recode_encoding)

Часть стабильного ABI. Потокобезопасность: атомарная.

Декодирует строку s с экранированными обратной косой чертой символами. s не должна быть NULL. len должен задавать размер s.

errors должно быть одним из значений "strict", "replace" или "ignore". Если errors равно NULL, по умолчанию используется "strict".

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

Изменено в версии 3.9: unicode и recode_encoding больше не используются.