DOC: Document array_function at a higher level. #13979
Conversation
|
CircleCI is complaining. |
| Subclassing a ``numpy.ndarray`` is possible but if your goal is to create an | ||
| array with *modified* behavior, as do dask arrays for distributed computation | ||
| and cupy arrays for GPU-based computation, subclassing is discouraged. Instead, | ||
| using numpy's :ref:`dispatch mechanism <basics.dispatch>`_ is recommended. |
There was a problem hiding this comment.
The trailing _ (signifying an external link) is not needed, it clashes with the leading :ref: which requests sphinx to create an link to internal documentation
| provides all argument types with an ``'__array_function__'`` attribute. | ||
| This allows implementors to quickly identify cases where they should defer | ||
| to ``__array_function__`` implementations on other arguments. | ||
| Implementaitons should not rely on the iteration order of ``types``. |
| - If all ``__array_function__`` methods return ``NotImplemented``, | ||
| NumPy will raise ``TypeError``. | ||
|
|
||
| If no ``__array_function__`` methods exist, NumPy will default to calling |
There was a problem hiding this comment.
Wow, thank you @danielballan, this is a really fantastic start!
I have a few minor suggestions, but I agree that we should try to merge this ASAP so that we have some documentation rather than none!
| end. One way to simplify the question is by asking yourself if the | ||
| object you are interested in can be replaced as a single array or does | ||
| it really require two or more arrays at its core. | ||
| Subclassing a ``numpy.ndarray`` is possible but if your goal is to create an |
There was a problem hiding this comment.
I agree that the introduction to this page doesn't quite make sense, but I'm not sure this version entirely works either -- the next paragraph doesn't quite make sense without an introduction first. Maybe better to just add brief .. note:: with a link for now?
There was a problem hiding this comment.
Agreed. Reworking this properly is a bigger job. I have restored the original introduction, with only minor edits, and placed a note at the top directing users to consider dispatch instead of subclassing.
|
Thanks for the fast review, all! |
|
Thanks @danielballan . |
|
this is great, thanks again Dan! |
| - ``inputs``, which could be a mixture of different types | ||
| - ``kwargs``, keyword arguments passed to the function | ||
|
|
||
| For this example we will only handle the method ``'__call__``. |
| calls ``numpy.sum(self)``, and the same for ``mean``. | ||
|
|
||
| >>> @implements(np.sum) | ||
| ... def sum(a): |
| ... return arr._i * arr._N | ||
| ... | ||
| >>> @implements(np.mean) | ||
| ... def sum(a): |
|
@danielballan thank you so much for writing this up! 🥇 |
|
#14272 addresses the minor issues identified |
|
Thanks for the close read and cleanup, @thewtex! Glad it was helpful. |
Closes #13844
This PR adds a new document illustrating a very simple custom array container implementing
__array_ufunc__and__array_function__. It also rephrases the documentation on subclasses to direct users toward considering dispatch instead of inheritance.Additional work is needed to restructure the documentation to make this new document easier for developers to discover and to provide more context about when to choose inheritance (rarely but sometimes still the right choice) or dispatch. I propose to defer that larger effort to a separate PR and get this published soon so that some high-level documentation on
__array_function__is at least available.Feel free to take a heavy hand to this in reviewing/editing. I wrote this with the perspective of someone who has been following the
__array_function__conversation but has not thought deeply about the design.@shoyer Any input of yours on this would be especially welcome.