NumPy 子类化 ndarray

介绍

对 ndarray 进行子类化相对简单，但与其他 Python 对象相比，它有一些复杂性。在此页面上，我们解释了允许您对 ndarray 进行子类化的机制，以及实现子类的含义。

ndarrays 和对象创建

由于 ndarray 类的新实例可以通过三种不同的方式产生，因此子类化 ndarray 很复杂。这些是：

1. 显式构造函数调用 - 如MySubClass(params). 这是创建 Python 实例的常用方法。
2. 视图转换 - 将现有的 ndarray 转换为给定的子类
3. New from template - 从模板实例创建一个新实例。示例包括从子类数组返回切片、从 ufunc 创建返回类型以及复制数组。有关更多详细信息，请参阅 从模板创建新内容

最后两个是 ndarrays 的特性 - 为了支持数组切片之类的东西。子类化 ndarray 的复杂性是由于 numpy 必须支持后两种实例创建路径的机制。

查看投射

视图转换是标准的 ndarray 机制，您可以通过它获取任何子类的 ndarray，并将数组的视图作为另一个（指定的）子类返回：

>>> import numpy as np
>>> # create a completely useless ndarray subclass
>>> class C(np.ndarray): pass
>>> # create a standard ndarray
>>> arr = np.zeros((3,))
>>> # take a view of it, as our useless subclass
>>> c_arr = arr.view(C)
>>> type(c_arr)
<class 'C'>

从模板创建新

ndarray 子类的新实例也可以通过与View cast非常相似的机制产生，当 numpy 发现它需要从模板实例创建一个新实例时。这必须发生的最明显的地方是当您获取子类数组的切片时。例如：

>>> v = c_arr[1:]
>>> type(v) # the view is of type 'C'
<class 'C'>
>>> v is c_arr # but it's a new instance
False

切片是原始数据的视图c_arr。因此，当我们从 ndarray 中查看时，我们返回一个新的 ndarray，属于同一类，指向原始数据。

使用 ndarrays 的其他点我们需要这样的视图，例如复制数组 ( c_arr.copy())、创建 ufunc 输出数组（另请参阅__array_wrap__ 以了解 ufuncs 和其他函数）和减少方法（如 c_arr.mean()）。

视图转换和新模板的关系

这些路径都使用相同的机器。我们在这里进行区分，因为它们会导致对您的方法的不同输入。具体来说， 视图转换意味着您已经从 ndarray 的任何潜在子类创建了数组类型的新实例。 从模板 创建新实例意味着您已经从预先存在的实例创建了类的新实例，例如，允许您跨子类特定的属性进行复制。

子类化的含义

如果我们继承 ndarray，我们不仅需要处理数组类型的显式构造，还需要处理视图转换或 从模板创建新的。NumPy 具有执行此操作的机制，正是这种机制使子类化略微非标准。

ndarray 用于支持子类中的视图和新模板的机制有两个方面。

首先是使用该ndarray.__new__方法进行对象初始化的主要工作，而不是更常用的__init__ 方法。第二个是使用该__array_finalize__方法允许子类在从模板创建视图和新实例后进行清理。

关于__new__和的简短 Python 入门__init__

__new__是一个标准的 Python 方法，如果存在，__init__在我们创建类实例之前调用。有关更多详细信息，请参阅python new 文档。

例如，考虑以下 Python 代码：

class C:
    def __new__(cls, *args):
        print('Cls in __new__:', cls)
        print('Args in __new__:', args)
        # The `object` type __new__ method takes a single argument.
        return object.__new__(cls)


    def __init__(self, *args):
        print('type(self) in __init__:', type(self))
        print('Args in __init__:', args)

这意味着我们得到：

>>> c = C('hello')
Cls in __new__: <class 'C'>
Args in __new__: ('hello',)
type(self) in __init__: <class 'C'>
Args in __init__: ('hello',)

当我们调用 时C('hello')，该__new__方法获取自己的类作为第一个参数，以及传递的参数，即字符串 'hello'。在 python 调用之后__new__，它通常（见下文）调用我​​们的__init__方法，将 的输出__new__作为第一个参数（现在是一个类实例），然后是传递的参数。

