Python `__array_interface__`：与 NumPy 数组协议的交互

好的，各位观众，欢迎来到今天的“Python 数组协议揭秘”特别节目！今天咱们要聊的是一个有点儿神秘，但又非常实用的东西：Python 的 __array_interface__。 别害怕，虽然名字听起来像是外星科技，但其实它就是个“翻译器”，能让你的自定义数据结构和 NumPy 数组愉快地玩耍。

为啥要了解 __array_interface__？

想象一下，你辛辛苦苦写了一个超酷的自定义数据结构，用来存储图像、音频，或者别的什么炫酷的数据。但是，你想用 NumPy 强大的数组操作功能，比如切片、广播、线性代数等等，来处理这些数据，怎么办？难道要手动把数据复制到 NumPy 数组里？太麻烦了！

__array_interface__ 就是来解决这个问题的。它定义了一套标准，让你的自定义数据结构“告诉” NumPy 自己的数据是怎么组织的，NumPy 就能直接操作你的数据，而不需要复制。 听起来是不是很棒？

__array_interface__ 的核心：一个字典

__array_interface__ 本身就是一个 Python 字典。这个字典包含了一些关键的信息，NumPy 会根据这些信息来理解你的数据。 让我们来看看这个字典里都有哪些重要的键：

• version: 必须是整数 3。告诉 NumPy 你用的是哪个版本的协议。

• shape: 一个元组，表示数组的形状。例如，(3, 4) 表示一个 3 行 4 列的数组。

• typestr: 一个字符串，描述数组中元素的类型。这个字符串遵循 NumPy 的类型代码规范。例如，'<i4' 表示小端序的 32 位整数，'|f8' 表示本地字节序的 64 位浮点数。

• data: 一个元组 (address, readonly)。address 是一个整数，表示数据在内存中的起始地址。readonly 是一个布尔值，表示数据是否只读。

• strides (可选): 一个元组，表示数组在内存中的步长。步长是指从一个元素到下一个元素需要跳过的字节数。如果数组是 C 风格连续的，可以省略这个键。

• descr (可选): 一个列表，描述数组中每个字段的类型和偏移量。用于结构化数组。

• names (可选): 一个元组，包含字段的名字。

• offsets (可选): 一个元组，包含字段的偏移量。

• title (可选): 一个字符串，包含数组的标题。

• flags (可选): 一个整数，表示数组的标志。

一个简单的例子：我的自定义数组

让我们来创建一个简单的自定义数组类，并实现 __array_interface__。

import numpy as np

class MyArray:
    def __init__(self, data):
        self.data = data
        self.shape = (len(data),)
        self.dtype = np.dtype('i4') # 假设数据是 32 位整数

    @property
    def __array_interface__(self):
        return {
            'version': 3,
            'shape': self.shape,
            'typestr': self.dtype.str,
            'data': (self.data.__array_interface__['data'][0], False), # 获取底层数据的地址
            'strides': None, # 连续数组，可以省略
        }

# 创建一个 MyArray 对象
my_array = MyArray(np.arange(10))

# 现在，我们可以像使用 NumPy 数组一样使用 my_array 了！
print(np.sum(my_array))  # 输出：45
print(my_array[2:5])   # 输出：[2 3 4]

在这个例子中，MyArray 类包装了一个 Python 列表 data。__array_interface__ 属性返回一个字典，告诉 NumPy 我们的数据是一个一维的 32 位整数数组，并且数据存储在 data 列表的底层 NumPy array 中。

详细解说：每个键的作用

让我们更深入地了解每个键的作用：

• version: 永远是 3。这是协议的版本号，将来可能会有更新的版本，但目前都是 3。

• shape: 这个元组定义了数组的形状。对于图像来说，可能是 (height, width, channels)；对于音频来说，可能是 (samples,) 或 (channels, samples)。

• typestr: 这是最关键的部分之一。它告诉 NumPy 数组中元素的类型。NumPy 定义了一套类型代码，用于表示不同的数据类型。

  类型代码	描述
  'b'	布尔型
  'i'	整数型
  'u'	无符号整数型
  'f'	浮点型
  'c'	复数型
  'S'	字节字符串
  'U'	Unicode 字符串
  'V'	void (原始数据)

  在类型代码前面还可以加上一些修饰符：

  • '<': 小端序
  • '>': 大端序
  • '|': 本地字节序

  例如，'<i4' 表示小端序的 32 位整数，'>f8' 表示大端序的 64 位浮点数。

• data: 这个元组告诉 NumPy 数据在内存中的位置。第一个元素是数据的起始地址，第二个元素是一个布尔值，表示数据是否只读。

  获取data的方式需要根据底层数据类型来判断，如果本身就是numpy array，那么直接获取即可。如果本身不是，则需要将其转换成numpy array再获取。

• strides: 步长定义了在内存中如何访问数组的元素。对于一个 C 风格连续的数组，元素是按行存储的，步长就是 (元素大小 * 列数, 元素大小)。对于一个 Fortran 风格连续的数组，元素是按列存储的，步长就是 (元素大小, 元素大小 * 行数)。

  如果数组是连续的，可以省略 strides 键。NumPy 会自动计算步长。

• descr: 用于描述结构化数组。结构化数组是指数组中的每个元素都是一个结构体，包含多个字段。descr 是一个列表，其中每个元素都是一个元组 (字段名, 字段类型, 字段偏移量)。

