> **Источник:** https://python-all.ru/3.4/c-api/bytes.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# Объекты bytes

Эти функции возбуждают [`TypeError`](https://python-all.ru/3.4/library/exceptions.html#TypeError), когда ожидают параметр bytes, а вызываются с параметром, не являющимся bytes.

**`PyBytesObject`**

Этот подтип [`PyObject`](https://python-all.ru/3.4/c-api/structures.html#c.PyObject) представляет объект bytes Python.

**[PyTypeObject](https://python-all.ru/3.4/c-api/type.html#c.PyTypeObject) `PyBytes_Type`**

Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.4/c-api/type.html#c.PyTypeObject) представляет тип bytes Python; он является тем же объектом, что и [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes) на уровне Python.

#### `int PyBytes_Check(PyObject *o)`

Возвращает истину, если объект *o* является объектом bytes или экземпляром подтипа типа bytes.

#### `int PyBytes_CheckExact(PyObject *o)`

Возвращает истину, если объект *o* является объектом bytes, но не экземпляром подтипа типа bytes.

#### `PyObject* PyBytes_FromString(const char *v)`

Возвращает новый объект bytes с копией строки *v* в качестве значения в случае успеха и *NULL* в случае ошибки. Параметр *v* не должен быть *NULL*; он не будет проверяться.

#### `PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)`

Возвращает новый объект bytes с копией строки *v* в качестве значения и длины *len* при успехе, и *NULL* при ошибке. Если *v* равно *NULL*, содержимое объекта bytes не инициализировано.

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

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

| Символы формата | Тип | Описание |
| --- | --- | --- |
| `%%` | *н/д* | Буквальный символ %. |
| `%c` | int | Один байт, представленный как C int. |
| `%d` | int | Полностью эквивалентно `printf("%d")`. |
| `%u` | unsigned int | Полностью эквивалентно `printf("%u")`. |
| `%ld` | long | Полностью эквивалентно `printf("%ld")`. |
| `%lu` | unsigned long | Полностью эквивалентно `printf("%lu")`. |
| `%zd` | Py\_ssize\_t | Полностью эквивалентно `printf("%zd")`. |
| `%zu` | size\_t | Полностью эквивалентно `printf("%zu")`. |
| `%i` | int | Полностью эквивалентно `printf("%i")`. |
| `%x` | int | Полностью эквивалентно `printf("%x")`. |
| `%s` | char\* | Нуль-терминированный массив символов C. |
| `%p` | void\* | Шестнадцатеричное представление указателя C. В основном эквивалентно `printf("%p")` за исключением того, что гарантированно начинается с литерала `0x` независимо от того, что выдает `printf` на данной платформе. |

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

#### `PyObject* PyBytes_FromFormatV(const char *format, va_list vargs)`

Идентична [`PyBytes_FromFormat()`](https://python-all.ru/3.4/c-api/bytes.html#c.PyBytes_FromFormat) за исключением того, что принимает ровно два аргумента.

#### `PyObject* PyBytes_FromObject(PyObject *o)`

Возвращает байтовое представление объекта *o*, реализующего протокол буфера.

#### `Py_ssize_t PyBytes_Size(PyObject *o)`

Возвращает длину байтов в байтовом объекте *o*.

#### `Py_ssize_t PyBytes_GET_SIZE(PyObject *o)`

Макрос, аналогичный [`PyBytes_Size()`](https://python-all.ru/3.4/c-api/bytes.html#c.PyBytes_Size), но без проверки ошибок.

#### `char* PyBytes_AsString(PyObject *o)`

Возвращает указатель на содержимое *o*. Указатель ссылается на внутренний буфер *o*, который состоит из `len(o) + 1` байт. Последний байт в буфере всегда равен нулю, независимо от того, есть ли в нём другие нулевые байты. Данные нельзя изменять никаким образом, за исключением случая, когда объект только что был создан с помощью `PyBytes_FromStringAndSize(NULL, size)`. Буфер нельзя освобождать. Если *o* вовсе не является объектом bytes, [`PyBytes_AsString()`](https://python-all.ru/3.4/c-api/bytes.html#c.PyBytes_AsString) возвращает *NULL* и возбуждает [`TypeError`](https://python-all.ru/3.4/library/exceptions.html#TypeError).

#### `char* PyBytes_AS_STRING(PyObject *string)`

Макрос, аналогичный [`PyBytes_AsString()`](https://python-all.ru/3.4/c-api/bytes.html#c.PyBytes_AsString), но без проверки ошибок.

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

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

Если *length* равен *NULL*, объект bytes не может содержать встроенных нулевых байт; если же содержит, функция возвращает `-1` и возбуждается [`TypeError`](https://python-all.ru/3.4/library/exceptions.html#TypeError).

Буфер ссылается на внутренний буфер объекта *obj*, который включает дополнительный нулевой байт в конце (не учитываемый в *length*). Данные нельзя изменять никаким образом, за исключением случая, когда объект только что был создан с помощью `PyBytes_FromStringAndSize(NULL, size)`. Буфер нельзя освобождать. Если *obj* вовсе не является объектом bytes, [`PyBytes_AsStringAndSize()`](https://python-all.ru/3.4/c-api/bytes.html#c.PyBytes_AsStringAndSize) возвращает `-1` и возбуждает [`TypeError`](https://python-all.ru/3.4/library/exceptions.html#TypeError).

#### `void PyBytes_Concat(PyObject **bytes, PyObject *newpart)`

Создаёт новый объект bytes в *\*bytes*, содержащий содержимое *newpart*, добавленное к *bytes*; вызывающий становится владельцем новой ссылки. Ссылка на старое значение *bytes* будет украдена. Если новый объект не может быть создан, старая ссылка на *bytes* всё равно будет отброшена, а значение *\*bytes* будет установлено в *NULL*; будет установлено соответствующее исключение.

#### `void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)`

Создаёт новый объект bytes в *\*bytes*, содержащий содержимое *newpart*, добавленное к *bytes*. Эта версия уменьшает счётчик ссылок *newpart*.

#### `int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)`

Способ изменить размер объекта bytes, несмотря на то, что он «неизменяемый». Используйте это только для создания нового объекта bytes; не используйте, если объект bytes уже может быть известен в других частях кода. Вызов этой функции является ошибкой, если счётчик ссылок на входной объект bytes не равен единице. Передайте адрес существующего объекта bytes как lvalue (в него может быть произведена запись) и желаемый новый размер. В случае успеха *\*bytes* содержит изменённый объект bytes и возвращается `0`; адрес в *\*bytes* может отличаться от входного значения. Если перераспределение памяти не удаётся, исходный объект bytes по адресу *\*bytes* освобождается, *\*bytes* устанавливается в *NULL*, устанавливается исключение памяти, и возвращается `-1`.