Add specification for asarray

[rgommers]

Closes gh-122

See gh-122 for a discussion on the order= keyword. The majority opinion there is not to add it, but it's not 100% clear cut.

Also, I did add memoryview as a supported input type, which wasn't considered in the discussion in gh-122. (EDIT: removed again, captured by SupportsBufferProtocol).

[shoyer]

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.

[rgommers]

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.

[rgommers]

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.

[rgommers]

One point made for why order= is useful to include (by @kkraus14): a common use case is to create 2-D arrays with order='F' and then turn them into a dataframe - Fortran ordering will ensure columns are contiguous; otherwise copies may need to be made.

order= is always only ever a performance optimization, it does not change interpretation of data like nested lists.

It doesn't make sense to add order= only to asarray though, it'd need to be added to all array creation functions (zeros, ones`, etc.) - and we had previously decided against it.

[shoyer]

My personal opinion is that if you need those sorts of optimizations, you should use library specific APIs, perhaps with generic APIs as a fallback. Whether this makes sense depends on lots of details, e.g., the particular way that the dataframe library manages memory.

…

On Fri, Feb 19, 2021 at 11:19 AM Ralf Gommers ***@***.***> wrote: One point made for why order= is useful to include (by @kkraus14 <https://github.com/kkraus14>): a common use case is to create 2-D arrays with order='F' and then turn them into a dataframe - Fortran ordering will ensure columns are contiguous; otherwise copies may need to be made. order= is always only ever a performance optimization, it does not change interpretation of data like nested lists. It doesn't make sense to add order= only to asarray though, it'd need to be added to all array creation functions (zeros, ones`, etc.) - and we had previously decided against it. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#130 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAJJFVRKOVQ2EZ6SQ25HUKDS722TXANCNFSM4XY7RI5Q> .

[rgommers]

My personal opinion is that if you need those sorts of optimizations, you should use library specific APIs, perhaps with generic APIs as a fallback. Whether this makes sense depends on lots of details, e.g., the particular way that the dataframe library manages memory.

True indeed.

We don't have order= in other array creation functions - it can be considered separately for all of them, but shouldn't be a blocker for getting asarray in. I'll merge this. Thanks for the review @shoyer