docs: clarify that behavior when provided a nested sequence to asarray is unspecified

[ev-br]

This came up in data-apis/array-api-strict#118.

AFAICS, the behavior of asarray([array, list]) does vary by implementation and is not explicitly mentioned in the standard. Thus add a note that it's unspecified.

Due diligence:

CuPy : allows sequences of arrays, does not allows mixed sequences of arrays/scalars:

In [2]: cp.asarray(cp.asarray([1, 2, 3]))
Out[2]: array([1, 2, 3])

In [3]: cp.asarray(cp.ones(3))
Out[3]: array([1., 1., 1.])

In [4]: cp.asarray([cp.ones(3), cp.ones(3)])
Out[4]: 
array([[1., 1., 1.],
       [1., 1., 1.]])

In [5]: cp.asarray([cp.ones(3), 1])
---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
..
TypeError: Implicit conversion to a NumPy array is not allowed. Please use `.get()` to construct a NumPy array explicitly.

In [6]: cp.asarray([cp.ones(3), [1, 2, 3]])
---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
..
TypeError: Implicit conversion to a NumPy array is not allowed. Please use `.get()` to construct a NumPy array explicitly.

Torch: does not allow sequences of tensors

In [1]: import torch

In [2]: torch.as_tensor(torch.ones(3))
Out[2]: tensor([1., 1., 1.])

In [3]: torch.as_tensor([torch.ones(3), torch.ones(3)])
---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[3], line 1
----> 1 torch.as_tensor([torch.ones(3), torch.ones(3)])

ValueError: only one element tensors can be converted to Python scalars

In [4]: torch.as_tensor([torch.ones(3), 1])
---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[4], line 1
----> 1 torch.as_tensor([torch.ones(3), 1])

ValueError: only one element tensors can be converted to Python scalars

In [5]: torch.as_tensor([torch.ones(3), [1, 2, 3]])
---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[5], line 1
----> 1 torch.as_tensor([torch.ones(3), [1, 2, 3]])

ValueError: only one element tensors can be converted to Python scalars

JAX : allows sequences but not scalars

In [1]: import jax.numpy as jnp

In [2]: jnp.asarray(jnp.ones(3))
Out[2]: Array([1., 1., 1.], dtype=float32)

In [3]: jnp.asarray([jnp.ones(3), jnp.ones(3)])
Out[3]: 
Array([[1., 1., 1.],
       [1., 1., 1.]], dtype=float32)

In [4]: jnp.asarray([jnp.ones(3), 1])
---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
...
ValueError: All input arrays must have the same shape.

In [5]: jnp.asarray([jnp.ones(3), [1, 2, 3]])
Out[5]: 
Array([[1., 1., 1.],
       [1., 2., 3.]], dtype=float32)

Dask.array: as JAX.

[lucascolley]

Suggested change

	.. note::
	If ``obj`` is a sequence with some elements being arrays, the behavior is unspecified and thus implementation-defined. Conforming
	implentations may perform the conversion or raise an error.
	.. note::
	If ``obj`` is a sequence with some elements being arrays, the behavior is unspecified and thus implementation-defined. Conforming
	implentations may perform the conversion or raise an error.
	To join a sequence of arrays along a new axis, see :func:`~array_api.stack`.