Rename the array class in the array API namespace from ndarray to Array

The actual class name doesn't matter because it isn't part of the namespace
API (arrays should be constructed with the array creation functions like
asarray()). However, it is better to use a name that is different from the
existing NumPy array object to avoid ambiguity.

Author: asmeurer

numpy/_array_api/__init__.py

@@ -58,7 +58,7 @@
   guaranteed to give a comprehensive coverage of the spec. Therefore, those
   reviewing this submodule should refer to the standard documents themselves.
 
-- There is a custom array object, numpy._array_api.ndarray, which is returned
+- There is a custom array object, numpy._array_api.Array, which is returned
   by all functions in this module. All functions in the array API namespace
   implicitly assume that they will only receive this object as input. The only
   way to create instances of this object is to use one of the array creation
@@ -69,14 +69,14 @@
   limit/change certain behavior that differs in the spec. In particular:
 
   - Indexing: Only a subset of indices supported by NumPy are required by the
-    spec. The ndarray object restricts indexing to only allow those types of
+    spec. The Array object restricts indexing to only allow those types of
     indices that are required by the spec. See the docstring of the
-    numpy._array_api.ndarray._validate_indices helper function for more
+    numpy._array_api.Array._validate_indices helper function for more
     information.
 
   - Type promotion: Some type promotion rules are different in the spec. In
     particular, the spec does not have any value-based casting. Note that the
-    code to correct the type promotion rules on numpy._array_api.ndarray is
+    code to correct the type promotion rules on numpy._array_api.Array is
     not yet implemented.
 
 - All functions include type annotations, corresponding to those given in the
@@ -93,7 +93,7 @@
 
 Still TODO in this module are:
 
-- Implement the spec type promotion rules on the ndarray object.
+- Implement the spec type promotion rules on the Array object.
 
 - Disable NumPy warnings in the API functions.
 

numpy/_array_api/_array_object.py

@@ -22,13 +22,13 @@
 
 from typing import TYPE_CHECKING
 if TYPE_CHECKING:
-    from ._types import Any, Optional, PyCapsule, Tuple, Union, Array
+    from ._types import Any, Optional, PyCapsule, Tuple, Union, Device, Dtype
 
 import numpy as np
 
-class ndarray:
+class Array:
     """
-    ndarray object for the array API namespace.
+    n-d array object for the array API namespace.
 
     See the docstring of :py:obj:`np.ndarray <numpy.ndarray>` for more
     information.
@@ -46,7 +46,7 @@ class ndarray:
     @classmethod
     def _new(cls, x, /):
         """
-        This is a private method for initializing the array API ndarray
+        This is a private method for initializing the array API Array
         object.
 
         Functions outside of the array_api submodule should not use this
@@ -64,9 +64,9 @@ def _new(cls, x, /):
         obj._array = x
         return obj
 
-    # Prevent ndarray() from working
+    # Prevent Array() from working
     def __new__(cls, *args, **kwargs):
-        raise TypeError("The array_api ndarray object should not be instantiated directly. Use an array creation function, such as asarray(), instead.")
+        raise TypeError("The array_api Array object should not be instantiated directly. Use an array creation function, such as asarray(), instead.")
 
     # These functions are not required by the spec, but are implemented for
     # the sake of usability.
@@ -75,13 +75,13 @@ def __str__(self: Array, /) -> str:
         """
         Performs the operation __str__.
         """
-        return self._array.__str__().replace('array', 'ndarray')
+        return self._array.__str__().replace('array', 'Array')
 
     def __repr__(self: Array, /) -> str:
         """
         Performs the operation __repr__.
         """
-        return self._array.__repr__().replace('array', 'ndarray')
+        return self._array.__repr__().replace('array', 'Array')
 
     # Helper function to match the type promotion rules in the spec
     def _promote_scalar(self, scalar):
@@ -109,7 +109,7 @@ def _promote_scalar(self, scalar):
         # behavior for integers within the bounds of the integer dtype.
         # Outside of those bounds we use the default NumPy behavior (either
         # cast or raise OverflowError).
-        return ndarray._new(np.array(scalar, self.dtype))
+        return Array._new(np.array(scalar, self.dtype))
 
     @staticmethod
     def _normalize_two_args(x1, x2):
@@ -135,9 +135,9 @@ def _normalize_two_args(x1, x2):
             # performant. broadcast_to(x1._array, x2.shape) is much slower. We
             # could also manually type promote x2, but that is more complicated
             # and about the same performance as this.
