Merge pull request #21133 from seberg/doc-subclasses

DOC: Note interop from "subclassing" docs and explain when to avoid

2 files changed, 45 insertions, 0 deletions

diff --git a/doc/source/user/basics.interoperability.rst b/doc/source/user/basics.interoperability.rst
index 668058a9c..11fe18a04 100644
--- a/doc/source/user/basics.interoperability.rst
+++ b/doc/source/user/basics.interoperability.rst
@@ -1,4 +1,6 @@
 
+.. _basics.interoperability:
+
 ***************************
 Interoperability with NumPy
 ***************************
diff --git a/doc/source/user/basics.subclassing.rst b/doc/source/user/basics.subclassing.rst
index cee794b8c..7b97abab7 100644
--- a/doc/source/user/basics.subclassing.rst
+++ b/doc/source/user/basics.subclassing.rst
@@ -31,6 +31,49 @@ things like array slicing.  The complications of subclassing ndarray are
 due to the mechanisms numpy has to support these latter two routes of
 instance creation.
 
+When to use subclassing
+=======================
+
+Besides the additional complexities of subclassing a NumPy array, subclasses
+can run into unexpected behaviour because some functions may convert the
+subclass to a baseclass and "forget" any additional information
+associated with the subclass.
+This can result in surprising behavior if you use NumPy methods or
+functions you have not explicitly tested.
+
+On the other hand, compared to other interoperability approaches,
+subclassing can be a useful because many thing will "just work".
+
+This means that subclassing can be a convenient approach and for a long time
+it was also often the only available approach.
+However, NumPy now provides additional interoperability protocols described
+in ":ref:`Interoperability with NumPy <basics.interoperability>`".
+For many use-cases these interoperability protocols may now be a better fit
+or supplement the use of subclassing.
+
+Subclassing can be a good fit if:
+
+* you are less worried about maintainability or users other than yourself:
+  Subclass will be faster to implement and additional interoperability
+  can be added "as-needed".  And with few users, possible surprises are not
+  an issue.
+* you do not think it is problematic if the subclass information is
+  ignored or lost silently.  An example is ``np.memmap`` where "forgetting"
+  about data being memory mapped cannot lead to a wrong result.
+  An example of a subclass that sometimes confuses users are NumPy's masked
+  arrays.  When they were introduced, subclassing was the only approach for
+  implementation.  However, today we would possibly try to avoid subclassing
+  and rely only on interoperability protocols.
+
+Note that also subclass authors may wish to study
+:ref:`Interoperability with NumPy <basics.interoperability>`
+to support more complex use-cases or work around the surprising behavior.
+
+``astropy.units.Quantity`` and ``xarray`` are examples for array-like objects
+that interoperate well with NumPy.  Astropy's ``Quantity`` is an example
+which uses a dual approach of both subclassing and interoperability protocols.
+
+
 .. _view-casting:
 
 View casting