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, 11 insertions, 0 deletions

diff --git a/numpy/array_api/_manipulation_functions.py b/numpy/array_api/_manipulation_functions.py
index c11866261..4f2114ff5 100644
--- a/numpy/array_api/_manipulation_functions.py
+++ b/numpy/array_api/_manipulation_functions.py
@@ -41,6 +41,17 @@ def flip(x: Array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None) ->
     return Array._new(np.flip(x._array, axis=axis))
 
 
+# Note: The function name is different here (see also matrix_transpose).
+# Unlike transpose(), the axes argument is required.
+def permute_dims(x: Array, /, axes: Tuple[int, ...]) -> 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))
+
+
 def reshape(x: Array, /, shape: Tuple[int, ...]) -> Array:
     """
     Array API compatible wrapper for :py:func:`np.reshape <numpy.reshape>`.