-            x1 = ndarray._new(x1._array[None])
+            x1 = Array._new(x1._array[None])
         elif x2.shape == () and x1.shape != ():
-            x2 = ndarray._new(x2._array[None])
+            x2 = Array._new(x2._array[None])
         return (x1, x2)
 
     # Everything below this line is required by the spec.
@@ -284,7 +284,7 @@ def _validate_index(key, shape):
         Additionally, it should be noted that indices that would return a
         scalar in NumPy will return a shape () array. Array scalars are not allowed
         in the specification, only shape () arrays. This is done in the
-        ``ndarray._new`` constructor, not this function.
+        ``Array._new`` constructor, not this function.
 
         """
         if isinstance(key, slice):
@@ -313,7 +313,7 @@ def _validate_index(key, shape):
             return key
 
         elif isinstance(key, tuple):
-            key = tuple(ndarray._validate_index(idx, None) for idx in key)
+            key = tuple(Array._validate_index(idx, None) for idx in key)
 
             for idx in key:
                 if isinstance(idx, np.ndarray) and idx.dtype in _boolean_dtypes or isinstance(idx, (bool, np.bool_)):
@@ -329,11 +329,11 @@ def _validate_index(key, shape):
             ellipsis_i = key.index(...) if n_ellipsis else len(key)
 
             for idx, size in list(zip(key[:ellipsis_i], shape)) + list(zip(key[:ellipsis_i:-1], shape[:ellipsis_i:-1])):
-                ndarray._validate_index(idx, (size,))
+                Array._validate_index(idx, (size,))
             return key
         elif isinstance(key, bool):
             return key
-        elif isinstance(key, ndarray):
+        elif isinstance(key, Array):
             if key.dtype in _integer_dtypes:
                 if key.shape != ():
                     raise IndexError("Integer array indices with shape != () are not allowed in the array API namespace")
@@ -346,7 +346,7 @@ def _validate_index(key, shape):
             return operator.index(key)
         except TypeError:
             # Note: This also omits boolean arrays that are not already in
-            # ndarray() form, like a list of booleans.
+            # Array() form, like a list of booleans.
             raise IndexError("Only integers, slices (`:`), ellipsis (`...`), and boolean arrays are valid indices in the array API namespace")
 
     def __getitem__(self: Array, key: Union[int, slice, ellipsis, Tuple[Union[int, slice, ellipsis], ...], Array], /) -> Array:

numpy/_array_api/_creation_functions.py

@@ -19,14 +19,14 @@ def asarray(obj: Union[float, NestedSequence[bool|int|float], SupportsDLPack, Su
     """
     # _array_object imports in this file are inside the functions to avoid
     # circular imports
-    from ._array_object import ndarray
+    from ._array_object import Array
     if device is not None:
-        # Note: Device support is not yet implemented on ndarray
+        # Note: Device support is not yet implemented on Array
         raise NotImplementedError("Device support is not yet implemented")
     if copy is not None:
         # Note: copy is not yet implemented in np.asarray
         raise NotImplementedError("The copy keyword argument to asarray is not yet implemented")
-    if isinstance(obj, ndarray) and (dtype is None or obj.dtype == dtype):
+    if isinstance(obj, Array) and (dtype is None or obj.dtype == dtype):
         return obj
     if dtype is None and isinstance(obj, int) and (obj > 2**64 or obj < -2**63):
         # Give a better error message in this case. NumPy would convert this
