DOC: __array__ accepts a dtype argument

[rsokl]

The documentation for writing custom array containers should indicate that the __array__ interface accepts an optional dtype parameter.

In the present docs, the example class has a bug lurking:

class DiagonalArray:
    def __init__(self, N, value):
        self._N = N
        self._i = value
    def __repr__(self):
        return f"{self.__class__.__name__}(N={self._N}, value={self._i})"
    def __array__(self):
        return self._i * np.eye(self._N)

>>> arr = DiagonalArray(4, 2)
>>> np.asarray(arr, dtype=np.float32)
TypeError: __array__() takes 1 positional argument but 2 were given

[mattip]

The documentation for the __array__ function is not very descriptive. It describes what the ufunc will not do if __array__ is present. It should describe what the prospective __array__ user is expected to do with self and optional dtype. That would be nice to expand upon here or in a follow-up PR.

[rsokl]

Agreed @mattip - in fact the documentation is so unclear, that I am not even sure what it is saying! Thus I am afraid that I might not be the one to come up with better wording.

[seberg]

If you are up for it, that would be great anyway, we can always iterate together (no pressure though). The only subtlety I can really think of, is that it should be completely fine to ignore dtype which would just trigger casting in NumPy itself.

[mattip]

OK, let's put this in as-is, it is a good first step.

[mattip]

Thanks @rsokl