DOC: Update np.copy docstring to include ragged case (#15928)

We only do a shallow copy of arrays (mainly important for object arrays), so
mention that in the documentation.

Fixes #15923

Co-Authored-By: Eric Wieser <wieser.eric@gmail.com>
Co-Authored-By: Ross Barnowski <rossbar@berkeley.edu>

1 files changed, 24 insertions, 0 deletions

diff --git a/numpy/lib/function_base.py b/numpy/lib/function_base.py
index 7eeed7825..38acfd2d5 100644
--- a/numpy/lib/function_base.py
+++ b/numpy/lib/function_base.py
@@ -764,6 +764,30 @@ def copy(a, order='K', subok=False):
     >>> x[0] == z[0]
     False
 
+    Note that np.copy is a shallow copy and will not copy object
+    elements within arrays. This is mainly important for arrays
+    containing Python objects. The new array will contain the
+    same object which may lead to surprises if that object can
+    be modified (is mutable):
+
+    >>> a = np.array([1, 'm', [2, 3, 4]], dtype=object)
+    >>> b = np.copy(a)
+    >>> b[2][0] = 10
+    >>> a
+    array([1, 'm', list([10, 3, 4])], dtype=object)
+
+    To ensure all elements within an ``object`` array are copied,
+    use `copy.deepcopy`:
+
+    >>> import copy
+    >>> a = np.array([1, 'm', [2, 3, 4]], dtype=object)
+    >>> c = copy.deepcopy(a)
+    >>> c[2][0] = 10
+    >>> c
+    array([1, 'm', list([10, 3, 4])], dtype=object)
+    >>> a
+    array([1, 'm', list([2, 3, 4])], dtype=object)
+
     """
     return array(a, order=order, subok=subok, copy=True)