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)