Python中的`__array_finalize__`方法：自定义NumPy数组子类的元数据管理

大家好，今天我们来深入探讨NumPy中一个相对高级但非常重要的特性：__array_finalize__方法。它是构建自定义NumPy数组子类的关键，允许我们管理和传递元数据，确保自定义行为在数组操作中得到保持。

1. NumPy数组子类的必要性

NumPy的ndarray对象功能强大，但有时我们需要在标准数组的基础上添加额外的功能或属性。例如，我们可能需要：

存储单位信息: 创建一个数组来表示长度，并确保单位（例如米、厘米）在数组操作中得到维护。
跟踪历史: 记录数组创建或修改的步骤，用于调试或数据溯源。
实现自定义索引: 定义特殊的索引行为，例如根据特定规则访问数组元素。
集成其他库: 将NumPy数组与现有的数据结构或算法结合使用。

为了实现这些目标，我们可以创建ndarray的子类，从而扩展其功能。

2. __array_finalize__ 的作用

当创建一个新的NumPy数组时（例如，通过切片、视图转换、算术运算等），NumPy会调用新数组的类（如果它是ndarray的子类）的__array_finalize__方法。这个方法提供了一个机会来初始化新数组的实例，特别是从现有数组继承元数据。

__array_finalize__方法的签名如下：

def __array_finalize__(self, obj, dtype=None):
    """
    self:  新创建的数组实例。
    obj:   新数组的来源。  可以是：
           - None: 如果数组是通过标准构造函数创建的 (例如，MyArray(...))。
           - ndarray: 如果数组是从另一个ndarray创建的（例如，切片、视图）。
           - 另一个子类的实例：如果数组是从另一个子类实例创建的。
    dtype: 新数组的数据类型。
    """
    pass

理解obj参数至关重要。 它是连接新数组和原始数组的桥梁，允许我们根据原始数组的类型和属性来初始化新数组。

3. 一个简单的例子：带有单位的数组

让我们创建一个名为UnitArray的子类，它存储数组的单位信息。

import numpy as np

class UnitArray(np.ndarray):
    """
    一个带有单位的NumPy数组子类。
    """
    def __new__(cls, input_array, unit=None, *args, **kwargs):
        # 这是创建实例的主要方法。
        obj = np.asarray(input_array, *args, **kwargs).view(cls)
        obj.unit = unit
        return obj

    def __array_finalize__(self, obj):
        # 这是在创建新实例后调用的方法，用于传递元数据。
        if obj is None: return  # 通过标准构造函数创建
        self.unit = getattr(obj, 'unit', None) # 从obj复制单位

代码解释：

__new__ 方法: 这是创建类实例的静态方法。它接收输入数据（input_array）和单位（unit），并将输入数据转换为NumPy数组，然后将其视为UnitArray的实例。我们还设置了unit属性。
__array_finalize__ 方法: 当创建一个新的UnitArray实例（例如，通过切片）时，这个方法会被调用。它检查obj是否为None（如果是，则表示使用构造函数直接创建的，不需要从其他数组复制属性）。如果obj不是None，它会尝试从obj复制unit属性。 getattr(obj, 'unit', None) 的作用是安全地获取obj的unit属性，如果obj没有unit属性，则返回None。

用法示例：

# 创建一个带有单位的数组
arr = UnitArray([1, 2, 3], unit="meters")
print(arr, arr.unit) # 输出: [1 2 3] meters

# 切片操作
sliced_arr = arr[1:]
print(sliced_arr, sliced_arr.unit) # 输出: [2 3] meters

# 视图转换
view_arr = arr.view(np.ndarray)  # 转换为普通ndarray
print(type(view_arr)) # 输出: <class 'numpy.ndarray'>

#  从ndarray创建UnitArray
new_arr = UnitArray(view_arr, unit="kilometers")
print(new_arr, new_arr.unit) # 输出: [1 2 3] kilometers

4. 更复杂的例子：历史记录数组

让我们创建一个HistoryArray类，它记录数组的创建和修改历史。

import numpy as np

class HistoryArray(np.ndarray):
    """
    一个记录历史的NumPy数组子类。
    """
    def __new__(cls, input_array, history=None, *args, **kwargs):
        obj = np.asarray(input_array, *args, **kwargs).view(cls)
        if history is None:
            obj.history = ["Array created"]
        else:
            obj.history = history[:]  # 创建副本，避免修改原始历史记录
        return obj

    def __array_finalize__(self, obj):
        if obj is None: return
        self.history = getattr(obj, 'history', [])[:] # 复制历史记录

    def __array_wrap__(self, out_arr, context=None):
        #  在任何 ufunc 完成后调用
        if context:
            self.history.append(f"Operation: {context[0].__name__}")
        return np.ndarray.__array_wrap__(self, out_arr, context) # 调用基类方法

    def __setitem__(self, key, value):
        # 覆盖 __setitem__ 以记录修改
        super().__setitem__(key, value)
        self.history.append(f"Item at {key} set to {value}")

代码解释：

__new__ 方法: 创建HistoryArray的实例。如果没有提供历史记录，则创建一个包含 "Array created" 的新历史记录。
__array_finalize__ 方法: 从原始数组复制历史记录。重要的是创建历史记录的副本 ([:])，以防止修改原始数组的历史记录。
__array_wrap__ 方法: 这个方法在NumPy的通用函数（ufuncs，例如 np.add, np.sin）执行后被调用。 context参数包含有关ufunc的信息。我们在这里将操作名称添加到历史记录中。我们还调用基类的__array_wrap__方法，以确保NumPy的正常行为。
__setitem__ 方法: 我们覆盖了__setitem__方法（用于设置数组元素的值）来记录修改操作。

