DOC: Update pandas.Series.copy docstring

pandas/core/generic.py

@@ -4506,7 +4506,15 @@ def astype(self, dtype, copy=True, errors='raise', **kwargs):
 
     def copy(self, deep=True):
         """
-        Make a copy of this objects data.
+        Make a copy of this objects indices and data.
+
+        Deep copy (default) will create a new object with a copy of the objects
+        data and indices. Modifications to the data or indices of the copy
+        will not be reflected in the original object.
+
+        Shallow copy (``deep=False``) will create a new object without copying
+        the data or indices. Any changes to the index or data of the original
+        will be reflected in the shallow copy (and vice versa).
 
         Parameters
         ----------
@@ -4522,6 +4530,102 @@ def copy(self, deep=True):
         Returns
         -------
         copy : type of caller
+
+        Examples
+        --------
+        >>> s = pd.Series([1,2], dtype="int32", index=["a", "b"])
+        >>> s
+        a    1
+        b    2
+        dtype: int32
+        >>> s_copy = s.copy()
+        >>> s_copy
+        a    1
+        b    2
+        dtype: int32
+
+        Shallow copy versus default (deep) copy:
+
+        In a shallow copy the index and data is a reference to the original
+        objects'.
+
+        >>> s = pd.Series([1,2], dtype="int32", index=["a", "b"])
+        >>> deep_copy = s.copy()
+        >>> shallow_copy = s.copy(deep=False)
+        >>> id(s) == id(shallow_copy)
+        False
+        >>> id(s.index) == id(shallow_copy.index)
+        True
+        >>> id(s.values) == id(shallow_copy.values)
+        True
+        >>> id(s) == id(deep_copy)
+        False
+        >>> id(s.index) == id(deep_copy.index)
+        False
+        >>> id(s.values) == id(deep_copy.values)
+        False
+        >>> s[0] = 3
+        >>> s
+        a    3
+        b    2
+        dtype: int32
+        >>> shallow_copy
+        a    3
+        b    2
+        dtype: int32
+        >>> deep_copy
+        a    1
+        b    2
+        dtype: int32
+        >>> shallow_copy[0] = 4
+        >>> s
+        a    4
+        b    2
+        dtype: int32
+        >>> shallow_copy
+        a    4
+        b    2
+        dtype: int32
+        >>> deep_copy
+        a    1
+        b    2
+        dtype: int32
+
+        When copying object containing python objects, deep copy will
+        copy the indices and data but will not do so recursively.
+
+        >>> class Point(object):
+        ...     def __init__(self, x, y):
+        ...         self.x = x
+        ...         self.y = y
+        ...     def __repr__(self):
+        ...         return "Point(%d,%d)" % (self.x, self.y)
+        ...
+        >>> p1 = Point(0, 1)
+        >>> s = pd.Series([p1], dtype="object")
+        >>> s
+        0    Point(0,1)
+        dtype: object
+        >>> s_copy = s.copy()
+        >>> s_copy
+        0    Point(0,1)
+        dtype: object
+        >>> id(s[0]) == id(s_copy[0])
+        True
+        >>> p1.x = 1
+        >>> s
+        0    Point(1,1)
+        dtype: object
+        >>> s_copy
+        0    Point(1,1)
+        dtype: object
+        >>>
+
+        For deep-copying python objects, the following can be used:
+
+        >>> import copy
+        >>> deep_deep_copy = pd.Series(copy.deepcopy(s.values),
+        ...                            index=copy.deepcopy(s.index))
         """
         data = self._data.copy(deep=deep)
         return self._constructor(data).__finalize__(self)