ENH: Add `subok` parameter to np.copy function (cf. gfh6509) (gh-15685)

This is largely a re-submission of the original change proposed in #6509. Discussion was hosted in multiple forums including #3474, the numpy mailing list circa 10-2015, and the 02-26-2020 NumPy Triage meeting.

This PR closes #3474 and #15570

3 files changed, 28 insertions, 3 deletions

diff --git a/doc/release/upcoming_changes/15685.new_feature.rst b/doc/release/upcoming_changes/15685.new_feature.rst
new file mode 100644
index 000000000..c4ed04e93
--- /dev/null
+++ b/doc/release/upcoming_changes/15685.new_feature.rst
@@ -0,0 +1,9 @@
+``subok`` option for `numpy.copy`
+---------------------------------
+A new kwarg, ``subok``, was added to `numpy.copy` to allow users to toggle the 
+behavior of `numpy.copy` with respect to array subclasses. The default value
+is ``False`` which is consistent with the behavior of `numpy.copy` for 
+previous numpy versions. To create a copy that preserves an array subclass with
+`numpy.copy`, call ``np.copy(arr, subok=True)``. This addition better documents
+that the default behavior of `numpy.copy` differs from the 
+`numpy.ndarray.copy` method which respects array subclasses by default.
diff --git a/numpy/lib/function_base.py b/numpy/lib/function_base.py
index 47b5133be..b9f3bbb16 100644
--- a/numpy/lib/function_base.py
+++ b/numpy/lib/function_base.py
@@ -708,12 +708,12 @@ def select(condlist, choicelist, default=0):
     return result
 
 
-def _copy_dispatcher(a, order=None):
+def _copy_dispatcher(a, order=None, subok=None):
     return (a,)
 
 
 @array_function_dispatch(_copy_dispatcher)
-def copy(a, order='K'):
+def copy(a, order='K', subok=False):
     """
     Return an array copy of the given object.
 
@@ -728,12 +728,21 @@ def copy(a, order='K'):
         as possible. (Note that this function and :meth:`ndarray.copy` are very
         similar, but have different default values for their order=
         arguments.)
+    subok : bool, optional
+        If True, then sub-classes will be passed-through, otherwise the
+        returned array will be forced to be a base-class array (defaults to False).
+
+        .. versionadded:: 1.19.0
 
     Returns
     -------
     arr : ndarray
         Array interpretation of `a`.
 
+    See Also
+    --------
+    ndarray.copy : Preferred method for creating an array copy
+
     Notes
     -----
     This is equivalent to:
@@ -757,7 +766,7 @@ def copy(a, order='K'):
     False
 
     """
-    return array(a, order=order, copy=True)
+    return array(a, order=order, subok=subok, copy=True)
 
 # Basic operations
 
diff --git a/numpy/lib/tests/test_function_base.py b/numpy/lib/tests/test_function_base.py
index 751a7a212..860cf452b 100644
--- a/numpy/lib/tests/test_function_base.py
+++ b/numpy/lib/tests/test_function_base.py
@@ -273,6 +273,13 @@ class TestCopy:
         assert_(not a_fort_copy.flags.c_contiguous)
         assert_(a_fort_copy.flags.f_contiguous)
 
+    def test_subok(self):
+        mx = ma.ones(5)
+        assert_(not ma.isMaskedArray(np.copy(mx, subok=False)))
+        assert_(ma.isMaskedArray(np.copy(mx, subok=True)))
+        # Default behavior
+        assert_(not ma.isMaskedArray(np.copy(mx)))
+
 
 class TestAverage: