docs: allow per-device dtype subsets

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,9 @@ 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 support at least one data type
+from each :ref:`category <data-type-categories>`.
+
 Data type objects must have the following methods (no attributes are required):
 
 ..

spec/draft/design_topics/device_support.rst

@@ -77,6 +77,9 @@ 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: