Skip to content

Add specification for asarray #130

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Feb 21, 2021
Merged
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions spec/API_specification/creation_functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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=None)

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`, never copies. If `None`, reuses existing memory buffer if possible. Default: `None`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is probably a good idea to specify the specific exception (i.e., ValueError) that is raised when an otherwise valid input would require a copy.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We've tried to avoid that in other places, but this particular may be so often needed when writing library code with copy=False that it makes sense to add.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added: "Must raise ValueError if copying of inputs which support DLPack or the buffer protocol is necessary and copy=False."

Data in sequence input is still copied of course.


#### Returns

- **out**: _<array>_

- An array containing the data from `obj`.


(function-empty)=
### empty(shape, /, *, dtype=None, device=None)

Expand Down