位元組物件 (Bytes Objects)

这些函数在期望附带一个字节串形参但却附带了一个非字节串形参被调用时会引发 TypeError。

type PyBytesObject

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

PyTypeObject PyBytes_Type

属于 稳定 ABI.

PyTypeObject 的实例代表一个 Python 字节类型，在 Python 层面它与 bytes 是相同的对象。

int PyBytes_Check(PyObject *o)

如果对象 o 是一个 bytes 对象或者 bytes 类型的子类型的实例则返回真值。 此函数总是会成功执行。

int PyBytes_CheckExact(PyObject *o)

如果对象 o 是一个 bytes 对象但不是 bytes 类型的子类型的实例则返回真值。 此函数总是会成功执行。

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 语言的整型
%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 的输出是什么。

无法识别的格式字符会导致将格式字符串的其余所有内容原样复制到结果对象，并丢弃所有多余的参数。

[1] (1,2,3,4,5,6,7,8)

对于整数说明符（d，u，ld，lu，zd，zu，i，x）：当给出精度时，0 转换标志是有效的。

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 以空值作为结束的内容。 成功时返回 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 的 strong reference (即递减其引用计数)。

int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)

改变字节串大小的一种方式，即使其为“不可变对象”。 此方式仅用于创建全新的字节串对象；如果字节串在代码的其他部分已知则不可使用此方式。 如果输入字节串对象的引用计数不为一则调用此函数将报错。 传入一个现有字节串对象的地址作为 lvalue（它可能会被写入），并传入希望的新大小。 当成功时，*bytes 将存放改变大小后的字节串对象并返回 0；*bytes 中的地址可能与其输入值不同。 如果重新分配失败，则 *bytes 上的原字节串对象将被撤销分配，*bytes 会被设为 NULL，同时设置 MemoryError 并返回 -1。