From f3181833b9734c6b9911d3d2f82708bd01f77a84 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 3 Nov 2022 01:34:49 -0700 Subject: [PATCH 01/10] Add specification for `is_type` --- .../array_api/data_type_functions.py | 32 ++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/spec/API_specification/array_api/data_type_functions.py b/spec/API_specification/array_api/data_type_functions.py index 0e07e818c..b2ecf2d9b 100644 --- a/spec/API_specification/array_api/data_type_functions.py +++ b/spec/API_specification/array_api/data_type_functions.py @@ -117,6 +117,36 @@ def iinfo(type: Union[dtype, array], /) -> iinfo_object: integer data type. """ +def is_type(dtype: dtype, kind: Union[dtype, str, tuple[Union[dtype, str], ...]]) -> bool: + """ + Returns a boolean indicating whether a provided dtype is of a specified data type "kind". + + Parameters + ---------- + dtype: dtype + the input dtype. + kind: Union[str, dtype, tuple[Union[str, dtype], ...]] + data type kind. + + - If ``kind`` is a dtype, the function must return a boolean indicating whether the input ``dtype`` is equal to the dtype specified by ``kind``. + - If ``kind`` is a string, the function must return a boolean indicating whether the input ``dtype`` is of a specified data type kind. The following dtype kinds must be supported: + + - **bool**: boolean data types (e.g., ``bool``). + - **signed integer**: signed integer data types (e.g., ``int8``, ``int16``, ``int32``, ``int64``). + - **unsigned integer**: unsigned integer data types (e.g., ``uint8``, ``uint16``, ``uint32``, ``uint64``). + - **integer**: integer data types. Shorthand for ``('signed integer', 'unsigned integer')``. + - **real**: real-valued floating-point data types (e.g., ``float32``, ``float64``). + - **complex**: complex floating-point data types (e.g., ``complex64``, ``complex128``). + - **numeric**: numeric data types. Shorthand for ``('integer', 'real', 'complex')``. + + - If ``kind`` is a tuple, the tuple specifies a union of dtypes and/or kinds, and the function must return a boolean indicating whether the input ``dtype`` is either equal to a specified dtype or belongs to at least one specified data type kind. + + Returns + ------- + out: bool + boolean indicating whether a provided dtype is of a specified data type kind. + """ + def result_type(*arrays_and_dtypes: Union[array, dtype]) -> dtype: """ Returns the dtype that results from applying the type promotion rules (see :ref:`type-promotion`) to the arguments. @@ -135,4 +165,4 @@ def result_type(*arrays_and_dtypes: Union[array, dtype]) -> dtype: the dtype resulting from an operation involving the input arrays and dtypes. """ -__all__ = ['astype', 'can_cast', 'finfo', 'iinfo', 'result_type'] +__all__ = ['astype', 'can_cast', 'finfo', 'iinfo', 'is_type', 'result_type'] From 99dd63a5113dd3e8f02c715c7e69c4b0106a5113 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 3 Nov 2022 01:50:07 -0700 Subject: [PATCH 02/10] Update toc --- spec/API_specification/data_type_functions.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/spec/API_specification/data_type_functions.rst b/spec/API_specification/data_type_functions.rst index d58e438a9..3c06df9d8 100644 --- a/spec/API_specification/data_type_functions.rst +++ b/spec/API_specification/data_type_functions.rst @@ -22,4 +22,5 @@ Objects in API can_cast finfo iinfo + is_type result_type From 9e876e640b38cdd91bde53e8904362801086725f Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 3 Nov 2022 01:56:26 -0700 Subject: [PATCH 03/10] Fix typing --- spec/API_specification/array_api/data_type_functions.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/array_api/data_type_functions.py b/spec/API_specification/array_api/data_type_functions.py index b2ecf2d9b..59b341bcd 100644 --- a/spec/API_specification/array_api/data_type_functions.py +++ b/spec/API_specification/array_api/data_type_functions.py @@ -1,4 +1,4 @@ -from ._types import Union, array, dtype, finfo_object, iinfo_object +from ._types import Union, Tuple, array, dtype, finfo_object, iinfo_object def astype(x: array, dtype: dtype, /, *, copy: bool = True) -> array: """ @@ -117,7 +117,7 @@ def iinfo(type: Union[dtype, array], /) -> iinfo_object: integer data type. """ -def is_type(dtype: dtype, kind: Union[dtype, str, tuple[Union[dtype, str], ...]]) -> bool: +def is_type(dtype: dtype, kind: Union[dtype, str, Tuple[Union[dtype, str], ...]]) -> bool: """ Returns a boolean indicating whether a provided dtype is of a specified data type "kind". @@ -125,7 +125,7 @@ def is_type(dtype: dtype, kind: Union[dtype, str, tuple[Union[dtype, str], ...]] ---------- dtype: dtype the input dtype. - kind: Union[str, dtype, tuple[Union[str, dtype], ...]] + kind: Union[str, dtype, Tuple[Union[str, dtype], ...]] data type kind. - If ``kind`` is a dtype, the function must return a boolean indicating whether the input ``dtype`` is equal to the dtype specified by ``kind``. From b3de736bf6c79f9b94a1fed07c4d9933e9e67839 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 21 Nov 2022 02:11:01 -0800 Subject: [PATCH 04/10] Update specification based on review feedback --- .../array_api/data_type_functions.py | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/spec/API_specification/array_api/data_type_functions.py b/spec/API_specification/array_api/data_type_functions.py index 142c9214b..7e5d10336 100644 --- a/spec/API_specification/array_api/data_type_functions.py +++ b/spec/API_specification/array_api/data_type_functions.py @@ -127,7 +127,7 @@ def iinfo(type: Union[dtype, array], /) -> iinfo_object: integer data type. """ -def is_type(dtype: dtype, kind: Union[dtype, str, Tuple[Union[dtype, str], ...]]) -> bool: +def is_dtype(dtype: dtype, kind: Union[dtype, str, Tuple[Union[dtype, str], ...]]) -> bool: """ Returns a boolean indicating whether a provided dtype is of a specified data type "kind". @@ -144,13 +144,16 @@ def is_type(dtype: dtype, kind: Union[dtype, str, Tuple[Union[dtype, str], ...]] - **bool**: boolean data types (e.g., ``bool``). - **signed integer**: signed integer data types (e.g., ``int8``, ``int16``, ``int32``, ``int64``). - **unsigned integer**: unsigned integer data types (e.g., ``uint8``, ``uint16``, ``uint32``, ``uint64``). - - **integer**: integer data types. Shorthand for ``('signed integer', 'unsigned integer')``. - - **real**: real-valued floating-point data types (e.g., ``float32``, ``float64``). - - **complex**: complex floating-point data types (e.g., ``complex64``, ``complex128``). + - **integral**: integer data types. Shorthand for ``('signed integer', 'unsigned integer')``. + - **real floating**: real-valued floating-point data types (e.g., ``float32``, ``float64``). + - **complex floating**: complex floating-point data types (e.g., ``complex64``, ``complex128``). - **numeric**: numeric data types. Shorthand for ``('integer', 'real', 'complex')``. - If ``kind`` is a tuple, the tuple specifies a union of dtypes and/or kinds, and the function must return a boolean indicating whether the input ``dtype`` is either equal to a specified dtype or belongs to at least one specified data type kind. + .. note:: + A conforming implementation of the array API standard is **not** limited to only including the dtypes described in this specification in the required data type kinds. For example, implementations supporting ``float16`` and ``bfloat16`` can include ``float16`` and ``bfloat16`` in the ``real floating`` data type kind. Similarly, implementations supporting ``int128`` can include ``int128`` in both ``signed integer`` and ``integral`` data type kinds. + Returns ------- out: bool @@ -175,4 +178,4 @@ def result_type(*arrays_and_dtypes: Union[array, dtype]) -> dtype: the dtype resulting from an operation involving the input arrays and dtypes. """ -__all__ = ['astype', 'can_cast', 'finfo', 'iinfo', 'is_type', 'result_type'] +__all__ = ['astype', 'can_cast', 'finfo', 'iinfo', 'is_dtype', 'result_type'] From b3d9ef84a68a48ac2f49fca83ead86d94438ed50 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 21 Nov 2022 02:18:02 -0800 Subject: [PATCH 05/10] Update copy and fix index --- spec/API_specification/array_api/data_type_functions.py | 2 +- spec/API_specification/data_type_functions.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/array_api/data_type_functions.py b/spec/API_specification/array_api/data_type_functions.py index 7e5d10336..de186fde4 100644 --- a/spec/API_specification/array_api/data_type_functions.py +++ b/spec/API_specification/array_api/data_type_functions.py @@ -152,7 +152,7 @@ def is_dtype(dtype: dtype, kind: Union[dtype, str, Tuple[Union[dtype, str], ...] - If ``kind`` is a tuple, the tuple specifies a union of dtypes and/or kinds, and the function must return a boolean indicating whether the input ``dtype`` is either equal to a specified dtype or belongs to at least one specified data type kind. .. note:: - A conforming implementation of the array API standard is **not** limited to only including the dtypes described in this specification in the required data type kinds. For example, implementations supporting ``float16`` and ``bfloat16`` can include ``float16`` and ``bfloat16`` in the ``real floating`` data type kind. Similarly, implementations supporting ``int128`` can include ``int128`` in both ``signed integer`` and ``integral`` data type kinds. + A conforming implementation of the array API standard is **not** limited to only including the dtypes described in this specification in the required data type kinds. For example, implementations supporting ``float16`` and ``bfloat16`` can include ``float16`` and ``bfloat16`` in the ``real floating`` data type kind. Similarly, implementations supporting ``int128`` can include ``int128`` in the ``signed integer`` data type kind. Returns ------- diff --git a/spec/API_specification/data_type_functions.rst b/spec/API_specification/data_type_functions.rst index 3c06df9d8..fe89b0b17 100644 --- a/spec/API_specification/data_type_functions.rst +++ b/spec/API_specification/data_type_functions.rst @@ -22,5 +22,5 @@ Objects in API can_cast finfo iinfo - is_type + is_dtype result_type From 467e38ba024cb89b21a7dd57268829cb4f90a888 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 21 Nov 2022 02:24:53 -0800 Subject: [PATCH 06/10] Rename function --- spec/API_specification/array_api/data_type_functions.py | 4 ++-- spec/API_specification/data_type_functions.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/array_api/data_type_functions.py b/spec/API_specification/array_api/data_type_functions.py index de186fde4..b8234f855 100644 --- a/spec/API_specification/array_api/data_type_functions.py +++ b/spec/API_specification/array_api/data_type_functions.py @@ -127,7 +127,7 @@ def iinfo(type: Union[dtype, array], /) -> iinfo_object: integer data type. """ -def is_dtype(dtype: dtype, kind: Union[dtype, str, Tuple[Union[dtype, str], ...]]) -> bool: +def isdtype(dtype: dtype, kind: Union[dtype, str, Tuple[Union[dtype, str], ...]]) -> bool: """ Returns a boolean indicating whether a provided dtype is of a specified data type "kind". @@ -178,4 +178,4 @@ def result_type(*arrays_and_dtypes: Union[array, dtype]) -> dtype: the dtype resulting from an operation involving the input arrays and dtypes. """ -__all__ = ['astype', 'can_cast', 'finfo', 'iinfo', 'is_dtype', 'result_type'] +__all__ = ['astype', 'can_cast', 'finfo', 'iinfo', 'isdtype', 'result_type'] diff --git a/spec/API_specification/data_type_functions.rst b/spec/API_specification/data_type_functions.rst index fe89b0b17..d42968c7b 100644 --- a/spec/API_specification/data_type_functions.rst +++ b/spec/API_specification/data_type_functions.rst @@ -22,5 +22,5 @@ Objects in API can_cast finfo iinfo - is_dtype + isdtype result_type From f30db3533f94fe1fbd4cf450de67a8558e74b9a7 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 21 Nov 2022 02:32:55 -0800 Subject: [PATCH 07/10] Update note --- spec/API_specification/array_api/data_type_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/array_api/data_type_functions.py b/spec/API_specification/array_api/data_type_functions.py index b8234f855..5f996e8dd 100644 --- a/spec/API_specification/array_api/data_type_functions.py +++ b/spec/API_specification/array_api/data_type_functions.py @@ -152,7 +152,7 @@ def isdtype(dtype: dtype, kind: Union[dtype, str, Tuple[Union[dtype, str], ...]] - If ``kind`` is a tuple, the tuple specifies a union of dtypes and/or kinds, and the function must return a boolean indicating whether the input ``dtype`` is either equal to a specified dtype or belongs to at least one specified data type kind. .. note:: - A conforming implementation of the array API standard is **not** limited to only including the dtypes described in this specification in the required data type kinds. For example, implementations supporting ``float16`` and ``bfloat16`` can include ``float16`` and ``bfloat16`` in the ``real floating`` data type kind. Similarly, implementations supporting ``int128`` can include ``int128`` in the ``signed integer`` data type kind. + A conforming implementation of the array API standard is **not** limited to only including the dtypes described in this specification in the required data type kinds. For example, implementations supporting ``float16`` and ``bfloat16`` can include ``float16`` and ``bfloat16`` in the ``real floating`` data type kind. Similarly, implementations supporting ``int128`` can include ``int128`` in the ``signed integer`` data type kind. In short, conforming implementations may extend data type kinds; however, data type kinds must remain consistent (e.g., only integer dtypes may belong to integer data type kinds and only floating-point dtypes may belong to floating-point data type kinds), and extensions must be clearly documented as such in library documentation. Returns ------- From e8840ce5462ecf20a1b4bc23d260a305916c04d7 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 21 Nov 2022 02:34:34 -0800 Subject: [PATCH 08/10] Add linebreaks --- spec/API_specification/array_api/data_type_functions.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/spec/API_specification/array_api/data_type_functions.py b/spec/API_specification/array_api/data_type_functions.py index 5f996e8dd..ce0d94ba8 100644 --- a/spec/API_specification/array_api/data_type_functions.py +++ b/spec/API_specification/array_api/data_type_functions.py @@ -152,7 +152,9 @@ def isdtype(dtype: dtype, kind: Union[dtype, str, Tuple[Union[dtype, str], ...]] - If ``kind`` is a tuple, the tuple specifies a union of dtypes and/or kinds, and the function must return a boolean indicating whether the input ``dtype`` is either equal to a specified dtype or belongs to at least one specified data type kind. .. note:: - A conforming implementation of the array API standard is **not** limited to only including the dtypes described in this specification in the required data type kinds. For example, implementations supporting ``float16`` and ``bfloat16`` can include ``float16`` and ``bfloat16`` in the ``real floating`` data type kind. Similarly, implementations supporting ``int128`` can include ``int128`` in the ``signed integer`` data type kind. In short, conforming implementations may extend data type kinds; however, data type kinds must remain consistent (e.g., only integer dtypes may belong to integer data type kinds and only floating-point dtypes may belong to floating-point data type kinds), and extensions must be clearly documented as such in library documentation. + A conforming implementation of the array API standard is **not** limited to only including the dtypes described in this specification in the required data type kinds. For example, implementations supporting ``float16`` and ``bfloat16`` can include ``float16`` and ``bfloat16`` in the ``real floating`` data type kind. Similarly, implementations supporting ``int128`` can include ``int128`` in the ``signed integer`` data type kind. + + In short, conforming implementations may extend data type kinds; however, data type kinds must remain consistent (e.g., only integer dtypes may belong to integer data type kinds and only floating-point dtypes may belong to floating-point data type kinds), and extensions must be clearly documented as such in library documentation. Returns ------- From 3e32dd4f1308a649595e791e982741aa0df39589 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 21 Nov 2022 02:36:54 -0800 Subject: [PATCH 09/10] Fix description --- spec/API_specification/array_api/data_type_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/array_api/data_type_functions.py b/spec/API_specification/array_api/data_type_functions.py index ce0d94ba8..b2d6d92be 100644 --- a/spec/API_specification/array_api/data_type_functions.py +++ b/spec/API_specification/array_api/data_type_functions.py @@ -147,7 +147,7 @@ def isdtype(dtype: dtype, kind: Union[dtype, str, Tuple[Union[dtype, str], ...]] - **integral**: integer data types. Shorthand for ``('signed integer', 'unsigned integer')``. - **real floating**: real-valued floating-point data types (e.g., ``float32``, ``float64``). - **complex floating**: complex floating-point data types (e.g., ``complex64``, ``complex128``). - - **numeric**: numeric data types. Shorthand for ``('integer', 'real', 'complex')``. + - **numeric**: numeric data types. Shorthand for ``('integral', 'real', 'complex')``. - If ``kind`` is a tuple, the tuple specifies a union of dtypes and/or kinds, and the function must return a boolean indicating whether the input ``dtype`` is either equal to a specified dtype or belongs to at least one specified data type kind. From a2c6135bd3517d5c658dee3a18f9b8087e2564ec Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 21 Nov 2022 02:38:02 -0800 Subject: [PATCH 10/10] Fix description --- spec/API_specification/array_api/data_type_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/array_api/data_type_functions.py b/spec/API_specification/array_api/data_type_functions.py index b2d6d92be..6b1b242ae 100644 --- a/spec/API_specification/array_api/data_type_functions.py +++ b/spec/API_specification/array_api/data_type_functions.py @@ -147,7 +147,7 @@ def isdtype(dtype: dtype, kind: Union[dtype, str, Tuple[Union[dtype, str], ...]] - **integral**: integer data types. Shorthand for ``('signed integer', 'unsigned integer')``. - **real floating**: real-valued floating-point data types (e.g., ``float32``, ``float64``). - **complex floating**: complex floating-point data types (e.g., ``complex64``, ``complex128``). - - **numeric**: numeric data types. Shorthand for ``('integral', 'real', 'complex')``. + - **numeric**: numeric data types. Shorthand for ``('integral', 'real floating', 'complex floating')``. - If ``kind`` is a tuple, the tuple specifies a union of dtypes and/or kinds, and the function must return a boolean indicating whether the input ``dtype`` is either equal to a specified dtype or belongs to at least one specified data type kind.