@@ -35,58 +35,58 @@ def asarray(obj: Union[float, NestedSequence[bool|int|float], SupportsDLPack, Su
     res = np.asarray(obj, dtype=dtype)
     if res.dtype not in _all_dtypes:
         raise TypeError(f"The array_api namespace does not support the dtype '{res.dtype}'")
-    return ndarray._new(res)
+    return Array._new(res)
 
 def arange(start: Union[int, float], /, stop: Optional[Union[int, float]] = None, step: Union[int, float] = 1, *, dtype: Optional[Dtype] = None, device: Optional[Device] = None) -> Array:
     """
     Array API compatible wrapper for :py:func:`np.arange <numpy.arange>`.
 
     See its docstring for more information.
     """
-    from ._array_object import ndarray
+    from ._array_object import Array
     if device is not None:
-        # Note: Device support is not yet implemented on ndarray
+        # Note: Device support is not yet implemented on Array
         raise NotImplementedError("Device support is not yet implemented")
-    return ndarray._new(np.arange(start, stop=stop, step=step, dtype=dtype))
+    return Array._new(np.arange(start, stop=stop, step=step, dtype=dtype))
 
 def empty(shape: Union[int, Tuple[int, ...]], *, dtype: Optional[Dtype] = None, device: Optional[Device] = None) -> Array:
     """
     Array API compatible wrapper for :py:func:`np.empty <numpy.empty>`.
 
     See its docstring for more information.
     """
-    from ._array_object import ndarray
+    from ._array_object import Array
     if device is not None:
-        # Note: Device support is not yet implemented on ndarray
+        # Note: Device support is not yet implemented on Array
         raise NotImplementedError("Device support is not yet implemented")
-    return ndarray._new(np.empty(shape, dtype=dtype))
+    return Array._new(np.empty(shape, dtype=dtype))
 
 def empty_like(x: Array, /, *, dtype: Optional[Dtype] = None, device: Optional[Device] = None) -> Array:
     """
     Array API compatible wrapper for :py:func:`np.empty_like <numpy.empty_like>`.
 
     See its docstring for more information.
     """
-    from ._array_object import ndarray
+    from ._array_object import Array
     if device is not None:
-        # Note: Device support is not yet implemented on ndarray
+        # Note: Device support is not yet implemented on Array
         raise NotImplementedError("Device support is not yet implemented")
-    return ndarray._new(np.empty_like(x._array, dtype=dtype))
+    return Array._new(np.empty_like(x._array, dtype=dtype))
 
 def eye(n_rows: int, n_cols: Optional[int] = None, /, *, k: Optional[int] = 0, dtype: Optional[Dtype] = None, device: Optional[Device] = None) -> Array:
     """
     Array API compatible wrapper for :py:func:`np.eye <numpy.eye>`.
 
     See its docstring for more information.
     """
-    from ._array_object import ndarray
+    from ._array_object import Array
     if device is not None:
-        # Note: Device support is not yet implemented on ndarray
+        # Note: Device support is not yet implemented on Array
         raise NotImplementedError("Device support is not yet implemented")
-    return ndarray._new(np.eye(n_rows, M=n_cols, k=k, dtype=dtype))
+    return Array._new(np.eye(n_rows, M=n_cols, k=k, dtype=dtype))
 
 def from_dlpack(x: object, /) -> Array:
-    # Note: dlpack support is not yet implemented on ndarray
+    # Note: dlpack support is not yet implemented on Array
     raise NotImplementedError("DLPack support is not yet implemented")
 
 def full(shape: Union[int, Tuple[int, ...]], fill_value: Union[int, float], *, dtype: Optional[Dtype] = None, device: Optional[Device] = None) -> Array:
@@ -95,101 +95,101 @@ def full(shape: Union[int, Tuple[int, ...]], fill_value: Union[int, float], *, d
 
     See its docstring for more information.
     """
-    from ._array_object import ndarray
+    from ._array_object import Array
     if device is not None:
-        # Note: Device support is not yet implemented on ndarray
+        # Note: Device support is not yet implemented on Array
         raise NotImplementedError("Device support is not yet implemented")
-    if isinstance(fill_value, ndarray) and fill_value.ndim == 0:
-            fill_value = fill_value._array[...]
+    if isinstance(fill_value, Array) and fill_value.ndim == 0:
+        fill_value = fill_value._array[...]
     res = np.full(shape, fill_value, dtype=dtype)
     if res.dtype not in _all_dtypes:
         # This will happen if the fill value is not something that NumPy
         # coerces to one of the acceptable dtypes.
         raise TypeError("Invalid input to full")
-    return ndarray._new(res)
+    return Array._new(res)
 
 def full_like(x: Array, /, fill_value: Union[int, float], *, dtype: Optional[Dtype] = None, device: Optional[Device] = None) -> Array:
     """
     Array API compatible wrapper for :py:func:`np.full_like <numpy.full_like>`.
 
     See its docstring for more information.
     """
-    from ._array_object import ndarray
+    from ._array_object import Array
     if device is not None:
-        # Note: Device support is not yet implemented on ndarray
+        # Note: Device support is not yet implemented on Array
         raise NotImplementedError("Device support is not yet implemented")
     res = np.full_like(x._array, fill_value, dtype=dtype)
     if res.dtype not in _all_dtypes:
         # This will happen if the fill value is not something that NumPy
         # coerces to one of the acceptable dtypes.
         raise TypeError("Invalid input to full_like")
-    return ndarray._new(res)
+    return Array._new(res)
 
 def linspace(start: Union[int, float], stop: Union[int, float], /, num: int, *, dtype: Optional[Dtype] = None, device: Optional[Device] = None, endpoint: bool = True) -> Array:
     """
     Array API compatible wrapper for :py:func:`np.linspace <numpy.linspace>`.
 
     See its docstring for more information.
     """
-    from ._array_object import ndarray
+    from ._array_object import Array
     if device is not None:
-        # Note: Device support is not yet implemented on ndarray
+        # Note: Device support is not yet implemented on Array
         raise NotImplementedError("Device support is not yet implemented")
-    return ndarray._new(np.linspace(start, stop, num, dtype=dtype, endpoint=endpoint))
+    return Array._new(np.linspace(start, stop, num, dtype=dtype, endpoint=endpoint))
 
 def meshgrid(*arrays: Sequence[Array], indexing: str = 'xy') -> List[Array, ...]:
     """
     Array API compatible wrapper for :py:func:`np.meshgrid <numpy.meshgrid>`.
 
     See its docstring for more information.
     """
-    from ._array_object import ndarray
-    return [ndarray._new(array) for array in np.meshgrid(*[a._array for a in arrays], indexing=indexing)]
+    from ._array_object import Array
+    return [Array._new(array) for array in np.meshgrid(*[a._array for a in arrays], indexing=indexing)]
 
 def ones(shape: Union[int, Tuple[int, ...]], *, dtype: Optional[Dtype] = None, device: Optional[Device] = None) -> Array:
     """
     Array API compatible wrapper for :py:func:`np.ones <numpy.ones>`.
 
     See its docstring for more information.
     """
-    from ._array_object import ndarray
+    from ._array_object import Array
     if device is not None:
-        # Note: Device support is not yet implemented on ndarray
+        # Note: Device support is not yet implemented on Array
         raise NotImplementedError("Device support is not yet implemented")
-    return ndarray._new(np.ones(shape, dtype=dtype))
+    return Array._new(np.ones(shape, dtype=dtype))
 
 def ones_like(x: Array, /, *, dtype: Optional[Dtype] = None, device: Optional[Device] = None) -> Array:
     """
     Array API compatible wrapper for :py:func:`np.ones_like <numpy.ones_like>`.
 
     See its docstring for more information.
     """
-    from ._array_object import ndarray
+    from ._array_object import Array
     if device is not None:
-        # Note: Device support is not yet implemented on ndarray
+        # Note: Device support is not yet implemented on Array
         raise NotImplementedError("Device support is not yet implemented")
-    return ndarray._new(np.ones_like(x._array, dtype=dtype))
+    return Array._new(np.ones_like(x._array, dtype=dtype))
 
 def zeros(shape: Union[int, Tuple[int, ...]], *, dtype: Optional[Dtype] = None, device: Optional[Device] = None) -> Array:
     """
     Array API compatible wrapper for :py:func:`np.zeros <numpy.zeros>`.
 
     See its docstring for more information.
     """
-    from ._array_object import ndarray
+    from ._array_object import Array
     if device is not None:
-        # Note: Device support is not yet implemented on ndarray
+        # Note: Device support is not yet implemented on Array
         raise NotImplementedError("Device support is not yet implemented")
-    return ndarray._new(np.zeros(shape, dtype=dtype))
+    return Array._new(np.zeros(shape, dtype=dtype))
 
 def zeros_like(x: Array, /, *, dtype: Optional[Dtype] = None, device: Optional[Device] = None) -> Array:
     """
     Array API compatible wrapper for :py:func:`np.zeros_like <numpy.zeros_like>`.
 
     See its docstring for more information.
     """
-    from ._array_object import ndarray
+    from ._array_object import Array
     if device is not None:
-        # Note: Device support is not yet implemented on ndarray
+        # Note: Device support is not yet implemented on Array
         raise NotImplementedError("Device support is not yet implemented")
-    return ndarray._new(np.zeros_like(x._array, dtype=dtype))
+    return Array._new(np.zeros_like(x._array, dtype=dtype))