From 3b404e69c9cf78b35339cb7035d7ee104e0ea5d9 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 21 Oct 2021 02:18:42 -0700 Subject: [PATCH 1/5] Add astype API and restrict asarray to type promotion rules --- spec/API_specification/creation_functions.md | 20 +++++++++++--- spec/API_specification/data_type_functions.md | 26 +++++++++++++++++++ 2 files changed, 42 insertions(+), 4 deletions(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index dc0f8374f..e56705046 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -59,7 +59,7 @@ Convert the input to an array. - **obj**: _Union\[ <array>, bool, int, float, NestedSequence\[ bool | int | float ], SupportsDLPack, SupportsBufferProtocol ]_ - - Object to be converted to an array. Can be a Python scalar, a (possibly nested) sequence of Python scalars, or an object supporting DLPack or the Python buffer protocol. + - object to be converted to an array. May be a Python scalar, a (possibly nested) sequence of Python scalars, or an object supporting DLPack or the Python buffer protocol. :::{tip} An object supporting DLPack has `__dlpack__` and `__dlpack_device__` methods. @@ -68,7 +68,19 @@ Convert the input to an array. - **dtype**: _Optional\[ <dtype> ]_ - - output array data type. If `dtype` is `None`, the output array data type must be inferred from the data type(s) in `obj`. If all input values are Python scalars, then if they're all `bool` the output dtype will be `bool`; if they're a mix of `bool`s and `int` the output dtype will be the default integer data type; if they contain `float`s the output dtype will be the default floating-point data type. Default: `None`. + - output array data type. If `dtype` is `None`, the output array data type must be inferred from the data type(s) in `obj`. If all input values are Python scalars, then + + - if all values are of type `bool`, the output data type must be `bool`. + - if the values are a mixture of `bool`s and `int`, the output data type must be the default integer data type. + - if one or more values are `float`s, the output data type must be the default floating-point data type. + + Default: `None`. + + ```{note} + If `dtype` is not `None`, then array conversions should obey {ref}`type-promotion` rules. Conversions not specified according to {ref}`type-promotion` rules may or may not be permitted by a conforming array library. + + To perform an explicit cast, use {ref}`function-astype`. + ``` - **device**: _Optional\[ <device> ]_ @@ -76,13 +88,13 @@ Convert the input to an array. - **copy**: _Optional\[ bool ]_ - - Whether or not to make a copy of the input. If `True`, always copies. If `False`, never copies for input which supports DLPack or the buffer protocol, and raises `ValueError` in case that would be necessary. If `None`, reuses existing memory buffer if possible, copies otherwise. Default: `None`. + - boolean indicating whether or not to copy the input. If `True`, the function must always copy. If `False`, the function must never copy for input which supports DLPack or the buffer protocol, and raises `ValueError` in case a copy would be necessary. If `None`, the function must reuse existing memory buffer if possible and copy otherwise. Default: `None`. #### Returns - **out**: _<array>_ - - An array containing the data from `obj`. + - an array containing the data from `obj`. (function-empty)= diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md index 11f893a97..556ab67d8 100644 --- a/spec/API_specification/data_type_functions.md +++ b/spec/API_specification/data_type_functions.md @@ -7,6 +7,32 @@ A conforming implementation of the array API standard must provide and support t ## Objects in API + +(function-astype)= +### astype(x, dtype, /) + +Copies an array to a specified data type irrespective of {ref}`type-promotion` rules. + +```{note} +Casting floating-point `NaN` and `infinity` values to integral data types is not specified and implementation-dependent. +``` + +#### Parameters + +- **x**: _<array>_ + + - array to cast. + +- **dtype**: _<dtype>_ + + - desired data type. + +#### Returns + +- **out**: _<array>_ + + - an array having the specified data type. The returned array must have the same shape as `x`. + (function-broadcast_arrays)= ### broadcast_arrays(*arrays) From 88a3337c99427ea05aacac18da8e5c6c4dbb39c0 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 21 Oct 2021 02:31:22 -0700 Subject: [PATCH 2/5] Update copy --- spec/API_specification/creation_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index e56705046..6cb52aea0 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -88,7 +88,7 @@ Convert the input to an array. - **copy**: _Optional\[ bool ]_ - - boolean indicating whether or not to copy the input. If `True`, the function must always copy. If `False`, the function must never copy for input which supports DLPack or the buffer protocol, and raises `ValueError` in case a copy would be necessary. If `None`, the function must reuse existing memory buffer if possible and copy otherwise. Default: `None`. + - boolean indicating whether or not to copy the input. If `True`, the function must always copy. If `False`, the function must never copy for input which supports DLPack or the buffer protocol and must raise a `ValueError` in case a copy would be necessary. If `None`, the function must reuse existing memory buffer if possible and copy otherwise. Default: `None`. #### Returns From 3a8fa5bce166611c162dbd1bea9d2e3d2e013a76 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 21 Oct 2021 02:32:01 -0700 Subject: [PATCH 3/5] Update copy --- spec/API_specification/data_type_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md index 556ab67d8..9af976fa7 100644 --- a/spec/API_specification/data_type_functions.md +++ b/spec/API_specification/data_type_functions.md @@ -14,7 +14,7 @@ A conforming implementation of the array API standard must provide and support t Copies an array to a specified data type irrespective of {ref}`type-promotion` rules. ```{note} -Casting floating-point `NaN` and `infinity` values to integral data types is not specified and implementation-dependent. +Casting floating-point `NaN` and `infinity` values to integral data types is not specified and is implementation-dependent. ``` #### Parameters From 69d52ef8e23f607108b7d175f6a49f9f610cf853 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 1 Nov 2021 10:07:23 -0700 Subject: [PATCH 4/5] Add support for a `copy` keyword --- spec/API_specification/data_type_functions.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md index 9af976fa7..0f1dc512d 100644 --- a/spec/API_specification/data_type_functions.md +++ b/spec/API_specification/data_type_functions.md @@ -9,7 +9,7 @@ A conforming implementation of the array API standard must provide and support t ## Objects in API (function-astype)= -### astype(x, dtype, /) +### astype(x, dtype, /, *, copy=True) Copies an array to a specified data type irrespective of {ref}`type-promotion` rules. @@ -27,6 +27,10 @@ Casting floating-point `NaN` and `infinity` values to integral data types is not - desired data type. +- **copy**: _<bool>_ + + - specifies whether to copy an array when the specified `dtype` matches the data type of the input array `x`. If `True`, a newly allocated array must always be returned. If `False` and the specified `dtype` matches the data type of the input array, the input array must be returned; otherwise, a newly allocated must be returned. Default: `True`. + #### Returns - **out**: _<array>_ From 859040e37556b6c9c1222f7f31f65f406730771e Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 1 Nov 2021 10:28:59 -0700 Subject: [PATCH 5/5] Restrict `docutils` version --- requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements.txt b/requirements.txt index fa2e7d09f..5df0b2504 100644 --- a/requirements.txt +++ b/requirements.txt @@ -3,3 +3,4 @@ sphinx-material==0.0.30 myst-parser sphinx_markdown_tables sphinx_copybutton +docutils<0.18