From acff379282f93f400d249de144bc3b62d4a5556e Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 20 Sep 2023 19:50:12 -0700 Subject: [PATCH 1/2] Add `device` kwarg support to `can_cast` and `result_type` --- .../_draft/data_type_functions.py | 25 ++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/src/array_api_stubs/_draft/data_type_functions.py b/src/array_api_stubs/_draft/data_type_functions.py index 81d518807..ef7357144 100644 --- a/src/array_api_stubs/_draft/data_type_functions.py +++ b/src/array_api_stubs/_draft/data_type_functions.py @@ -60,7 +60,13 @@ def astype( """ -def can_cast(from_: Union[dtype, array], to: dtype, /) -> bool: +def can_cast( + from_: Union[dtype, array], + to: dtype, + /, + *, + device: Optional[device] = None, +) -> bool: """ Determines if one data type can be cast to another data type according :ref:`type-promotion` rules. @@ -70,11 +76,16 @@ def can_cast(from_: Union[dtype, array], to: dtype, /) -> bool: input data type or array from which to cast. to: dtype desired data type. + device: Optional[device] + device on which to perform a cast. If ``device`` is ``None``, the function must apply :ref:`type-promotion` rules irrespective of device capabilities. If ``device`` is a device object, the function must determine whether a cast can be performed on the specified device. Default: ``None``. + + .. note:: + While specification-conforming array libraries are expected to support all data types included in this specification, array libraries may support devices which do not have full data type support. Accordingly, the inclusion of a ``device`` keyword argument allows downstream array API consumers to test casting support for particular devices. Returns ------- out: bool - ``True`` if the cast can occur according to :ref:`type-promotion` rules; otherwise, ``False``. + ``True`` if the cast is possible; otherwise, ``False``. """ @@ -206,7 +217,10 @@ def isdtype( """ -def result_type(*arrays_and_dtypes: Union[array, dtype]) -> dtype: +def result_type( + *arrays_and_dtypes: Union[array, dtype], + device: Optional[device] = None, +) -> dtype: """ Returns the dtype that results from applying the type promotion rules (see :ref:`type-promotion`) to the arguments. @@ -217,6 +231,11 @@ def result_type(*arrays_and_dtypes: Union[array, dtype]) -> dtype: ---------- arrays_and_dtypes: Union[array, dtype] an arbitrary number of input arrays and/or dtypes. + device: Optional[device] + device on which to apply type promotion rules. If ``device`` is ``None``, the function must apply :ref:`type-promotion` rules irrespective of device capabilities. If ``device`` is a device object, the function must apply type promotion rules with respect to the specified device. Default: ``None``. + + .. note:: + While specification-conforming array libraries are expected to support all data types included in this specification, array libraries may support devices which do not have full data type support. Accordingly, the inclusion of a ``device`` keyword argument allows downstream array API consumers to apply type promotions with respect to particular devices. Returns ------- From b4b11054e87ab7766f9ec734725e012a4624e82b Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 20 Sep 2023 19:58:27 -0700 Subject: [PATCH 2/2] Update copy --- src/array_api_stubs/_draft/data_type_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/array_api_stubs/_draft/data_type_functions.py b/src/array_api_stubs/_draft/data_type_functions.py index ef7357144..448bb0855 100644 --- a/src/array_api_stubs/_draft/data_type_functions.py +++ b/src/array_api_stubs/_draft/data_type_functions.py @@ -85,7 +85,7 @@ def can_cast( Returns ------- out: bool - ``True`` if the cast is possible; otherwise, ``False``. + ``True`` if the cast can occur; otherwise, ``False``. """