|
"""Mixin classes for custom array types that don't inherit from ndarray."""
# Nothing should be exposed in the top-level NumPy module.
"""True when __array_ufunc__ is set to None.""" try: return obj.__array_ufunc__ is None except AttributeError: return False
"""Implement a forward binary method with a ufunc, e.g., __add__.""" if _disables_array_ufunc(other): return NotImplemented return ufunc(self, other)
"""Implement a reflected binary method with a ufunc, e.g., __radd__.""" if _disables_array_ufunc(other): return NotImplemented return ufunc(other, self)
"""Implement an in-place binary method with a ufunc, e.g., __iadd__.""" return ufunc(self, other, out=(self,))
"""Implement forward, reflected and inplace binary methods with a ufunc.""" _reflected_binary_method(ufunc, name), _inplace_binary_method(ufunc, name))
"""Implement a unary special method with a ufunc.""" return ufunc(self)
"""Mixin defining all operator special methods using __array_ufunc__.
This class implements the special methods for almost all of Python's builtin operators defined in the `operator` module, including comparisons (``==``, ``>``, etc.) and arithmetic (``+``, ``*``, ``-``, etc.), by deferring to the ``__array_ufunc__`` method, which subclasses must implement.
It is useful for writing classes that do not inherit from `numpy.ndarray`, but that should support arithmetic and numpy universal functions like arrays as described in `A Mechanism for Overriding Ufuncs <../../neps/nep-0013-ufunc-overrides.html>`_.
As an trivial example, consider this implementation of an ``ArrayLike`` class that simply wraps a NumPy array and ensures that the result of any arithmetic operation is also an ``ArrayLike`` object::
class ArrayLike(np.lib.mixins.NDArrayOperatorsMixin): def __init__(self, value): self.value = np.asarray(value)
# One might also consider adding the built-in list type to this # list, to support operations like np.add(array_like, list) _HANDLED_TYPES = (np.ndarray, numbers.Number)
def __array_ufunc__(self, ufunc, method, *inputs, **kwargs): out = kwargs.get('out', ()) for x in inputs + out: # Only support operations with instances of _HANDLED_TYPES. # Use ArrayLike instead of type(self) for isinstance to # allow subclasses that don't override __array_ufunc__ to # handle ArrayLike objects. if not isinstance(x, self._HANDLED_TYPES + (ArrayLike,)): return NotImplemented
# Defer to the implementation of the ufunc on unwrapped values. inputs = tuple(x.value if isinstance(x, ArrayLike) else x for x in inputs) if out: kwargs['out'] = tuple( x.value if isinstance(x, ArrayLike) else x for x in out) result = getattr(ufunc, method)(*inputs, **kwargs)
if type(result) is tuple: # multiple return values return tuple(type(self)(x) for x in result) elif method == 'at': # no return value return None else: # one return value return type(self)(result)
def __repr__(self): return '%s(%r)' % (type(self).__name__, self.value)
In interactions between ``ArrayLike`` objects and numbers or numpy arrays, the result is always another ``ArrayLike``:
>>> x = ArrayLike([1, 2, 3]) >>> x - 1 ArrayLike(array([0, 1, 2])) >>> 1 - x ArrayLike(array([ 0, -1, -2])) >>> np.arange(3) - x ArrayLike(array([-1, -1, -1])) >>> x - np.arange(3) ArrayLike(array([1, 1, 1]))
Note that unlike ``numpy.ndarray``, ``ArrayLike`` does not allow operations with arbitrary, unrecognized types. This ensures that interactions with ArrayLike preserve a well-defined casting hierarchy.
.. versionadded:: 1.13 """ # Like np.ndarray, this mixin class implements "Option 1" from the ufunc # overrides NEP.
# comparisons don't have reflected and in-place versions
# numeric methods um.matmul, 'matmul') # Python 3 uses only __truediv__ and __floordiv__ __div__, __rdiv__, __idiv__ = _numeric_methods(um.divide, 'div') um.true_divide, 'truediv') um.floor_divide, 'floordiv') # __idivmod__ does not exist # TODO: handle the optional third argument for __pow__? um.left_shift, 'lshift') um.right_shift, 'rshift')
# unary methods |