From 5e8a4a11a900d9427368fe1f10c8086290ff01f1 Mon Sep 17 00:00:00 2001 From: Stephan Hoyer Date: Sun, 26 May 2019 16:12:26 -0700 Subject: [PATCH] DOC: caution against relying upon NumPy's implementation in subclasses I think this is an important warning to include for subclass authors. Otherwise, we will be expanding our exposure of internal APIs as part of ``__array_function__``. All things being equal, it's great when things "just work" subclasses, but I don't want to guarantee it. In particular, I would be very displeased if ``__array_function__`` leads to NumPy adding more subclass specific hacks like always calling ``mean()`` inside ``median()`` (GH-3846). mhvk: please take a look. --- doc/neps/nep-0018-array-function-protocol.rst | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/doc/neps/nep-0018-array-function-protocol.rst b/doc/neps/nep-0018-array-function-protocol.rst index 01bd22522695..27a462239189 100644 --- a/doc/neps/nep-0018-array-function-protocol.rst +++ b/doc/neps/nep-0018-array-function-protocol.rst @@ -349,19 +349,27 @@ with ``__array_ufunc__``, so ``numpy.ndarray`` also defines a This method matches NumPy's dispatching rules, so for most part it is possible to pretend that ``ndarray.__array_function__`` does not exist. +The private ``_implementation`` attribute, defined below in the +``array_function_dispatch`` decorator, allows us to avoid the special cases for +NumPy arrays that were needed in the ``__array_ufunc__`` protocol. The ``__array_function__`` protocol always calls subclasses before superclasses, so if any ``ndarray`` subclasses are involved in an operation, they will get the chance to override it, just as if any other argument -overrides ``__array_function__``. However, the default behavior in an operation +overrides ``__array_function__``. But the default behavior in an operation that combines a base NumPy array and a subclass is different: if the subclass returns ``NotImplemented``, NumPy's implementation of the function will be called instead of raising an exception. This is appropriate since subclasses are `expected to be substitutable `_. -Note that the private ``_implementation`` attribute, defined below in the -``array_function_dispatch`` decorator, allows us to avoid the special cases for -NumPy arrays that were needed in the ``__array_ufunc__`` protocol. +We still caution authors of subclasses to exercise caution when relying +upon details of NumPy's internal implementations. It is not always possible to +write a perfectly substitutable ndarray subclass, e.g., in cases involving the +creation of new arrays, not least because NumPy makes use of internal +optimizations specialized to base NumPy arrays, e.g., code written in C. Even +if NumPy's implementation happens to work today, it may not work in the future. +In these cases, your recourse is to re-implement top-level NumPy functions via +``__array_function__`` on your subclass. Changes within NumPy functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^