• names 和 offsets: 这两个键也是用于结构化数组的。names 是一个元组，包含字段的名字。offsets 是一个元组，包含字段的偏移量。

• title: 数组的标题，可以随便写。

• flags: 数组的标志，用于表示数组的一些属性，例如是否可写、是否 C 风格连续、是否 Fortran 风格连续等等。

一个更复杂的例子：图像数据

假设你有一个自定义的图像类，图像数据存储在一个字节数组中。

import numpy as np

class MyImage:
    def __init__(self, width, height, channels, data):
        self.width = width
        self.height = height
        self.channels = channels
        self.data = data # 假设 data 是一个字节数组

    @property
    def __array_interface__(self):
        return {
            'version': 3,
            'shape': (self.height, self.width, self.channels),
            'typestr': '|u1', # 无符号 8 位整数 (字节)
            'data': (self.data.__array_interface__['data'][0], False),
            'strides': (self.width * self.channels, self.channels, 1),
        }

# 创建一个 MyImage 对象 (假设已经加载了图像数据到 byte_data)
width, height, channels = 256, 256, 3
byte_data = np.random.randint(0, 256, size=width * height * channels, dtype=np.uint8).tobytes()
my_image = MyImage(width, height, channels, np.frombuffer(byte_data, dtype=np.uint8).reshape(width*height*channels))

# 现在，我们可以像使用 NumPy 数组一样使用 my_image 了！
image_array = np.array(my_image, copy=False) # 创建一个 NumPy 数组的视图
print(image_array.shape) # 输出：(256, 256, 3)
print(image_array[100, 100, :]) # 输出：[某个像素的 RGB 值]

在这个例子中，我们假设图像数据存储在一个字节数组 data 中。__array_interface__ 告诉 NumPy 我们的数据是一个三维数组，形状是 (height, width, channels)，元素类型是无符号 8 位整数。我们还指定了步长，告诉 NumPy 如何在内存中访问图像的像素。

使用 numpy.asarray

通常情况下，你不需要手动访问 __array_interface__ 字典。NumPy 提供了 numpy.asarray 函数，可以自动检测一个对象是否实现了 __array_interface__，并将其转换为 NumPy 数组。

import numpy as np

# 假设 my_array 是一个实现了 __array_interface__ 的对象
numpy_array = np.asarray(my_array)

# 现在，numpy_array 就是一个 NumPy 数组，包含了 my_array 的数据。

numpy.asarray 函数会尽可能地创建一个视图，而不是复制数据。如果你的数据格式和 NumPy 数组兼容，它会直接返回一个指向你的数据的 NumPy 数组。如果你的数据格式和 NumPy 数组不兼容，它会创建一个新的 NumPy 数组，并将你的数据复制到新的数组中。

__array_struct__ 和 __array_props__

除了 __array_interface__ 之外，还有两个相关的协议：__array_struct__ 和 __array_props__。

• __array_struct__: 这是一个 C 语言的接口，用于在 C 扩展中访问数组数据。它和 __array_interface__ 的作用类似，但是它是为 C 语言设计的。

• __array_props__: 这是一个字典，用于传递一些额外的数组属性，例如单位、比例等等。NumPy 目前还没有完全支持 __array_props__。

注意事项

• 数据所有权: 当你通过 __array_interface__ 将你的数据暴露给 NumPy 时，你需要小心处理数据的所有权问题。NumPy 不会复制你的数据，而是直接使用你的数据。这意味着如果你的数据被修改，NumPy 数组也会被修改。如果你不希望 NumPy 修改你的数据，你需要将 readonly 设置为 True。

• 内存布局: 确保你的数据在内存中的布局和你在 __array_interface__ 中描述的布局一致。如果布局不一致，NumPy 可能会访问到错误的数据，导致程序崩溃或者产生错误的结果。

• 类型一致性: 确保你的数据类型和你在 __array_interface__ 中描述的类型一致。如果类型不一致，NumPy 可能会将你的数据解释为错误的类型，导致程序崩溃或者产生错误的结果。

总结

__array_interface__ 是一个强大的工具，可以让你将自定义数据结构和 NumPy 数组无缝集成。通过实现 __array_interface__，你可以让 NumPy 直接操作你的数据，而不需要复制数据，从而提高程序的性能。

希望今天的讲解对你有所帮助！记住，__array_interface__ 就像一个“翻译器”，让你的数据结构和 NumPy 数组能够愉快地交流。只要你掌握了这门“语言”，就能让你的程序更加高效、更加强大！

进阶思考

1. 实现一个支持切片的自定义数组类: 尝试实现一个自定义数组类，支持像 NumPy 数组一样的切片操作。你需要重写 __getitem__ 方法，并根据切片的范围修改 __array_interface__ 中的 shape 和 data。

2. 结构化数组: 尝试实现一个结构化数组类，其中每个元素包含多个字段。你需要使用 descr、names 和 offsets 键来描述数组的结构。

3. 性能优化: 比较使用 __array_interface__ 和手动复制数据到 NumPy 数组的性能差异。在处理大型数据集时，使用 __array_interface__ 通常可以显著提高性能。

好了，今天的节目就到这里。感谢大家的收看，我们下期再见！