用法示例：

# 创建一个 HistoryArray
arr = HistoryArray([1, 2, 3])
print(arr, arr.history)

# 执行一些操作
arr2 = arr + 1
print(arr2, arr2.history) # 注意: arr2的历史记录是空的，因为没有正确传递

arr[0] = 10
print(arr, arr.history)

arr_slice = arr[1:]
print(arr_slice, arr_slice.history)

注意： 在上面的例子中，arr2 的历史记录是空的。这是因为__array_wrap__返回的是一个ndarray实例，而不是HistoryArray实例。我们需要修改__array_wrap__来返回HistoryArray实例。

修改后的 __array_wrap__ 方法：

    def __array_wrap__(self, out_arr, context=None):
        #  在任何 ufunc 完成后调用
        if context:
            self.history.append(f"Operation: {context[0].__name__}")
        return HistoryArray(out_arr, history=self.history)  # 返回 HistoryArray 实例

现在再次运行上面的例子，arr2 的历史记录将被正确记录。

5. 关于 dtype 参数

__array_finalize__ 方法接收一个 dtype 参数，表示新数组的数据类型。在大多数情况下，我们不需要显式地处理 dtype，因为NumPy会自动处理数据类型转换。但是，在某些特殊情况下，我们可能需要根据 dtype 来执行不同的初始化操作。例如，如果我们需要创建一个只能存储特定数据类型的数组子类，我们可以使用 dtype 参数来验证输入数据类型。

6. 何时使用 __array_finalize__

需要自定义元数据: 当需要在NumPy数组子类中存储额外的元数据，并且需要在数组操作中保持这些元数据时，就需要使用__array_finalize__。
需要控制数组创建过程: __array_finalize__允许我们在数组创建的最后阶段进行干预，例如验证数据类型、初始化属性等。
与 __array_wrap__ 配合使用: 为了确保在ufunc操作后返回正确的子类实例，通常需要同时使用__array_finalize__和__array_wrap__。

7. 其他相关的特殊方法

__array_prepare__: 在 ufunc 执行之前调用。可以用来检查输入参数，并决定是否覆盖 ufunc 的行为。
__array__: 允许将自定义对象转换为 NumPy 数组。
__array_ufunc__: 允许完全自定义 ufunc 的行为。

这些方法提供了更高级的控制，可以实现非常复杂的数组子类行为。

8. 示例：避免元数据丢失

考虑以下情况，如果我们只是简单地子类化 ndarray 并添加一个属性，而不使用 __array_finalize__，可能会发生什么？

import numpy as np

class MyArray(np.ndarray):
    def __new__(cls, input_array, my_attribute=None, *args, **kwargs):
        obj = np.asarray(input_array, *args, **kwargs).view(cls)
        obj.my_attribute = my_attribute
        return obj

# 创建一个 MyArray 实例
arr = MyArray([1, 2, 3], my_attribute="Hello")
print(arr, arr.my_attribute)

# 切片操作
sliced_arr = arr[1:]
# sliced_arr 继承了ndarray的类型
print(type(sliced_arr)) # <class 'numpy.ndarray'>
try:
    print(sliced_arr.my_attribute)
except AttributeError:
    print("AttributeError: 'numpy.ndarray' object has no attribute 'my_attribute'")

正如你所看到的，切片操作返回了一个普通的 ndarray 实例，而不是 MyArray 实例。因此，my_attribute 丢失了。这就是为什么我们需要 __array_finalize__ 来确保元数据被正确地传递到新的数组实例。

9. 一个表格总结特殊方法

方法名	调用时机	作用
`__new__`	创建实例时	创建类的实例，设置初始属性。
`__array_finalize__`	创建新的数组实例时（例如，切片、视图）	初始化新数组实例，从原始数组复制元数据。
`__array_prepare__`	ufunc 执行之前	检查输入参数，决定是否覆盖 ufunc 的行为。
`__array_wrap__`	ufunc 执行之后	处理 ufunc 的输出，返回正确的子类实例。
`__array__`	需要将对象转换为 NumPy 数组时	将自定义对象转换为 NumPy 数组。
`__array_ufunc__`	执行 ufunc 时	完全自定义 ufunc 的行为。
`__setitem__`	给数组元素赋值时	覆盖默认的赋值行为，例如记录修改历史。

使用__array_finalize__传递元数据，扩展NumPy数组的功能

总之，__array_finalize__方法是自定义NumPy数组子类的关键。它允许我们管理和传递元数据，确保自定义行为在数组操作中得到保持。通过结合使用__array_finalize__、__array_wrap__和其他特殊方法，我们可以创建功能强大的NumPy数组子类，以满足特定的需求。

理解并正确使用__array_finalize__，可以创建功能强大的NumPy数组子类

希望今天的讲解能够帮助大家更好地理解和应用__array_finalize__方法。谢谢大家！

更多IT精英技术系列讲座，到智猿学院

Python中的__array_finalize__方法：自定义NumPy数组子类的元数据管理

发表回复 取消回复

Python中的`__array_finalize__`方法：自定义NumPy数组子类的元数据管理

发表回复取消回复