10000 Merge pull request #13633 from shoyer/nep-18-subclass-warning · numpy/numpy@9c44a2d · GitHub
[go: up one dir, main page]

Skip to content

Commit 9c44a2d

Browse files
authored
Merge pull request #13633 from shoyer/nep-18-subclass-warning
DOC: caution against relying upon NumPy's implementation in subclasses
2 parents a8313fe + 5e8a4a1 commit 9c44a2d

File tree

1 file changed

+12
-4
lines changed

1 file changed

+12
-4
lines changed

doc/neps/nep-0018-array-function-protocol.rst

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -349,19 +349,27 @@ with ``__array_ufunc__``, so ``numpy.ndarray`` also defines a
349349
350350
This method matches NumPy's dispatching rules, so for most part it is
351351
possible to pretend that ``ndarray.__array_function__`` does not exist.
352+
The private ``_implementation`` attribute, defined below in the
353+
``array_function_dispatch`` decorator, allows us to avoid the special cases for
354+
NumPy arrays that were needed in the ``__array_ufunc__`` protocol.
352355

353356
The ``__array_function__`` protocol always calls subclasses before
354357
superclasses, so if any ``ndarray`` subclasses are involved in an operation,
355358
they will get the chance to override it, just as if any other argument
356-
overrides ``__array_function__``. However, the default behavior in an operation
359+
overrides ``__array_function__``. But the default behavior in an operation
357360
that combines a base NumPy array and a subclass is different: if the subclass
358361
returns ``NotImplemented``, NumPy's implementation of the function will be
359362
called instead of raising an exception. This is appropriate since subclasses
360363
are `expected to be substitutable <https://en.wikipedia.org/wiki/Liskov_substitution_principle>`_.
361364

362-
Note that the private ``_implementation`` attribute, defined below in the
363-
``array_function_dispatch`` decorator, allows us to avoid the special cases for
364-
NumPy arrays that were needed in the ``__array_ufunc__`` protocol.
365+
We still caution authors of subclasses to exercise caution when relying
366+
upon details of NumPy's internal implementations. It is not always possible to
367+
write a perfectly substitutable ndarray subclass, e.g., in cases involving the
368+
creation of new arrays, not least because NumPy makes use of internal
369+
optimizations specialized to base NumPy arrays, e.g., code written in C. Even
370+
if NumPy's implementation happens to work today, it may not work in the future.
371+
In these cases, your recourse is to re-implement top-level NumPy functions via
372+
``__array_function__`` on your subclass.
365373

366374
Changes within NumPy functions
367375
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

0 commit comments

Comments
 (0)
0