字节对象

当期望一个字节参数但调用时使用了非字节参数时，这些函数会引发 TypeError。

type PyBytesObject

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

PyTypeObject PyBytes_Type
属于 稳定 ABI 的一部分。

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

int PyBytes_Check(PyObject *o)

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

int PyBytes_CheckExact(PyObject *o)

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

PyObject *PyBytes_FromString(const char *v)
返回值：新的引用。属于 稳定 ABI 的一部分。

成功时，返回一个新的字节对象，其值为字符串 v 的副本，失败时返回 NULL。参数 v 不能为 NULL；不会对其进行检查。

PyObject *PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
返回值：新的引用。属于 稳定 ABI 的一部分。

成功时，返回一个新的字节对象，其值为字符串 v 的副本，长度为 len，失败时返回 NULL。如果 v 为 NULL，则字节对象的内容未初始化。

PyObject *PyBytes_FromFormat(const char *format, ...)
返回值：新的引用。属于 稳定 ABI 的一部分。

接受一个 C printf() 样式的 format 字符串和可变数量的参数，计算生成的 Python 字节对象的大小，并返回一个字节对象，其中包含格式化后的值。可变参数必须是 C 类型，并且必须与 format 字符串中的格式字符完全对应。允许使用以下格式字符

格式字符

类型

注释

%%

n/a

字面量 % 字符。

%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)
返回值：新的引用。属于 稳定 ABI 的一部分。

返回实现缓冲区协议的对象 o 的字节表示形式。

Py_ssize_t PyBytes_Size(PyObject *o)
属于 稳定 ABI 的一部分。

返回字节对象 o 中字节的长度。

Py_ssize_t PyBytes_GET_SIZE(PyObject *o)

与 PyBytes_Size() 类似，但不进行错误检查。

char *PyBytes_AsString(PyObject *o)
属于 稳定 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)
属于 稳定 ABI 的一部分。

通过输出变量 buffer 和 length 返回对象 obj 的以 null 结尾的内容。成功时返回 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)
属于 稳定 ABI 的一部分。

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

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

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

int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)

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