refactor!: allow subsets of dtypes and allow device-dependent dtype support

PR-URL: data-apis#1005
Reviewed-by: Athan Reines <kgryte@gmail.com>
Reviewed-by: Ralf Gommers <ralf.gommers@gmail.com>
Reviewed-by: Olivier Grisel
Ref: data-apis#998

Author: ev-br

spec/draft/API_specification/creation_functions.rst

@@ -34,3 +34,8 @@ Objects in API
    triu
    zeros
    zeros_like
+
+
+.. note::
+   Creation functions which accept ``device`` and ``dtype`` arguments should raise an
+   exception if the explicitly provided ``dtype`` is not supported by the ``device``.

spec/draft/API_specification/data_types.rst

@@ -5,7 +5,7 @@ Data Types
 
     Array API specification for supported data types.
 
-A conforming implementation of the array API standard must provide and support
+A conforming implementation of the array API standard should provide and support
 the following data types ("dtypes") in its array object, and as data type
 objects in its main namespace under the specified names:
 
@@ -39,6 +39,8 @@ objects in its main namespace under the specified names:
 | complex128   | Double-precision (128-bit) complex floating-point number whose real and imaginary components must be IEEE 754 double-precision (64-bit) binary floating-point numbers (see IEEE 754-2019). |
 +--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
+If a library only supports a subset of data types, it must at a minimum support ``bool`` and at least one integer dtype and one real floating-point dtype.
+
 Data type objects must have the following methods (no attributes are required):
 
 ..

spec/draft/design_topics/device_support.rst

@@ -77,6 +77,7 @@ rather than hard requirements:
 - Respect explicit device assignment (i.e. if the input to the ``device=`` keyword is not ``None``, guarantee that the array is created on the given device, and raise an exception otherwise).
 - Preserve device assignment as much as possible (e.g. output arrays from a function are expected to be on the same device as input arrays to the function).
 - Raise an exception if an operation involves arrays on different devices (i.e. avoid implicit data transfer between devices).
+- Raise an exception if the user explicitly requests an unsupported combination of a ``device=`` and ``dtype=`` arguments (e.g. when a user attempts to create an array of a data type which is not supported by the device, we recommend raising an error instead of silently returning an array of a dtype supported by the device).
 - When a function accepts a mix of arrays and Python scalars, the scalars should inherit the device of the arrays, much like what happens with :ref:`type-promotion`.
 - Use a default for ``device=None`` which is consistent between functions within the same library.
 - If a library has multiple ways of controlling device placement, the most explicit method should have the highest priority:

src/array_api_stubs/_draft/array_object.py

@@ -669,6 +669,10 @@ def __getitem__(
         -   See :ref:`indexing` for details on supported indexing semantics.
         -   When ``__getitem__`` is defined on an object, Python will automatically define iteration (i.e., the behavior from ``iter(x)``) as  ``x[0]``, ``x[1]``, ..., ``x[N-1]``. This can also be implemented directly by defining ``__iter__``. Therefore, for a one-dimensional array ``x``, iteration should produce a sequence of zero-dimensional arrays ``x[0]``, ``x[1]``, ..., ``x[N-1]``, where ``N`` is the number of elements in the array. Iteration behavior for arrays having zero dimensions or more than one dimension is unspecified and thus implementation-defined.
 
+            .. note::
+               When ``key`` contains integer arrays on a device different from the device of ``self``, the
+               behavior is unspecified and thus implementation-defined.
+
         .. versionchanged:: 2024.12
             Clarified that iteration is defined for one-dimensional arrays.
         """
@@ -1154,6 +1158,10 @@ def __setitem__(
             .. note::
                Indexing semantics when ``key`` is an integer array or a tuple of integers and integer arrays is currently unspecified and thus implementation-defined. This will be revisited in a future revision of this standard.
 
+            .. note::
+               When ``value`` is an array on a device different from the device of ``self``, the
+               behavior is unspecified and thus implementation-defined.
+
         -   Setting array values must not affect the data type of ``self``.
         -   ``value`` must be promoted to the data type of ``self`` according to :ref:`type-promotion`. If this is not supported according to :ref:`type-promotion`, behavior is unspecified and thus implementation-defined.