`bytes.md`

223 строк · 20.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.14/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.14/library/exceptions.html#TypeError), если ожидается параметр bytes, а вызываются с параметром, не являющимся bytes.1011#### `type PyBytesObject`1213Этот подтип [`PyObject`](https://python-all.ru/3.14/c-api/structures.html#c.PyObject) представляет объект Python bytes.1415#### `PyTypeObject PyBytes_Type`1617*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*1819Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.14/c-api/type.html#c.PyTypeObject) представляет тип bytes в Python; это тот же объект, что и [`bytes`](https://python-all.ru/3.14/library/stdtypes.html#bytes) в слое Python.2021#### `int PyBytes_Check(PyObject *o)`2223Возвращает true, если объект *o* является объектом bytes или экземпляром подтипа типа bytes. Эта функция всегда завершается успешно.2425#### `int PyBytes_CheckExact(PyObject *o)`2627Возвращает true, если объект *o* является объектом bytes, но не экземпляром подтипа типа bytes. Эта функция всегда завершается успешно.2829#### `PyObject *PyBytes_FromString(const char *v)`3031*Возвращаемое значение: новая ссылка.*3233*Часть [стабильного ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*3435*Потокобезопасность: [атомарно](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-atomic).*3637Возвращает новый объект bytes с копией строки *v* в качестве значения в случае успеха, и `NULL` в случае неудачи. Параметр *v* не должен быть `NULL`; он не будет проверяться.3839#### `PyObject *PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)`4041*Возвращаемое значение: новая ссылка.*4243*Часть [стабильного ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*4445*Потокобезопасность: [атомарно](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-atomic).*4647Возвращает новый объект bytes с копией строки *v* в качестве значения и длины *len* в случае успеха, и `NULL` в случае неудачи. Если *v* равно `NULL`, содержимое объекта bytes не инициализировано.4849#### `PyObject *PyBytes_FromFormat(const char *format, ...)`5051*Возвращаемое значение: новая ссылка.*5253*Часть [стабильного ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*5455*Потокобезопасность: [атомарно](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-atomic).*5657Принимает строку формата в стиле C `printf()`, строку *format* и переменное количество аргументов, вычисляет размер результирующего объекта bytes Python и возвращает объект bytes, в который отформатированы значения. Переменные аргументы должны быть типами C и точно соответствовать символам формата в строке *format*. Допускаются следующие символы формата:5859| Символы формата | Тип | Описание |60| --- | --- | --- |61| `%%` | *н/д* | Буквальный символ %. |62| `%c` | int | Один байт, представленный как C int. |63| `%d` | int | Эквивалентно `printf("%d")`. [\[1\]](https://python-all.ru/3.14/c-api/bytes.html#id9) |64| `%u` | unsigned int | Эквивалентно `printf("%u")`. [\[1\]](https://python-all.ru/3.14/c-api/bytes.html#id9) |65| `%ld` | long | Эквивалентно `printf("%ld")`. [\[1\]](https://python-all.ru/3.14/c-api/bytes.html#id9) |66| `%lu` | unsigned long | Эквивалентно `printf("%lu")`. [\[1\]](https://python-all.ru/3.14/c-api/bytes.html#id9) |67| `%zd` | [`Py_ssize_t`](https://python-all.ru/3.14/c-api/intro.html#c.Py_ssize_t) | Эквивалентно `printf("%zd")`. [\[1\]](https://python-all.ru/3.14/c-api/bytes.html#id9) |68| `%zu` | size\_t | Эквивалентно `printf("%zu")`. [\[1\]](https://python-all.ru/3.14/c-api/bytes.html#id9) |69| `%i` | int | Эквивалентно `printf("%i")`. [\[1\]](https://python-all.ru/3.14/c-api/bytes.html#id9) |70| `%x` | int | Эквивалентно `printf("%x")`. [\[1\]](https://python-all.ru/3.14/c-api/bytes.html#id9) |71| `%s` | const char\* | Нуль-терминированный массив символов C. |72| `%p` | const void\* | Шестнадцатеричное представление указателя C. В основном эквивалентно `printf("%p")`, за исключением того, что гарантированно начинается с литерала `0x` независимо от того, что возвращает `printf` на данной платформе. |7374Нераспознанный символ формата приводит к тому, что вся оставшаяся строка формата копируется как есть в результирующий объект, а все лишние аргументы отбрасываются.7576\[1\]7778([1](https://python-all.ru/3.14/c-api/bytes.html#id1),[2](https://python-all.ru/3.14/c-api/bytes.html#id2),[3](https://python-all.ru/3.14/c-api/bytes.html#id3),[4](https://python-all.ru/3.14/c-api/bytes.html#id4),[5](https://python-all.ru/3.14/c-api/bytes.html#id5),[6](https://python-all.ru/3.14/c-api/bytes.html#id6),[7](https://python-all.ru/3.14/c-api/bytes.html#id7),[8](https://python-all.ru/3.14/c-api/bytes.html#id8))7980Для целочисленных спецификаторов (d, u, ld, lu, zd, zu, i, x): флаг преобразования '0' действует, даже если задана точность.8182#### `PyObject *PyBytes_FromFormatV(const char *format, va_list vargs)`8384*Возвращаемое значение: новая ссылка.*8586*Часть [стабильного ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*8788*Потокобезопасность: [атомарно](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-atomic).*8990Идентично [`PyBytes_FromFormat()`](https://python-all.ru/3.14/c-api/bytes.html#c.PyBytes_FromFormat), за исключением того, что принимает ровно два аргумента.9192#### `PyObject *PyBytes_FromObject(PyObject *o)`9394*Возвращаемое значение: новая ссылка.*9596*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*9798*Потокобезопасность: [Безопасно для одновременного использования на одном объекте](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-shared).*99100Возвращает байтовое представление объекта *o*, реализующего протокол буфера.101102> **Примечание**103>104> Если объект реализует протокол буфера, то буфер не должен изменяться во время создания байтового объекта.105106#### `Py_ssize_t PyBytes_Size(PyObject *o)`107108*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*109110*Потокобезопасность: [Атомарно](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-atomic).*111112Возвращает длину байтов в байтовом объекте *o*.113114#### `Py_ssize_t PyBytes_GET_SIZE(PyObject *o)`115116*Потокобезопасность: [атомарно](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-atomic).*117118Аналогично [`PyBytes_Size()`](https://python-all.ru/3.14/c-api/bytes.html#c.PyBytes_Size), но без проверки ошибок.119120#### `char *PyBytes_AsString(PyObject *o)`121122*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*123124*Потокобезопасность: [Безопасен для вызова из нескольких потоков только с внешней синхронизацией](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-compatible).*125126Возвращает указатель на содержимое *o*. Указатель ссылается на внутренний буфер объекта *o*, который состоит из `len(o) + 1` байтов. Последний байт в буфере всегда нулевой, независимо от наличия других нулевых байтов. Данные нельзя изменять никаким образом, за исключением случая, когда объект только что был создан с помощью `PyBytes_FromStringAndSize(NULL, size)`. Его нельзя освобождать. Если *o* вообще не является байтовым объектом, [`PyBytes_AsString()`](https://python-all.ru/3.14/c-api/bytes.html#c.PyBytes_AsString) возвращает `NULL` и возбуждает [`TypeError`](https://python-all.ru/3.14/library/exceptions.html#TypeError).127128#### `char *PyBytes_AS_STRING(PyObject *string)`129130*Потокобезопасность: [Безопасно вызывать из нескольких потоков только с внешней синхронизацией](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-compatible).*131132Аналогично [`PyBytes_AsString()`](https://python-all.ru/3.14/c-api/bytes.html#c.PyBytes_AsString), но без проверки ошибок.133134#### `int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)`135136*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*137138*Потокобезопасность: [Безопасен для вызова из нескольких потоков только с внешней синхронизацией](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-compatible).*139140Возвращает содержимое объекта *obj*, завершающееся нулевым байтом, через выходные переменные *buffer* и *length*. В случае успеха возвращает `0`.141142Если *length* равно `NULL`, байтовый объект не может содержать встроенные нулевые байты; если содержит, функция возвращает `-1` и возбуждается [`ValueError`](https://python-all.ru/3.14/library/exceptions.html#ValueError).143144Буфер ссылается на внутренний буфер *obj*, который содержит дополнительный нулевой байт в конце (не учитывается в *length*). Данные нельзя изменять никаким образом, за исключением случая, когда объект только что был создан с помощью `PyBytes_FromStringAndSize(NULL, size)`. Его нельзя освобождать. Если *obj* вообще не является байтовым объектом, [`PyBytes_AsStringAndSize()`](https://python-all.ru/3.14/c-api/bytes.html#c.PyBytes_AsStringAndSize) возвращает `-1` и возбуждает [`TypeError`](https://python-all.ru/3.14/library/exceptions.html#TypeError).145146Изменено в версии 3.5: Ранее, [`TypeError`](https://python-all.ru/3.14/library/exceptions.html#TypeError) возбуждалось, когда в байтовом объекте встречались встроенные нулевые байты.147148#### `void PyBytes_Concat(PyObject **bytes, PyObject *newpart)`149150*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*151152*Потокобезопасность: [Безопасно для одновременного использования на одном объекте](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-shared).*153154Создаёт новый байтовый объект в *\*bytes*, содержащий содержимое *newpart*, добавленное к *bytes*; вызывающий получит новую ссылку. Ссылка на старое значение *bytes* будет «[украдена](https://python-all.ru/3.14/glossary.html#term-steal)». Если новый объект не может быть создан, старая ссылка на *bytes* всё равно будет «украдена», значение *\*bytes* будет установлено в `NULL`, и будет установлено соответствующее исключение.155156> **Примечание**157>158> Если *newpart* реализует протокол буфера, то буфер не должен изменяться во время создания нового байтового объекта.159160#### `void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)`161162*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*163164*Потокобезопасность: [Безопасно для одновременного использования на одном объекте](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-shared).*165166Создаёт новый байтовый объект в *\*bytes*, содержащий содержимое *newpart*, добавленное к *bytes*. Эта версия освобождает [сильную ссылку](https://python-all.ru/3.14/glossary.html#term-strong-reference) на *newpart* (т.е. уменьшает счётчик ссылок).167168> **Примечание**169>170> Если *newpart* реализует протокол буфера, то буфер не должен изменяться во время создания нового байтового объекта.171172#### `PyObject *PyBytes_Join(PyObject *sep, PyObject *iterable)`173174*Потокобезопасность: [Безопасно для одновременного использования на одном объекте](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-shared).*175176Аналогично `sep.join(iterable)` в Python.177178*sep* должен быть объектом Python [`bytes`](https://python-all.ru/3.14/library/stdtypes.html#bytes). (Обратите внимание, что [`PyUnicode_Join()`](https://python-all.ru/3.14/c-api/unicode.html#c.PyUnicode_Join) принимает разделитель `NULL` и обрабатывает его как пробел, тогда как [`PyBytes_Join()`](https://python-all.ru/3.14/c-api/bytes.html#c.PyBytes_Join) не принимает разделитель `NULL`.)179180*iterable* должен быть итерируемым объектом, порождающим объекты, реализующие [буферный протокол](https://python-all.ru/3.14/c-api/buffer.html#bufferobjects).181182В случае успеха возвращает новый объект [`bytes`](https://python-all.ru/3.14/library/stdtypes.html#bytes). В случае ошибки устанавливает исключение и возвращает `NULL`.183184Добавлено в версии 3.14.185186> **Примечание**187>188> Если объекты *iterable* реализуют буферный протокол, то буферы не должны изменяться во время создания нового объекта bytes.189190#### `int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)`191192*Потокобезопасность: [Можно безопасно вызывать без внешней синхронизации для разных объектов](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-distinct).*193194Изменяет размер объекта bytes. *newsize* – новая длина объекта bytes. Можно считать, что это создание нового объекта bytes и уничтожение старого, только более эффективно. Передайте адрес существующего объекта bytes как lvalue (в него может быть произведена запись) и желаемый новый размер. В случае успеха *\*bytes* содержит изменённый объект bytes и возвращается `0`; адрес в *\*bytes* может отличаться от исходного значения. Если перераспределение не удалось, исходный объект bytes по адресу *\*bytes* освобождается, *\*bytes* устанавливается в `NULL`, устанавливается [`MemoryError`](https://python-all.ru/3.14/library/exceptions.html#MemoryError) и возвращается `-1`.195196#### `PyObject *PyBytes_Repr(PyObject *bytes, int smartquotes)`197198*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*199200*Потокобезопасность: [Атомарно](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-atomic).*201202Возвращает строковое представление *bytes*. Эта функция в настоящее время используется для реализации `bytes.__repr__()` в Python.203204Эта функция не выполняет проверку типа; передача *bytes* в качестве объекта, не являющегося bytes, или `NULL` приводит к неопределённому поведению.205206Если *smartquotes* равно true, представление будет использовать строку в двойных кавычках вместо строки в одинарных кавычках, если в *bytes* присутствуют одинарные кавычки. Например, байтовая строка `'Python'` будет представлена как `b"'Python'"`, когда *smartquotes* равно true, или как `b'\'Python\''`, когда оно равно false.207208В случае успеха эта функция возвращает [сильную ссылку](https://python-all.ru/3.14/glossary.html#term-strong-reference) на объект [`str`](https://python-all.ru/3.14/library/stdtypes.html#str), содержащий представление. В случае ошибки возвращается `NULL` с установленным исключением.209210#### `PyObject *PyBytes_DecodeEscape(const char *s, Py_ssize_t len, const char *errors, Py_ssize_t unicode, const char *recode_encoding)`211212*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*213214*Потокобезопасность: [Атомарно](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-atomic).*215216Обрабатывает управляющие последовательности в строке с обратной косой чертой *s*. *s* не должно быть `NULL`. *len* должно быть размером *s*.217218*errors* должно быть одним из `"strict"`, `"replace"` или `"ignore"`. Если *errors* равно `NULL`, то по умолчанию используется `"strict"`.219220В случае успеха эта функция возвращает [сильную ссылку](https://python-all.ru/3.14/glossary.html#term-strong-reference) на объект Python [`bytes`](https://python-all.ru/3.14/library/stdtypes.html#bytes), содержащий неэкранированную строку. В случае ошибки эта функция возвращает `NULL` с установленным исключением.221222Изменено в версии 3.9: *unicode* и *recode\_encoding* теперь не используются.223