Coverage for /var/srv/projects/api.amasfac.comuna18.com/tmp/venv/lib/python3.9/site-packages/numpy/lib/mixins.py: 75%
59 statements
« prev ^ index » next coverage.py v6.4.4, created at 2023-07-17 14:22 -0600
« prev ^ index » next coverage.py v6.4.4, created at 2023-07-17 14:22 -0600
1"""Mixin classes for custom array types that don't inherit from ndarray."""
2from numpy.core import umath as um
5__all__ = ['NDArrayOperatorsMixin']
8def _disables_array_ufunc(obj):
9 """True when __array_ufunc__ is set to None."""
10 try:
11 return obj.__array_ufunc__ is None
12 except AttributeError:
13 return False
16def _binary_method(ufunc, name):
17 """Implement a forward binary method with a ufunc, e.g., __add__."""
18 def func(self, other):
19 if _disables_array_ufunc(other):
20 return NotImplemented
21 return ufunc(self, other)
22 func.__name__ = '__{}__'.format(name)
23 return func
26def _reflected_binary_method(ufunc, name):
27 """Implement a reflected binary method with a ufunc, e.g., __radd__."""
28 def func(self, other):
29 if _disables_array_ufunc(other):
30 return NotImplemented
31 return ufunc(other, self)
32 func.__name__ = '__r{}__'.format(name)
33 return func
36def _inplace_binary_method(ufunc, name):
37 """Implement an in-place binary method with a ufunc, e.g., __iadd__."""
38 def func(self, other):
39 return ufunc(self, other, out=(self,))
40 func.__name__ = '__i{}__'.format(name)
41 return func
44def _numeric_methods(ufunc, name):
45 """Implement forward, reflected and inplace binary methods with a ufunc."""
46 return (_binary_method(ufunc, name),
47 _reflected_binary_method(ufunc, name),
48 _inplace_binary_method(ufunc, name))
51def _unary_method(ufunc, name):
52 """Implement a unary special method with a ufunc."""
53 def func(self):
54 return ufunc(self)
55 func.__name__ = '__{}__'.format(name)
56 return func
59class NDArrayOperatorsMixin:
60 """Mixin defining all operator special methods using __array_ufunc__.
62 This class implements the special methods for almost all of Python's
63 builtin operators defined in the `operator` module, including comparisons
64 (``==``, ``>``, etc.) and arithmetic (``+``, ``*``, ``-``, etc.), by
65 deferring to the ``__array_ufunc__`` method, which subclasses must
66 implement.
68 It is useful for writing classes that do not inherit from `numpy.ndarray`,
69 but that should support arithmetic and numpy universal functions like
70 arrays as described in `A Mechanism for Overriding Ufuncs
71 <https://numpy.org/neps/nep-0013-ufunc-overrides.html>`_.
73 As an trivial example, consider this implementation of an ``ArrayLike``
74 class that simply wraps a NumPy array and ensures that the result of any
75 arithmetic operation is also an ``ArrayLike`` object::
77 class ArrayLike(np.lib.mixins.NDArrayOperatorsMixin):
78 def __init__(self, value):
79 self.value = np.asarray(value)
81 # One might also consider adding the built-in list type to this
82 # list, to support operations like np.add(array_like, list)
83 _HANDLED_TYPES = (np.ndarray, numbers.Number)
85 def __array_ufunc__(self, ufunc, method, *inputs, **kwargs):
86 out = kwargs.get('out', ())
87 for x in inputs + out:
88 # Only support operations with instances of _HANDLED_TYPES.
89 # Use ArrayLike instead of type(self) for isinstance to
90 # allow subclasses that don't override __array_ufunc__ to
91 # handle ArrayLike objects.
92 if not isinstance(x, self._HANDLED_TYPES + (ArrayLike,)):
93 return NotImplemented
95 # Defer to the implementation of the ufunc on unwrapped values.
96 inputs = tuple(x.value if isinstance(x, ArrayLike) else x
97 for x in inputs)
98 if out:
99 kwargs['out'] = tuple(
100 x.value if isinstance(x, ArrayLike) else x
101 for x in out)
102 result = getattr(ufunc, method)(*inputs, **kwargs)
104 if type(result) is tuple:
105 # multiple return values
106 return tuple(type(self)(x) for x in result)
107 elif method == 'at':
108 # no return value
109 return None
110 else:
111 # one return value
112 return type(self)(result)
114 def __repr__(self):
115 return '%s(%r)' % (type(self).__name__, self.value)
117 In interactions between ``ArrayLike`` objects and numbers or numpy arrays,
118 the result is always another ``ArrayLike``:
120 >>> x = ArrayLike([1, 2, 3])
121 >>> x - 1
122 ArrayLike(array([0, 1, 2]))
123 >>> 1 - x
124 ArrayLike(array([ 0, -1, -2]))
125 >>> np.arange(3) - x
126 ArrayLike(array([-1, -1, -1]))
127 >>> x - np.arange(3)
128 ArrayLike(array([1, 1, 1]))
130 Note that unlike ``numpy.ndarray``, ``ArrayLike`` does not allow operations
131 with arbitrary, unrecognized types. This ensures that interactions with
132 ArrayLike preserve a well-defined casting hierarchy.
134 .. versionadded:: 1.13
135 """
136 # Like np.ndarray, this mixin class implements "Option 1" from the ufunc
137 # overrides NEP.
139 # comparisons don't have reflected and in-place versions
140 __lt__ = _binary_method(um.less, 'lt')
141 __le__ = _binary_method(um.less_equal, 'le')
142 __eq__ = _binary_method(um.equal, 'eq')
143 __ne__ = _binary_method(um.not_equal, 'ne')
144 __gt__ = _binary_method(um.greater, 'gt')
145 __ge__ = _binary_method(um.greater_equal, 'ge')
147 # numeric methods
148 __add__, __radd__, __iadd__ = _numeric_methods(um.add, 'add')
149 __sub__, __rsub__, __isub__ = _numeric_methods(um.subtract, 'sub')
150 __mul__, __rmul__, __imul__ = _numeric_methods(um.multiply, 'mul')
151 __matmul__, __rmatmul__, __imatmul__ = _numeric_methods(
152 um.matmul, 'matmul')
153 # Python 3 does not use __div__, __rdiv__, or __idiv__
154 __truediv__, __rtruediv__, __itruediv__ = _numeric_methods(
155 um.true_divide, 'truediv')
156 __floordiv__, __rfloordiv__, __ifloordiv__ = _numeric_methods(
157 um.floor_divide, 'floordiv')
158 __mod__, __rmod__, __imod__ = _numeric_methods(um.remainder, 'mod')
159 __divmod__ = _binary_method(um.divmod, 'divmod')
160 __rdivmod__ = _reflected_binary_method(um.divmod, 'divmod')
161 # __idivmod__ does not exist
162 # TODO: handle the optional third argument for __pow__?
163 __pow__, __rpow__, __ipow__ = _numeric_methods(um.power, 'pow')
164 __lshift__, __rlshift__, __ilshift__ = _numeric_methods(
165 um.left_shift, 'lshift')
166 __rshift__, __rrshift__, __irshift__ = _numeric_methods(
167 um.right_shift, 'rshift')
168 __and__, __rand__, __iand__ = _numeric_methods(um.bitwise_and, 'and')
169 __xor__, __rxor__, __ixor__ = _numeric_methods(um.bitwise_xor, 'xor')
170 __or__, __ror__, __ior__ = _numeric_methods(um.bitwise_or, 'or')
172 # unary methods
173 __neg__ = _unary_method(um.negative, 'neg')
174 __pos__ = _unary_method(um.positive, 'pos')
175 __abs__ = _unary_method(um.absolute, 'abs')
176 __invert__ = _unary_method(um.invert, 'invert')