From 225772518716accbd81cb0544fb6e2cf1cef44bc Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Wed, 17 Feb 2021 20:56:49 +0100 Subject: [PATCH 1/3] Add specification for `asarray` Closes gh-122 --- spec/API_specification/creation_functions.md | 36 ++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index cf0674404..987f54857 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -49,6 +49,42 @@ This function cannot guarantee that the interval does not include the `stop` val - a one-dimensional array containing evenly spaced values. The length of the output array must be `ceil((stop-start)/step)`. + +(function-asarray)= +### asarray(obj, /, *, dtype=None, device=None, copy=False) + +Convert the input to an array. + +#### Parameters + +- **obj**: _Union\[ float, NestedSequence\[ bool | int | float ], SupportsDLPack, SupportsBufferProtocol, memoryview ]_ + + - 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. + + :::{tip} + An object supporting DLPack has `__dlpack__` and `__dlpack_device__` methods. + An object supporting the buffer protocol can be turned into a memoryview through `memoryview(obj)`. + ::: + +- **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`. Default: `None`. + +- **device**: _Optional\[ <device> ]_ + + - device to place the created array on, if given. Default: `None`. + +- **copy**: _bool_ + + - Whether or not to make a copy of the input. If `True`, always copies. If `False`, reuses existing memory buffer if possible. Default: `False`. + +#### Returns + +- **out**: _<array>_ + + - An array containing the data from `obj`. + + (function-empty)= ### empty(shape, /, *, dtype=None, device=None) From 82c788e64a0b4e0d11a11cc0e5f6a295af099d39 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Wed, 17 Feb 2021 23:33:19 +0100 Subject: [PATCH 2/3] Update copy= keyword for asarray --- spec/API_specification/creation_functions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 987f54857..7f72200af 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -51,7 +51,7 @@ This function cannot guarantee that the interval does not include the `stop` val (function-asarray)= -### asarray(obj, /, *, dtype=None, device=None, copy=False) +### asarray(obj, /, *, dtype=None, device=None, copy=None) Convert the input to an array. @@ -76,7 +76,7 @@ Convert the input to an array. - **copy**: _bool_ - - Whether or not to make a copy of the input. If `True`, always copies. If `False`, reuses existing memory buffer if possible. Default: `False`. + - Whether or not to make a copy of the input. If `True`, always copies. If `False`, never copies. If `None`, reuses existing memory buffer if possible. Default: `None`. #### Returns From 1a715c010490c860bb2bbcd059afaf1fea2a5ddf Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Thu, 18 Feb 2021 14:51:25 +0100 Subject: [PATCH 3/3] Address review comments on copy keyword --- spec/API_specification/creation_functions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 7f72200af..a97e24f7f 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -57,7 +57,7 @@ Convert the input to an array. #### Parameters -- **obj**: _Union\[ float, NestedSequence\[ bool | int | float ], SupportsDLPack, SupportsBufferProtocol, memoryview ]_ +- **obj**: _Union\[ 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. @@ -74,9 +74,9 @@ Convert the input to an array. - device to place the created array on, if given. Default: `None`. -- **copy**: _bool_ +- **copy**: _Optional\[ bool ]_ - - Whether or not to make a copy of the input. If `True`, always copies. If `False`, never copies. If `None`, reuses existing memory buffer if possible. Default: `None`. + - 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`. #### Returns