Deprecate LazyExpr.evaluate() for forthcoming 2.7.0

Author: FrancescAlted

blosc2/lazyexpr.py

@@ -5,6 +5,8 @@
 # This source code is licensed under a BSD-style license (found in the
 # LICENSE file in the root directory of this source tree)
 #######################################################################
+import warnings
+
 import ndindex
 import numexpr as ne
 import numpy as np
@@ -218,9 +220,39 @@ def __rpow__(self, value):
     def __ipow__(self, value):
         return self.update_expr(new_op=(self, "**", value))
 
+    def evaluate(self, item=None, **kwargs) -> blosc2.NDArray:
+        """Evaluate the lazy expression in self.
 
+        Parameters
+        ----------
+        item: slice, list of slices, optional
+            If not None, only the chunks that intersect with the slices
+            in items will be evaluated.
+        kwargs: dict, optional
+            Keyword arguments that are supported by the :func:`empty` constructor.
 
-    def evaluate(self, item=None, **kwargs) -> blosc2.NDArray:
+        Returns
+        -------
+        :ref:`NDArray`
+            The output array.
+
+        Note
+        ----
+
+        This is a deprecated method.  Use the new evaluation engine in Python-Blosc2 3.x.
+        """
+        warnings.warn(
+            "The `evaluate` method is deprecated as of Python-Blosc2 2.7.0 and is"
+            " actually removed in Python-Blosc2 3.x series. Use `LazyExpr.eval()` instead. "
+            "If you are interested in computing expressions involving NDArray instances, "
+            "please use the new, much improved, evaluation engine in Python-Blosc2 3.x series. "
+            "For more information, please check the documentation at: <New 3.x documentation URL>",
+            stacklevel=2,
+            category=DeprecationWarning,
+        )
+        return self.eval(item=item, **kwargs)
+
+    def eval(self, item=None, **kwargs) -> blosc2.NDArray:
         """Evaluate the lazy expression in self.
 
         Parameters
@@ -235,6 +267,11 @@ def evaluate(self, item=None, **kwargs) -> blosc2.NDArray:
         -------
         :ref:`NDArray`
             The output array.
+
+        Note
+        ----
+
+        This is a deprecated method.  Use the new evaluation engine in Python-Blosc2 3.x.
         """
         shape, dtype, equal_chunks, equal_blocks = validate_inputs(self.operands)
         nelem = np.prod(shape)
@@ -249,7 +286,7 @@ def evaluate(self, item=None, **kwargs) -> blosc2.NDArray:
         return out
 
     def __getitem__(self, item):
-        ndarray = self.evaluate(item=item)
+        ndarray = self.eval(item=item)
         return ndarray[item] if item is not None else ndarray[:]
 
     def __str__(self):
@@ -475,7 +512,7 @@ def do_slices_intersect(slice1, slice2):
     print(f"Elapsed time (numexpr, [:]): {time() - t0:.3f} s")
     nres = nres[sl] if sl is not None else nres
     t0 = time()
-    res = expr.evaluate(item=sl)
+    res = expr.eval(item=sl)
     print(f"Elapsed time (evaluate): {time() - t0:.3f} s")
     res = res[sl] if sl is not None else res[:]
     t0 = time()
@@ -498,7 +535,7 @@ def do_slices_intersect(slice1, slice2):
     print(f"Elapsed time (numexpr, [:]): {time() - t0:.3f} s")
     nres = nres[sl] if sl is not None else nres
     t0 = time()
-    res = expr.evaluate(sl)
+    res = expr.eval(sl)
     print(f"Elapsed time (evaluate): {time() - t0:.3f} s")
     res = res[sl] if sl is not None else res[:]
     t0 = time()

tests/ndarray/test_lazyexpr.py

@@ -85,7 +85,7 @@ def test_simple_expression(array_fixture):
     a1, a2, a3, a4, na1, na2, na3, na4 = array_fixture
     expr = a1 + a2 - a3 * a4
     nres = ne.evaluate("na1 + na2 - na3 * na4")
-    res = expr.evaluate()
+    res = expr.eval()
     np.testing.assert_allclose(res[:], nres)
 
 
@@ -97,7 +97,7 @@ def test_iXXX(array_fixture):
     expr *= 2  # __imul__
     expr /= 7  # __itruediv__
     expr **= 2.3  # __ipow__
-    res = expr.evaluate()
+    res = expr.eval()
     nres = ne.evaluate("(((((na1 ** 3 + na2 ** 2 + na3 ** 3 - na4 + 3) + 5) - 15) * 2) / 7) ** 2.3")
     np.testing.assert_allclose(res[:], nres)
 
@@ -107,7 +107,7 @@ def test_complex_evaluate(array_fixture):
     expr = blosc2.tan(a1) * (blosc2.sin(a2) * blosc2.sin(a2) + blosc2.cos(a3)) + (blosc2.sqrt(a4) * 2)
     expr += 2
     nres = ne.evaluate("tan(na1) * (sin(na2) * sin(na2) + cos(na3)) + (sqrt(na4) * 2) + 2")
-    res = expr.evaluate()
+    res = expr.eval()
     np.testing.assert_allclose(res[:], nres)