可以看到，对象可以在__new__ 方法中初始化，也可以在方法中初始化__init__，或者两者都可以，而实际上ndarray是没有__init__方法的，因为所有的初始化都是在__new__方法中完成的。 为什么要使用__new__而不仅仅是通常的__init__？因为在某些情况下，对于 ndarray，我们希望能够返回某个其他类的对象。考虑以下：

class D(C):
    def __new__(cls, *args):
        print('D cls is:', cls)
        print('D args in __new__:', args)
        return C.__new__(C, *args)


    def __init__(self, *args):
        # we never get here
        print('In D __init__')

意思是：

>>> obj = D('hello')
D cls is: <class 'D'>
D args in __new__: ('hello',)
Cls in __new__: <class 'C'>
Args in __new__: ('hello',)
>>> type(obj)
<class 'C'>

的定义C与之前相同，但对于D，该 __new__方法返回类的实例C而不是 D。请注意，不会调用的__init__方法D。通常，当该__new__方法返回定义它的类以外的类的对象时，__init__ 不会调用该类的方法。 这就是 ndarray 类的子类如何能够返回保留类类型的视图。在查看时，标准的 ndarray 机制会使用以下内容创建新的 ndarray 对象：

obj = ndarray.__new__(subtype, shape, ...

subdtype子类在哪里。因此，返回的视图与子类属于同一类，而不是属于 class ndarray。 这解决了返回相同类型视图的问题，但现在我们有一个新问题。ndarray 的机制可以在其用于获取视图的标准方法中以这种方式设置类，但是 ndarray __new__方法对我们在自己的__new__方法中为设置属性所做的一切一无所知 ，等等。（另外 - 为什么不调用呢？因为我们可能没有具有相同调用签名的方法）。obj = subdtype.__new__(...``__new__

__array_finalize__的作用

__array_finalize__ 是 numpy 提供的机制，允许子类处理创建新实例的各种方式。

请记住，子类实例可以通过以下三种方式产生：

1. 显式构造函数调用 ( )。这将调用then (如果存在) 的通常序列。obj = MySubClass(params)``MySubClass.__new__``MySubClass.__init__
2. 查看演员表
3. 从模板创建新

我们的MySubClass.__new__方法只在显式构造函数调用的情况下被调用，所以我们不能依赖MySubClass.__new__或 MySubClass.__init__处理视图转换和新模板。事实证明，MySubClass.__array_finalize__ 不被调用对象创建的所有三种方法，所以这是我们的对象创建看家一般无二。

• 对于显式构造函数调用，我们的子类需要创建它自己的类的新 ndarray 实例。在实践中，这意味着我们，代码的作者，需要调用 ndarray.__new__(MySubClass,...)，类层次结构准备调用 ，或者对现有数组进行视图转换（见下文）super().__new__(cls, ...)
• 对于视图转换和新模板ndarray.__new__(MySubClass,...，在 C 级别调用等效项 。

__array_finalize__上述三种实例创建方法接收的参数不同。 以下代码允许我们查看调用序列和参数：

import numpy as np


class C(np.ndarray):
    def __new__(cls, *args, **kwargs):
        print('In __new__ with class %s' % cls)
        return super().__new__(cls, *args, **kwargs)


    def __init__(self, *args, **kwargs):
        # in practice you probably will not need or want an __init__
        # method for your subclass
        print('In __init__ with class %s' % self.__class__)


    def __array_finalize__(self, obj):
        print('In array_finalize:')
        print('   self type is %s' % type(self))
        print('   obj type is %s' % type(obj))

现在：

>>> # Explicit constructor
>>> c = C((10,))
In __new__ with class <class 'C'>
In array_finalize:
   self type is <class 'C'>
   obj type is <type 'NoneType'>
In __init__ with class <class 'C'>
>>> # View casting
>>> a = np.arange(10)
>>> cast_a = a.view(C)
In array_finalize:
   self type is <class 'C'>
   obj type is <type 'numpy.ndarray'>
>>> # Slicing (example of new-from-template)
>>> cv = c[:1]
In array_finalize:
   self type is <class 'C'>
   obj type is <class 'C'>

的签名__array_finalize__是：

def __array_finalize__(self, obj):

可以看到，到 的super调用 ndarray.__new__传递__array_finalize__了我们自己的类 ( self) 以及从中获取视图的对象( )的新对象obj。从上面的输出可以看出，self总是我们子类的一个新创建的实例，obj 三种实例创建方法的类型不同：

• 当从显式构造函数调用时，obj是None
• 当从视图转换调用时，obj可以是 ndarray 的任何子类的实例，包括我们自己的。
• 当在 new-from-template 中调用时，obj是我们自己子类的另一个实例，我们可能会用它来更新新self实例。

因为__array_finalize__它是唯一能始终看到新实例被创建的方法，所以它是为新对象属性填充实例默认值以及其他任务的明智之选。 举个例子可能更清楚。

简单示例 - 向 ndarray 添加额外属性

import numpy as np


class InfoArray(np.ndarray):


    def __new__(subtype, shape, dtype=float, buffer=None, offset=0,
                strides=None, order=None, info=None):
        # Create the ndarray instance of our type, given the usual
        # ndarray input arguments.  This will call the standard
        # ndarray constructor, but return an object of our type.
        # It also triggers a call to InfoArray.__array_finalize__
        obj = super().__new__(subtype, shape, dtype,
                              buffer, offset, strides, order)
        # set the new 'info' attribute to the value passed
        obj.info = info
        # Finally, we must return the newly created object:
        return obj


    def __array_finalize__(self, obj):
        # ``self`` is a new object resulting from
        # ndarray.__new__(InfoArray, ...), therefore it only has
        # attributes that the ndarray.__new__ constructor gave it -
        # i.e. those of a standard ndarray.
        #
        # We could have got to the ndarray.__new__ call in 3 ways:
        # From an explicit constructor - e.g. InfoArray():
        #    obj is None
        #    (we're in the middle of the InfoArray.__new__
        #    constructor, and self.info will be set when we return to
        #    InfoArray.__new__)
        if obj is None: return
        # From view casting - e.g arr.view(InfoArray):
        #    obj is arr
        #    (type(obj) can be InfoArray)
        # From new-from-template - e.g infoarr[:3]
        #    type(obj) is InfoArray
        #
        # Note that it is here, rather than in the __new__ method,
        # that we set the default value for 'info', because this
        # method sees all creation of default objects - with the
        # InfoArray.__new__ constructor, but also with
        # arr.view(InfoArray).
        self.info = getattr(obj, 'info', None)
        # We do not need to return anything

使用对象如下所示：

>>> obj = InfoArray(shape=(3,)) # explicit constructor
>>> type(obj)
<class 'InfoArray'>
>>> obj.info is None
True
>>> obj = InfoArray(shape=(3,), info='information')
>>> obj.info
'information'
>>> v = obj[1:] # new-from-template - here - slicing
>>> type(v)
<class 'InfoArray'>
>>> v.info
'information'
>>> arr = np.arange(10)
>>> cast_arr = arr.view(InfoArray) # view casting
>>> type(cast_arr)
<class 'InfoArray'>
>>> cast_arr.info is None
True

这个类不是很有用，因为它具有与裸 ndarray 对象相同的构造函数，包括传入缓冲区和形状等。我们可能更希望构造函数能够从通常的 numpy 调用中获取一个已经形成的 ndarraynp.array并返回一个对象。

稍微更现实的例子 - 添加到现有数组的属性

这是一个类，它采用已经存在的标准 ndarray，转换为我们的类型，并添加了一个额外的属性。

import numpy as np


class RealisticInfoArray(np.ndarray):


    def __new__(cls, input_array, info=None):
        # Input array is an already formed ndarray instance
        # We first cast to be our class type
        obj = np.asarray(input_array).view(cls)
        # add the new attribute to the created instance
        obj.info = info
        # Finally, we must return the newly created object:
        return obj


    def __array_finalize__(self, obj):
        # see InfoArray.__array_finalize__ for comments
        if obj is None: return
        self.info = getattr(obj, 'info', None)

所以：

>>> arr = np.arange(5)
>>> obj = RealisticInfoArray(arr, info='information')
>>> type(obj)
<class 'RealisticInfoArray'>
>>> obj.info
'information'
>>> v = obj[1:]
>>> type(v)
<class 'RealisticInfoArray'>
>>> v.info
'information'

3 __array_ufunc__对于 ufunc 

1.13 版中的新功能。

子类可以通过覆盖默认ndarray.__array_ufunc__方法来覆盖在其上执行 numpy ufuncs 时发生的情况。执行此方法而不是ufunc 并且应该返回操作的结果，或者NotImplemented如果请求的操作没有实现。

的签名__array_ufunc__是：

def __array_ufunc__(ufunc, method, *inputs, **kwargs):


- *ufunc* is the ufunc object that was called.
- *method* is a string indicating how the Ufunc was called, either
  ``"__call__"`` to indicate it was called directly, or one of its
  :ref:`methods<ufuncs.methods>`: ``"reduce"``, ``"accumulate"``,
  ``"reduceat"``, ``"outer"``, or ``"at"``.
- *inputs* is a tuple of the input arguments to the ``ufunc``
- *kwargs* contains any optional or keyword arguments passed to the
  function. This includes any ``out`` arguments, which are always
  contained in a tuple.

典型的实现将转换作为自己类实例的任何输入或输出，使用 将所有内容传递给超类 super()，最后在可能的反向转换后返回结果。举例来说，来自测试案例采取 test_ufunc_override_with_super在core/tests/test_umath.py，如下。

import numpy as np


class A(np.ndarray):
    def __array_ufunc__(self, ufunc, method, *inputs, out=None, **kwargs):
        args = []
        in_no = []
        for i, input_ in enumerate(inputs):
            if isinstance(input_, A):
                in_no.append(i)
                args.append(input_.view(np.ndarray))
            else:
                args.append(input_)


        outputs = out
        out_no = []
        if outputs:
            out_args = []
            for j, output in enumerate(outputs):
                if isinstance(output, A):
                    out_no.append(j)
                    out_args.append(output.view(np.ndarray))
                else:
                    out_args.append(output)
            kwargs['out'] = tuple(out_args)
        else:
            outputs = (None,) * ufunc.nout


        info = {}
        if in_no:
            info['inputs'] = in_no
        if out_no:
            info['outputs'] = out_no


        results = super().__array_ufunc__(ufunc, method, *args, **kwargs)
        if results is NotImplemented:
            return NotImplemented


        if method == 'at':
            if isinstance(inputs[0], A):
                inputs[0].info = info
            return


        if ufunc.nout == 1:
            results = (results,)


        results = tuple((np.asarray(result).view(A)
                         if output is None else output)
                        for result, output in zip(results, outputs))
        if results and isinstance(results[0], A):
            results[0].info = info


        return results[0] if len(results) == 1 else results

所以，这个类实际上并没有做任何有趣的事情：它只是将它自己的任何实例转换为常规 ndarray（否则，我们会得到无限递归！），并添加一个info字典，告诉它转换了哪些输入和输出。因此，例如，

>>> a = np.arange(5.).view(A)
>>> b = np.sin(a)
>>> b.info
{'inputs': [0]}
>>> b = np.sin(np.arange(5.), out=(a,))
>>> b.info
{'outputs': [0]}
>>> a = np.arange(5.).view(A)
>>> b = np.ones(1).view(A)
>>> c = a + b
>>> c.info
{'inputs': [0, 1]}
>>> a += b
>>> a.info
{'inputs': [0, 1], 'outputs': [0]}

请注意，另一种方法是使用而不是调用。对于此示例，结果将是相同的，但如果另一个操作数也定义了 ，则会有所不同。例如，让我们假设我们评估 ，其中是另一个具有覆盖的类的实例。如果您在示例中使用as ， 会注意到它具有覆盖，这意味着它无法评估结果本身。因此，它将返回NotImplemented，我们的 class也将返回 。然后，控制将传递给，它要么知道如何处理我们并产生结果，要么不知道并返回NotImplemented，从而引发.getattr(ufunc, methods)(*inputs, **kwargs)``super``__array_ufunc__``np.add(a, b)``b``B``super``ndarray.__array_ufunc__``b``A``b``TypeError

相反，如果我们用 替换我们的super电话，我们就有效地做到了。同样， 将被调用，但现在它将 an视为另一个参数。很可能，它会知道如何处理这个问题，并将该类的一个新实例返回给我们。我们的示例类没有设置来处理这个问题，但如果，例如，要使用 重新实现，它可能是最好的方法。getattr(ufunc, method)``np.add(a.view(np.ndarray), b)``B.__array_ufunc__``ndarray``B``MaskedArray``__array_ufunc__

最后要注意的是：如果super路由适合给定的类，使用它的好处是它有助于构建类层次结构。例如，假设我们的另一个类在其 实现中B也使用了，并且我们创建了一个依赖于两者的类，即（为了简单起见，没有另一个 覆盖）。然后，实例上的任何 ufunc将传递给，调用将转到 ，调用将转到 ，从而允许并进行协作。super``__array_ufunc__``C``class C(A, B)``__array_ufunc__``C``A.__array_ufunc__``super``A``B.__array_ufunc__``super``B``ndarray.__array_ufunc__``A``B

__array_wrap__对于 ufuncs 和其他函数

在 numpy 1.13 之前，ufunc 的行为只能使用__array_wrap__和进行调整 __array_prepare__。这两个允许更改 ufunc 的输出类型，但与 相比 __array_ufunc__，不允许对输入进行任何更改。希望最终弃用这些，但__array_wrap__也被其他 numpy 函数和方法使用，例如squeeze，因此目前仍需要完整功能。

从概念上讲，__array_wrap__“包装动作”是指允许子类设置返回值的类型并更新属性和元数据。让我们用一个例子来展示它是如何工作的。首先我们回到更简单的示例子类，但使用不同的名称和一些打印语句：

import numpy as np


class MySubClass(np.ndarray):


    def __new__(cls, input_array, info=None):
        obj = np.asarray(input_array).view(cls)
        obj.info = info
        return obj


    def __array_finalize__(self, obj):
        print('In __array_finalize__:')
        print('   self is %s' % repr(self))
        print('   obj is %s' % repr(obj))
        if obj is None: return
        self.info = getattr(obj, 'info', None)


    def __array_wrap__(self, out_arr, context=None):
        print('In __array_wrap__:')
        print('   self is %s' % repr(self))
        print('   arr is %s' % repr(out_arr))
        # then just call the parent
        return super().__array_wrap__(self, out_arr, context)

我们在新数组的一个实例上运行一个 ufunc：

>>> obj = MySubClass(np.arange(5), info='spam')
In __array_finalize__:
   self is MySubClass([0, 1, 2, 3, 4])
   obj is array([0, 1, 2, 3, 4])
>>> arr2 = np.arange(5)+1
>>> ret = np.add(arr2, obj)
In __array_wrap__:
   self is MySubClass([0, 1, 2, 3, 4])
   arr is array([1, 3, 5, 7, 9])
In __array_finalize__:
   self is MySubClass([1, 3, 5, 7, 9])
   obj is MySubClass([0, 1, 2, 3, 4])
>>> ret
MySubClass([1, 3, 5, 7, 9])
>>> ret.info
'spam'

请注意， ufunc ( np.add) 调用了__array_wrap__带有参数selfas的方法obj，以及out_arr作为加法的 (ndarray) 结果。反过来，默认__array_wrap__ ( ndarray.__array_wrap__) 已将结果强制转换为 class MySubClass，并调用__array_finalize__- 因此复制info 属性。这一切都发生在 C 级。

但是，我们可以做任何我们想做的事情：

class SillySubClass(np.ndarray):


    def __array_wrap__(self, arr, context=None):
        return 'I lost your data'

>>> arr1 = np.arange(5)
>>> obj = arr1.view(SillySubClass)
>>> arr2 = np.arange(5)
>>> ret = np.multiply(obj, arr2)
>>> ret
'I lost your data'

因此，通过__array_wrap__为我们的子类定义一个特定的方法，我们可以调整 ufuncs 的输出。该__array_wrap__方法需要self，然后是一个参数——它是 ufunc 的结果——和一个可选的参数上下文。此参数由 ufuncs 作为 3 元素元组返回：（ufunc 的名称，ufunc 的参数，ufunc 的域），但不由其他 numpy 函数设置。虽然，如上所见，有可能以其他方式执行，但__array_wrap__应返回其包含类的实例。有关实现，请参阅掩码数组子类。

除了__array_wrap__在退出 ufunc 的途中调用的 之外，还有一个__array_prepare__方法在进入 ufunc 的途中调用，在创建输出数组之后但在执行任何计算之前。默认实现除了传递数组之外什么都不做。__array_prepare__不应尝试访问数组数据或调整数组大小，它旨在设置输出数组类型、更新属性和元数据，以及在计算开始之前根据可能需要的输入执行任何检查。像__array_wrap__,__array_prepare__必须返回一个 ndarray 或其子类或引发错误。

额外的问题 - 自定义__del__方法和 ndarray.base 

ndarray 解决的问题之一是跟踪 ndarray 及其视图的内存所有权。考虑我们创建了一个 ndarrayarr并使用. 这两个对象正在查看相同的内存。NumPy 使用以下属性跟踪特定数组或视图的数据来自何处 ：v = arr[1:]``base

>>> # A normal ndarray, that owns its own data
>>> arr = np.zeros((4,))
>>> # In this case, base is None
>>> arr.base is None
True
>>> # We take a view
>>> v1 = arr[1:]
>>> # base now points to the array that it derived from
>>> v1.base is arr
True
>>> # Take a view of a view
>>> v2 = v1[1:]
>>> # base points to the original array that it was derived from
>>> v2.base is arr
True

一般来说，如果数组拥有自己的内存，就arr在这种情况下，那么arr.base将是 None - 有一些例外 - 有关更多详细信息，请参阅 numpy book。

该base属性有助于判断我们是否拥有视图或原始数组。如果我们需要知道在删除子类数组时是否进行一些特定的清理，这反过来会很有用。例如，如果原始数组被删除，我们可能只想做清理，而不是视图。对于如何能工作的例子，看看在memmap上课 numpy.core。

子类化和下游兼容性

当子类化ndarray或创建模仿ndarray 接口的鸭子类型时，您有责任决定您的 API 与 numpy 的 API 的对齐程度。为了方便起见，具有相应的许多numpy的功能 ndarray的方法（例如，sum，mean，take，reshape）通过检查第一个参数的函数具有相同的名称的方法工作。如果存在，则调用该方法，而不是将参数强制转换为 numpy 数组。

例如，如果您希望您的子类或鸭子类型与 numpy 的sum函数兼容，则该对象的sum方法的方法签名应如下所示：

def sum(self, axis=None, dtype=None, out=None, keepdims=False):
...

这是完全相同的方法签名np.sum，所以现在如果用户调用 np.sum这个对象，numpy将调用对象自己的sum方法并在签名中传递上面枚举的这些参数，并且不会引发错误，因为签名完全兼容彼此。

但是，如果您决定偏离此签名并执行以下操作：

def sum(self, axis=None, dtype=None):
...

此对象不再与 兼容，np.sum因为如果您调用np.sum，它将传入意外的参数out和keepdims，从而引发 TypeError 。

如果您希望保持与 numpy 及其后续版本（可能会添加新的关键字参数）的兼容性，但又不想显示 numpy 的所有参数，则您的函数签名应接受**kwargs. 例如：

def sum(self, axis=None, dtype=None, **unused_kwargs):
...

这个对象现在np.sum再次兼容，因为任何无关的参数（即不是axis或 的关键字dtype）将隐藏在 **unused_kwargs参数中。