Repository: dask/dask

Issue:
Rename `is_arraylike` to `is_duck_array`
Based on some recent discussion, in particular this comment ( https://github.com/dask/dask/pull/7321#issuecomment-791243195 ), it would be good to rename `is_arraylike` to `is_duck_array` for clarity and possibly update the docstring of this function to reflect its intended usage.

cc @shoyer @pentschev @jrbourbeau


Discussion:
I think we need to have more discussion about this proposal especially since there are other methods that might benefit from a rename  `is_dataframe_like`.

@dask/maintenance for visibility

@jsignell and I were talking through this a bit and thought about adding to the docstring something along the lines of:

```
    This function tests specifically for an object that already has array
    attributes (e.g. np.ndarray, dask.array.Array), not for something that
    can be coerced into an array object (e.g. Python lists and tuples)
```

Any thoughts on this?
Beyond that, a quick
```
fd -t f -x gsed -i -e 's/is_arraylike/is_duck_array/g' {} \;
```
does the trick to rename all occurrences to `is_duck_array`, is more discussion around this necessary or would a PR be the next step?
@shoyer @pentschev @jrbourbeau, any more thoughts here? 🙂
I'm fine with changing that as per @douglasdavis' proposal. However, I often forget about small details so it'd be great to hear from @shoyer and @jrbourbeau if they see anything missing.
Remind me what the use case for this function inside dask is?

If it's specifically for testing valid duck array types to return from computing a dask array, then this looks right to me.

With regards to the proposed docstring addition: it seems a little funny to include pandas.Series as an example of a "duck array" because it doesn't work like a numpy.ndarray object. Nor does pandas.Series implement `__array_function__` (at least not yet, and perhaps not ever): https://github.com/pandas-dev/pandas/issues/26380
Stephan Hoyer ***@***.***> writes:

> With regards to the proposed docstring addition: it seems a little
> funny to include pandas.Series as an example of a "duck array" because
> it doesn't work like a numpy.ndarray object. Nor does pandas.Series
> implement __array_function__ (at least not yet, and perhaps not ever):
> pandas-dev/pandas#26380

Mistake on my end, thanks for pointing that out.

I had to search a bit through docs to find rationale here.  Apparently numpy uses the term "array-like" to mean "anything that could be coerced into an array, like a list".  Quote from numpy docs:

> “Duck array” works fine as a placeholder for now, but it’s pretty jargony and may confuse new users, so we may want to pick something else for the actual API functions. Unfortunately, “array-like” is already taken for the concept of “anything that can be coerced into an array” (including e.g. list objects), 

If there isn't a great pressing need here I'm inclined to just keep this as it is.  I understand that we conflict a bit with an internal nuance of Numpy's naming, but "duck array" seems only interpretable to a select few of us.  I don't think that it's a good name.  I think that it's more likely that a new dev will be confused by "duck array" than by "is_arraylike", so if this isn't blocking anyone's productivity today I recommend that we keep things as we are.
> I recommend that we keep things as we are

That sounds good to me. In that case, I think it'd be helpful to include a sentence in @douglasdavis's proposed docstring that points out this inconsistency with what numpy means by `array_like`.
+1 expanding the `is_arraylike` docstring sounds great 
I think we can be very verbose in that docstring since it's mostly targetting other dask developers and developers of downstream libraries ( aka not normal users)

Resolving patch:
diff --git a/dask/utils.py b/dask/utils.py
--- a/dask/utils.py
+++ b/dask/utils.py
@@ -1111,6 +1111,17 @@ def partial_by_order(*args, **kwargs):
 def is_arraylike(x):
     """Is this object a numpy array or something similar?
 
+    This function tests specifically for an object that already has
+    array attributes (e.g. np.ndarray, dask.array.Array, cupy.ndarray,
+    sparse.COO), **NOT** for something that can be coerced into an
+    array object (e.g. Python lists and tuples). It is meant for dask
+    developers and developers of downstream libraries.
+
+    Note that this function does not correspond with NumPy's
+    definition of array_like, which includes any object that can be
+    coerced into an array (see definition in the NumPy glossary):
+    https://numpy.org/doc/stable/glossary.html
+
     Examples
     --------
     >>> import numpy as np


Test patch: