fix: add ak.array_equal to NEP18 overrides, documentation, and add …

…one more test (#3225)

* Fixing missed changes with ak.array_equal

* Now overrides numpy.array_equal
* Adding link to toctree
* Unit test checks numpy override

* np.array_equal no longer supports any numpy =? awkward

* Fixing issue with ak_almost_equal and backend checks

Using ensure_same_backend now, which raises an exception instead of
returning False. This is a new behavior for ak.almost_equal.
This also removes a shortcut in the code, and we get a NotImplementedError
on a typetracer backend. Test_2678 updated to match this expectation.

docs/reference/toctree.txt

@@ -299,11 +299,12 @@
     generated/ak.backend
 
 .. toctree::
-    :caption: Approximation
+    :caption: Approximation and comparison
 
     generated/ak.round
     generated/ak.isclose
     generated/ak.almost_equal
+    generated/ak.array_equal
 
 .. toctree::
     :caption: NumPy compatibility

src/awkward/operations/ak_almost_equal.py

@@ -2,10 +2,11 @@
 
 from __future__ import annotations
 
-from awkward._backends.dispatch import backend_of_obj
+from awkward._backends.dispatch import backend_of
 from awkward._backends.numpy import NumpyBackend
 from awkward._behavior import behavior_of, get_array_class, get_record_class
 from awkward._dispatch import high_level_function
+from awkward._layout import ensure_same_backend
 from awkward._nplikes.numpy_like import NumpyMetadata
 from awkward._parameters import parameters_are_equal
 from awkward.operations.ak_to_layout import to_layout
@@ -82,14 +83,13 @@ def _impl(
     left_behavior = behavior_of(left)
     right_behavior = behavior_of(right)
 
-    left_backend = backend_of_obj(left, default=cpu)
-    right_backend = backend_of_obj(right, default=cpu)
-    if left_backend is not right_backend:
-        return False
-    backend = left_backend
-
-    left_layout = to_layout(left, allow_record=False).to_packed()
-    right_layout = to_layout(right, allow_record=False).to_packed()
+    layouts = ensure_same_backend(
+        to_layout(left, allow_record=False),
+        to_layout(right, allow_record=False),
+    )
+    left_layout = layouts[0].to_packed()
+    right_layout = layouts[1].to_packed()
+    backend = backend_of(left_layout)
 
     if not backend.nplike.known_data:
         raise NotImplementedError(

src/awkward/operations/ak_array_equal.py

@@ -8,6 +8,7 @@
 __all__ = ("array_equal",)
 
 
+@ak._connect.numpy.implements("array_equal")
 @high_level_function()
 def array_equal(
     a1,

tests/test_1105_ak_aray_equal.py

@@ -88,3 +88,10 @@ def test_array_equal_with_params():
     )
     assert not ak.array_equal(a1, a2)
     assert ak.array_equal(a1, a2, check_parameters=False)
+
+
+def test_array_equal_numpy_override():
+    assert np.array_equal(
+        ak.Array([[1, 2], [], [3, 4, 5]]),
+        ak.Array([[1, 2], [], [3, 4, 5]]),
+    )

tests/test_2305_nep_18_lazy_conversion.py

@@ -11,7 +11,10 @@
 def test_binary():
     ak_array = ak.Array(np.arange(10, dtype="<u4"))
     np_array = np.arange(10, dtype=">u4")
-    assert np.array_equal(ak_array, np_array)
+    with pytest.raises(TypeError):
+        # ak.array_equal now overrides np.array_equal, and requires
+        # both arrays to be valid within awkward.
+        assert np.array_equal(ak_array, np_array)
 
 
 def test_different_backend():

tests/test_2678_same_backend.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import numpy as np  # noqa: F401
-import pytest  # noqa: F401
+import pytest
 
 import awkward as ak
 
@@ -16,6 +16,7 @@ def test_where():
 
 
 def test_almost_equal():
-    assert not ak.almost_equal(
-        [True, False, False], ak.to_backend([True, False, False], "typetracer")
-    )
+    with pytest.raises(NotImplementedError):
+        ak.almost_equal(
+            [True, False, False], ak.to_backend([True, False, False], "typetracer")
+        )