HOWTO · Python

Python 中的缓冲区

了解 Python 缓冲区协议如何通过 memoryview 暴露兼容的字节数据、视图何时与可写存储共享数据,以及自定义类需满足哪些协议支持条件。

本页内容

Python 的缓冲区协议允许兼容对象向程序的其他部分提供面向字节的数据,而无需使用者了解提供者的内部表示。memoryview 是一种常见的使用者:它可以通过视图读取数据;如果提供者允许,也可以修改数据。这样可以避免额外复制,但并不意味着所有操作都不复制,也不保证性能一定提升。是否共享存储取决于提供者以及执行的操作。

Python 缓冲区协议提供什么

缓冲区协议是数据提供者与数据使用者之间的接口,使用者可以通过它操作这些数据。它适用于二进制输入、文件或网络载荷,以及交换连续或结构化数据的库。bytes 和 bytearray 等内置对象提供缓冲区;其他类型也可能提供。Python 的 str 表示文本,不是字节缓冲区,因此在使用面向字节的 API 前,应先按选定的字节编码对其进行编码。

该协议描述的是如何访问现有数据区域,而不是要求每个提供者都向 Python 代码公开一套通用方法。像 memoryview 这样的使用者会请求具有特定属性的视图。提供者可能直接支持这些属性、提供只读视图,或拒绝无法满足的请求。如果视图引用的是提供者的存储,就可能减少复制;将视图转换为另一个对象则会创建副本,例如调用 tobytes()。

使用 memoryview 操作内置缓冲区提供者

可以通过 memoryview(data) 从兼容对象创建视图。按字节访问视图中的元素会返回 0 到 255 之间的整数,切片则会返回另一个视图。视图仍可访问原始存储,因此,对 bytearray 创建的可写视图可以修改该对象。相比之下,基于不可变 bytes 创建的视图是只读的。下面这个独立示例演示如何通过可写视图进行索引、切片和等长更新。

运行此示例:

本节中的代码以及显示的标签或输出仍为英文。

data = bytearray(b'Python Buffer Interface')
view = memoryview(data)

print(view[0])
print(view[0:6].tobytes())
view[0:6] = b'Java  '
print(data.decode('ascii'))
80
b'Python'
Java   Buffer Interface

切片赋值会将六个字节写入已有的六个位置;通过视图进行切片赋值时,必须满足视图的形状和大小限制。需要修改数据时,请使用可写的提供者。如果任务只需要独立的字节序列,可以用 tobytes() 显式复制视图,并将这次内存分配考虑在内。

在自定义类中实现缓冲区协议

自定义类是否受支持取决于 Python 运行时。在支持 Python 层级 __buffer__ 钩子的运行时中,类可以定义 __buffer__(self, flags),返回合适的缓冲区导出者,通常是一个指向类所拥有存储的视图。该方法必须遵守请求的标志,并确保底层存储在使用者所需的整个期间内保持有效。依赖此钩子前,请查阅目标运行时的文档;本文不假定某个特定的版本边界。

定义 __getitem__ 和 __len__ 可以让对象表现得像序列,但仅有这些方法并不能让它成为缓冲区提供者。同样,返回字节的普通方法也不会自动成为缓冲区接口;只有当运行时的缓冲区协议识别该类的实现时才算支持。如果运行时不支持,或类无法满足使用者对布局和可变性的要求,可以提供文档齐全的转换方法,或改用 bytearray 这样的内置缓冲区提供者。

检查可变性和兼容性

将视图传递给其他 API 前,请确认对方是否需要可写数据、特定的字节布局或特定格式。bytes 提供不可变数据,而 bytearray 是可变的;如果使用者要求写入,就可能拒绝只读视图。视图也不保证后续每项操作都不会复制数据。memoryview 会保留对其导出者的引用,因此无需仅为了维持其生命周期而另存一份引用。不过,活动中的视图可能会阻止与已导出缓冲区冲突的提供者操作,例如调整 bytearray 的大小;尝试此类操作前,请先释放视图。

旧的内置函数 buffer() 属于 Python 2,不能用于在 Python 3 中获取视图。请对兼容的提供者使用 memoryview(),并确认你所部署的运行时支持自定义 __buffer__。这样可以避免把序列方法、文本值或依赖特定运行时的钩子误认为通用的缓冲区支持。