ENH: Updates to numpy.array_api (#19937)

* Add __index__ to array_api and update __int__, __bool__, and __float__

The spec specifies that they should only work on arrays with corresponding
dtypes. __index__ is new in the spec since the initial PR, and works
identically to np.array.__index__.

* Add the to_device method to the array_api

This method is new since #18585. It does nothing in NumPy since NumPy does not
support non-CPU devices.

* Update transpose methods in the array_api

transpose() was renamed to matrix_transpose() and now operates on stacks of
matrices. A function to permute dimensions will be added once it is finalized
in the spec. The attribute mT was added and the T attribute was updated to
only operate on 2-dimensional arrays as per the spec.

* Restrict input dtypes in the array API statistical functions

* Add the dtype parameter to the array API sum() and prod()

* Add the function permute_dims() to the array_api namespace

permute_dims() is the replacement for transpose(), which was split into
permute_dims() and matrix_transpose().

* Add tril and triu to the array API namespace

* Fix the array_api Array.__repr__ to indent the array properly

* Make the Device type in the array_api just accept the string "cpu"

1 files changed, 6 insertions, 7 deletions

diff --git a/numpy/array_api/_linear_algebra_functions.py b/numpy/array_api/_linear_algebra_functions.py
index 089081725..7a6c9846c 100644
--- a/numpy/array_api/_linear_algebra_functions.py
+++ b/numpy/array_api/_linear_algebra_functions.py
@@ -52,13 +52,12 @@ def tensordot(
     return Array._new(np.tensordot(x1._array, x2._array, axes=axes))
 
 
-def transpose(x: Array, /, *, axes: Optional[Tuple[int, ...]] = None) -> Array:
-    """
-    Array API compatible wrapper for :py:func:`np.transpose <numpy.transpose>`.
-
-    See its docstring for more information.
-    """
-    return Array._new(np.transpose(x._array, axes=axes))
+# Note: this function is new in the array API spec. Unlike transpose, it only
+# transposes the last two axes.
+def matrix_transpose(x: Array, /) -> Array:
+    if x.ndim < 2:
+        raise ValueError("x must be at least 2-dimensional for matrix_transpose")
+    return Array._new(np.swapaxes(x._array, -1, -2))
 
 
 # Note: vecdot is not in NumPy