Bytes 对象

当这些函数需要 bytes 参数但以非 bytes 参数调用时，它们会引发 TypeError。

type PyBytesObject

此 PyObject 的子类型表示一个 Python bytes 对象。

PyTypeObject PyBytes_Type
作为 稳定 ABI 的一部分。

此 PyTypeObject 实例表示 Python bytes 类型；它与 Python 层中的 bytes 对象相同。

int PyBytes_Check(PyObject *o)

如果对象 o 是一个 bytes 对象或 bytes 类型的子类型的实例，则返回 true。此函数始终成功。

int PyBytes_CheckExact(PyObject *o)

如果对象 o 是一个 bytes 对象，但不是 bytes 类型的子类型的实例，则返回 true。此函数始终成功。

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 的一部分。

接受 C printf() 风格的 format 字符串和可变数量的参数，计算结果 Python bytes 对象的大小，并返回一个将值格式化到其中的 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*

一个以 null 结尾的 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 中 bytes 的长度。

Py_ssize_t PyBytes_GET_SIZE(PyObject *o)

类似于 PyBytes_Size()，但没有错误检查。

char *PyBytes_AsString(PyObject *o)
作为 稳定 ABI 的一部分。

返回指向 o 内容的指针。该指针指向 o 的内部缓冲区，该缓冲区由 len(o) + 1 个字节组成。缓冲区中的最后一个字节始终为 null，无论是否存在其他 null 字节。数据不得以任何方式修改，除非该对象是使用 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 的一部分。

通过输出变量 buffer 和 length 返回对象 obj 的以 null 结尾的内容。成功时返回 0。

如果 length 为 NULL，则 bytes 对象可能不包含嵌入的 null 字节；如果包含，则函数返回 -1 并引发 ValueError。

缓冲区指向 obj 的内部缓冲区，其中末尾包含一个额外的 null 字节（未计入 length）。数据不得以任何方式修改，除非该对象是使用 PyBytes_FromStringAndSize(NULL, size) 刚刚创建的。它不得被释放。如果 obj 根本不是 bytes 对象，PyBytes_AsStringAndSize() 返回 -1 并引发 TypeError。

3.5 版本中有所改变: 之前，当 bytes 对象中遇到嵌入的 null 字节时会引发 TypeError。

void PyBytes_Concat(PyObject **bytes, PyObject *newpart)
作为 稳定 ABI 的一部分。

在 *bytes 中创建一个新的 bytes 对象，其中包含 newpart 的内容追加到 bytes 之后；调用者将拥有新的引用。对 bytes 旧值的引用将被盗用。如果无法创建新对象，对 bytes 的旧引用仍将被丢弃，并且 *bytes 的值将设置为 NULL；将设置适当的异常。

void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
作为 稳定 ABI 的一部分。

在 *bytes 中创建一个新的 bytes 对象，其中包含 newpart 的内容追加到 bytes 之后。此版本释放对 newpart 的 强引用（即减少其引用计数）。

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

类似于 Python 中的 sep.join(iterable)。

sep 必须是 Python bytes 对象。（请注意，PyUnicode_Join() 接受 NULL 分隔符并将其视为一个空格，而 PyBytes_Join() 不接受 NULL 分隔符。）

iterable 必须是一个可迭代对象，产生实现 缓冲区协议 的对象。

成功时，返回一个新的 bytes 对象。出错时，设置一个异常并返回 NULL。

在 3.14 版本加入。

int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)

调整 bytes 对象的大小。newsize 将是 bytes 对象的新长度。您可以将其视为创建一个新的 bytes 对象并销毁旧的，只是更有效。将现有 bytes 对象的地址作为左值传递（它可以被写入），以及所需的新大小。成功时，*bytes 持有调整大小后的 bytes 对象，并返回 0；*bytes 中的地址可能与其输入值不同。如果重新分配失败，*bytes 处的原始 bytes 对象将被释放，*bytes 将设置为 NULL，设置 MemoryError，并返回 -1。