Объекты bytes¶Bytes Objects

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

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

PyTypeObject PyBytes_Type¶: Часть Stable 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)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI. Потокобезопасность: Atomic.
Возвращает новый объект bytes с копией строки v в качестве значения в случае успеха, и NULL в случае неудачи. Параметр v не должен быть NULL; он не будет проверяться.

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

Мягко устарело с версии 3.15: Используйте API PyBytesWriter вместо PyBytes_FromStringAndSize(NULL, len).

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

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

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

Символы формата	Тип	Описание
`%%`	н/д	Буквальный символ %.
`%c`	int	Один байт, представленный как C int.
`%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)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI. Потокобезопасность: Безопасно для одновременного использования на одном объекте.
Возвращает байтовое представление объекта o, реализующего протокол буфера.

Примечание

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

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

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

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

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

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

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

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

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

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

Изменено в версии 3.5: Ранее, TypeError возбуждалось, когда в байтовом объекте встречались встроенные нулевые байты.

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

Примечание

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

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

Примечание

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

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

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

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

sep должен быть объектом 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.

Мягко устарело с версии 3.15: Вместо этого используйте API PyBytesWriter.

PyObject *PyBytes_Repr(PyObject *bytes, int smartquotes)¶

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

Часть Stable ABI.Потокобезопасность: Атомарно.

Обрабатывает управляющие последовательности в строке с обратной косой чертой s. s не должно быть NULL. len должно быть размером s.

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

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

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

PyBytesWriter¶

API PyBytesWriter можно использовать для создания объекта Python bytes.

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

type PyBytesWriter¶

Экземпляр средства записи байтов.

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

Экземпляр должен быть уничтожен с помощью PyBytesWriter_Finish() в случае успеха или PyBytesWriter_Discard() в случае ошибки.

Create, Finish, Discard¶

PyBytesWriter *PyBytesWriter_Create(Py_ssize_t size)¶

Создаёт PyBytesWriter для записи size байт.

Если size больше нуля, выделяет size байт и устанавливает размер writer в size. Вызывающий ответственен за запись size байт с помощью PyBytesWriter_GetData(). Эта функция не выделяет память с запасом.

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

size должен быть положительным или нулевым.

PyObject *PyBytesWriter_Finish(PyBytesWriter *writer)¶

Завершает объект PyBytesWriter, созданный с помощью PyBytesWriter_Create().

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

После вызова экземпляр writer становится недействительным в любом случае. После PyBytesWriter_Finish() никакие API для writer вызывать нельзя.

PyObject *PyBytesWriter_FinishWithSize(PyBytesWriter *writer, Py_ssize_t size)¶: Аналогично PyBytesWriter_Finish(), но изменяет размер writer до size байт перед созданием объекта bytes.

PyObject *PyBytesWriter_FinishWithPointer(PyBytesWriter *writer, void *buf)¶

Аналогично PyBytesWriter_Finish(), но изменяет размер writer с помощью указателя buf перед созданием объекта bytes.

Устанавливает исключение и возвращает NULL, если указатель buf находится за пределами внутреннего буфера.

Псевдокод функции:

Py_ssize_t size = (char*)buf - (char*)PyBytesWriter_GetData(writer);
return PyBytesWriter_FinishWithSize(writer, size);

void PyBytesWriter_Discard(PyBytesWriter *writer)¶

Отменяет объект PyBytesWriter, созданный с помощью PyBytesWriter_Create().

Ничего не делает, если writer равен NULL.

После вызова экземпляр writer становится недействительным. После PyBytesWriter_Discard() никакие API для writer вызывать нельзя.

API высокого уровня¶High-level API

int PyBytesWriter_WriteBytes(PyBytesWriter *writer, const void *bytes, Py_ssize_t size)¶

Увеличивает внутренний буфер writer на size байт, записывает size байт из bytes в конец writer и добавляет size к размеру writer.

Если size равно -1, вызывает strlen(bytes) для получения длины строки.

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

int PyBytesWriter_Format(PyBytesWriter *writer, const char *format, ...)¶

Аналогично PyBytes_FromFormat(), но записывает вывод непосредственно в конец writer. Увеличивает внутренний буфер writer по мере необходимости. Затем добавляет записанный размер к размеру writer.

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

Геттеры¶Getters

Py_ssize_t PyBytesWriter_GetSize(PyBytesWriter *writer)¶

Возвращает размер writer.

Функция не делает недействительными указатели, возвращённые PyBytesWriter_GetData().

Функция не может завершиться с ошибкой.

void *PyBytesWriter_GetData(PyBytesWriter *writer)¶

Возвращает данные writer: начало внутреннего буфера.

Указатель остаётся действительным, пока для writer не будет вызвана функция PyBytesWriter, отличная от PyBytesWriter_GetData() или PyBytesWriter_GetSize().

Функция не может завершиться с ошибкой.

Низкоуровневый API¶Low-level API

int PyBytesWriter_Resize(PyBytesWriter *writer, Py_ssize_t size)¶

Изменяет размер writer на size байт. Может использоваться для увеличения или уменьшения размера writer. Обычно эта функция выделяет память с запасом для обеспечения амортизированной производительности при многократном изменении размера.

Вновь выделенные байты остаются неинициализированными.

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

size должен быть положительным или нулевым.

int PyBytesWriter_Grow(PyBytesWriter *writer, Py_ssize_t grow)¶

Увеличивает размер writer на grow байт от текущего размера. Обычно эта функция выделяет память с запасом для обеспечения амортизированной производительности при многократном изменении размера.

Вновь выделенные байты остаются неинициализированными.

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

size может быть отрицательным для уменьшения writer.

void *PyBytesWriter_GrowAndUpdatePointer(PyBytesWriter *writer, Py_ssize_t size, void *buf)¶

Аналогично PyBytesWriter_Grow(), но также обновляет указатель buf .

Указатель buf перемещается, если внутренний буфер перемещается в памяти. Относительное положение buf внутри внутреннего буфера остаётся неизменным.

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

buf не должен быть NULL.

Псевдокод функции:

Py_ssize_t pos = (char*)buf - (char*)PyBytesWriter_GetData(writer);
if (PyBytesWriter_Grow(writer, size) < 0) {
    return NULL;
}
return (char*)PyBytesWriter_GetData(writer) + pos;