`bytes.md`

115 строк · 12.2 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.9/c-api/bytes.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты bytes89Эти функции возбуждают [`TypeError`](https://python-all.ru/3.9/library/exceptions.html#TypeError), если ожидается параметр bytes, а вызываются с параметром, не являющимся bytes.1011**`PyBytesObject`**1213Этот подтип [`PyObject`](https://python-all.ru/3.9/c-api/structures.html#c.PyObject) представляет объект Python bytes.1415**[PyTypeObject](https://python-all.ru/3.9/c-api/type.html#c.PyTypeObject) `PyBytes_Type`**1617Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.9/c-api/type.html#c.PyTypeObject) представляет тип bytes в Python; это тот же объект, что и [`bytes`](https://python-all.ru/3.9/library/stdtypes.html#bytes) в слое Python.1819#### `int PyBytes_Check(PyObject *o)`2021Возвращает true, если объект *o* является объектом bytes или экземпляром подтипа типа bytes. Эта функция всегда завершается успешно.2223#### `int PyBytes_CheckExact(PyObject *o)`2425Возвращает true, если объект *o* является объектом bytes, но не экземпляром подтипа типа bytes. Эта функция всегда завершается успешно.2627#### `PyObject* PyBytes_FromString(const char *v)`2829*Возвращаемое значение: новая ссылка.*3031Возвращает новый объект bytes с копией строки *v* в качестве значения в случае успеха, и `NULL` в случае неудачи. Параметр *v* не должен быть `NULL`; он не будет проверяться.3233#### `PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)`3435*Возвращаемое значение: новая ссылка.*3637Возвращает новый объект bytes с копией строки *v* в качестве значения и длины *len* в случае успеха, и `NULL` в случае неудачи. Если *v* равно `NULL`, содержимое объекта bytes не инициализировано.3839#### `PyObject* PyBytes_FromFormat(const char *format, ...)`4041*Возвращаемое значение: новая ссылка.*4243Принимает строку формата в стиле C `printf()`, строку *format* и переменное количество аргументов, вычисляет размер результирующего объекта bytes Python и возвращает объект bytes, в который отформатированы значения. Переменные аргументы должны быть типами C и точно соответствовать символам формата в строке *format*. Допускаются следующие символы формата:4445| Символы формата | Тип | Описание |46| --- | --- | --- |47| `%%` | *н/д* | Буквальный символ %. |48| `%c` | int | Один байт, представленный как C int. |49| `%d` | int | Эквивалентно `printf("%d")`. [1](https://python-all.ru/3.9/c-api/bytes.html#id9) |50| `%u` | unsigned int | Эквивалентно `printf("%u")`. [1](https://python-all.ru/3.9/c-api/bytes.html#id9) |51| `%ld` | long | Эквивалентно `printf("%ld")`. [1](https://python-all.ru/3.9/c-api/bytes.html#id9) |52| `%lu` | unsigned long | Эквивалентно `printf("%lu")`. [1](https://python-all.ru/3.9/c-api/bytes.html#id9) |53| `%zd` | [`Py_ssize_t`](https://python-all.ru/3.9/c-api/intro.html#c.Py_ssize_t) | Эквивалентно `printf("%zd")`. [1](https://python-all.ru/3.9/c-api/bytes.html#id9) |54| `%zu` | size\_t | Эквивалентно `printf("%zu")`. [1](https://python-all.ru/3.9/c-api/bytes.html#id9) |55| `%i` | int | Эквивалентно `printf("%i")`. [1](https://python-all.ru/3.9/c-api/bytes.html#id9) |56| `%x` | int | Эквивалентно `printf("%x")`. [1](https://python-all.ru/3.9/c-api/bytes.html#id9) |57| `%s` | const char\* | Нуль-терминированный массив символов C. |58| `%p` | const void\* | Шестнадцатеричное представление указателя C. В основном эквивалентно `printf("%p")`, за исключением того, что гарантированно начинается с литерала `0x` независимо от того, что возвращает `printf` на данной платформе. |5960Нераспознанный символ формата приводит к тому, что вся оставшаяся строка формата копируется как есть в результирующий объект, а все лишние аргументы отбрасываются.6162**1([1](https://python-all.ru/3.9/c-api/bytes.html#id1),[2](https://python-all.ru/3.9/c-api/bytes.html#id2),[3](https://python-all.ru/3.9/c-api/bytes.html#id3),[4](https://python-all.ru/3.9/c-api/bytes.html#id4),[5](https://python-all.ru/3.9/c-api/bytes.html#id5),[6](https://python-all.ru/3.9/c-api/bytes.html#id6),[7](https://python-all.ru/3.9/c-api/bytes.html#id7),[8](https://python-all.ru/3.9/c-api/bytes.html#id8))**6364Для целочисленных спецификаторов (d, u, ld, lu, zd, zu, i, x): флаг преобразования '0' действует, даже если задана точность.6566#### `PyObject* PyBytes_FromFormatV(const char *format, va_list vargs)`6768*Возвращаемое значение: новая ссылка.*6970Идентично [`PyBytes_FromFormat()`](https://python-all.ru/3.9/c-api/bytes.html#c.PyBytes_FromFormat), за исключением того, что принимает ровно два аргумента.7172#### `PyObject* PyBytes_FromObject(PyObject *o)`7374*Возвращаемое значение: новая ссылка.*7576Возвращает байтовое представление объекта *o*, реализующего протокол буфера.7778#### `Py_ssize_t PyBytes_Size(PyObject *o)`7980Возвращает длину байтов в байтовом объекте *o*.8182#### `Py_ssize_t PyBytes_GET_SIZE(PyObject *o)`8384Макроформа [`PyBytes_Size()`](https://python-all.ru/3.9/c-api/bytes.html#c.PyBytes_Size) без проверки ошибок.8586#### `char* PyBytes_AsString(PyObject *o)`8788Возвращает указатель на содержимое *o*. Указатель ссылается на внутренний буфер объекта *o*, который состоит из `len(o) + 1` байтов. Последний байт в буфере всегда нулевой, независимо от наличия других нулевых байтов. Данные нельзя изменять никаким образом, за исключением случая, когда объект только что был создан с помощью `PyBytes_FromStringAndSize(NULL, size)`. Его нельзя освобождать. Если *o* вообще не является байтовым объектом, [`PyBytes_AsString()`](https://python-all.ru/3.9/c-api/bytes.html#c.PyBytes_AsString) возвращает `NULL` и возбуждает [`TypeError`](https://python-all.ru/3.9/library/exceptions.html#TypeError).8990#### `char* PyBytes_AS_STRING(PyObject *string)`9192Макроформа [`PyBytes_AsString()`](https://python-all.ru/3.9/c-api/bytes.html#c.PyBytes_AsString) без проверки ошибок.9394#### `int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)`9596Возвращает содержимое объекта *obj*, завершённое нулевым символом, через выходные переменные *buffer* и *length*.9798Если *length* равно `NULL`, байтовый объект не может содержать встроенные нулевые байты; если содержит, функция возвращает `-1` и возбуждается [`ValueError`](https://python-all.ru/3.9/library/exceptions.html#ValueError).99100Буфер ссылается на внутренний буфер *obj*, который содержит дополнительный нулевой байт в конце (не учитывается в *length*). Данные нельзя изменять никаким образом, за исключением случая, когда объект только что был создан с помощью `PyBytes_FromStringAndSize(NULL, size)`. Его нельзя освобождать. Если *obj* вообще не является байтовым объектом, [`PyBytes_AsStringAndSize()`](https://python-all.ru/3.9/c-api/bytes.html#c.PyBytes_AsStringAndSize) возвращает `-1` и возбуждает [`TypeError`](https://python-all.ru/3.9/library/exceptions.html#TypeError).101102Изменено в версии 3.5: Ранее, [`TypeError`](https://python-all.ru/3.9/library/exceptions.html#TypeError) возбуждалось, когда в байтовом объекте встречались встроенные нулевые байты.103104#### `void PyBytes_Concat(PyObject **bytes, PyObject *newpart)`105106Создаёт новый байтовый объект в *\*bytes*, содержащий содержимое *newpart*, добавленное к *bytes*; вызывающий получает новую ссылку. Ссылка на старое значение *bytes* будет украдена. Если новый объект невозможно создать, старая ссылка на *bytes* всё равно будет отброшена, а значение *\*bytes* будет установлено в `NULL`; будет установлено соответствующее исключение.107108#### `void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)`109110Создаёт новый объект bytes в *\*bytes*, содержащий содержимое *newpart*, добавленное к *bytes*. Эта версия уменьшает счётчик ссылок *newpart*.111112#### `int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)`113114Способ изменить размер байтового объекта, несмотря на то что он «неизменяем». Используйте это только для создания совершенно нового байтового объекта; не используйте, если bytes уже может быть известен в других частях кода. Вызов этой функции является ошибкой, если счётчик ссылок на входной байтовый объект не равен единице. Передайте адрес существующего байтового объекта как lvalue (в него может производиться запись) и желаемый новый размер. В случае успеха *\*bytes* содержит изменённый байтовый объект и возвращается `0`; адрес в *\*bytes* может отличаться от исходного. Если перераспределение не удалось, исходный байтовый объект по адресу *\*bytes* освобождается, *\*bytes* устанавливается в `NULL`, устанавливается [`MemoryError`](https://python-all.ru/3.9/library/exceptions.html#MemoryError) и возвращается `-1`.115