字节对象

这些函数在期望字节参数但调用时传递非字节参数时会引发 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 个字节。缓冲区中的最后一个字节始终为 null，无论是否存在其他 null 字节。除非对象是使用 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，则字节对象可能不包含嵌入的 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中创建一个新的字节对象，其中包含newpart的内容附加到bytes；调用者将拥有新的引用。对bytes旧值的引用将被窃取。如果无法创建新对象，对bytes的旧引用将仍然被丢弃，*bytes的值将被设置为NULL；将设置相应的异常。

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

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

int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)

一种即使字节对象是“不可变的”也可以调整其大小的方法。仅将其用于构建全新的字节对象；如果字节可能在代码的其他部分已知，请勿使用它。如果输入字节对象的引用计数不是 1，则调用此函数将出错。将现有字节对象的地址作为左值传递（它可以被写入），以及所需的新大小。成功后，*bytes将保存调整大小的字节对象，并返回0；*bytes中的地址可能与其输入值不同。如果重新分配失败，则*bytes处的原始字节对象将被释放，*bytes将被设置为NULL，MemoryError将被设置，并返回-1。