numpy.array_api._typing.Array

Normalize inputs to two arg functions to fix type promotion rules

NumPy deviates from the spec type promotion rules in cases where one argument is 0-dimensional and the other is not. For example:

>>> import numpy as np
>>> a = np.array([1.0], dtype=np.float32)
>>> b = np.array(1.0, dtype=np.float64)
>>> np.add(a, b) # The spec says this should be float64
array([2.], dtype=float32)

To fix this, we add a dimension to the 0-dimension array before passing it through. This works because a dimension would be added anyway from broadcasting, so the resulting shape is the same, but this prevents NumPy from not promoting the dtype.

Validate an index according to the array API.

The array API specification only requires a subset of indices that are supported by NumPy. This function will reject any index that is allowed by NumPy but not required by the array API specification. We always raise IndexError on such indices (the spec does not require any specific behavior on them, but this makes the NumPy array API namespace a minimal implementation of the spec). See https://data-apis.org/array-api/latest/API_specification/indexing.html for the full list of required indexing behavior

This function either raises IndexError if the index key is invalid, or a new key to be used in place of key in indexing. It only raises IndexError on indices that are not already rejected by NumPy, as NumPy will already raise the appropriate error on such indices. shape may be None, in which case, only cases that are independent of the array shape are checked.

The following cases are allowed by NumPy, but not specified by the array API specification:

• Indices to not include an implicit ellipsis at the end. That is, every axis of an array must be explicitly indexed or an ellipsis included.
• The start and stop of a slice may not be out of bounds. In particular, for a slice i:j:k on an axis of size n, only the following are allowed:
  • i or j omitted (None).
  • -n <= i <= max(0, n - 1).
  • For k > 0 or k omitted (None), -n <= j <= n.
  • For k < 0, -n - 1 <= j <= max(0, n - 1).
• Boolean array indices are not allowed as part of a larger tuple index.
• Integer array indices are not allowed (with the exception of 0-D arrays, which are treated the same as scalars).

Additionally, it should be noted that indices that would return a scalar in NumPy will return a 0-D array. Array scalars are not allowed in the specification, only 0-D arrays. This is done in the Array._new constructor, not this function.