Added docstrings, depricated __iadd__, changed __add__ to use self.union()

Author: benthayer

doc/source/groupby.rst

@@ -133,8 +133,8 @@ but the specified columns
 
 .. ipython:: python
 
- df.set_index(['A', 'B'])
- grouped = df.groupby(level=df.index.names.difference(['B'])
+ df2 = df.set_index(['A', 'B'])
+ grouped = df2.groupby(level=df2.index.names.difference(['B'])
 
 These will split the DataFrame on its index (rows). We could also split by the
 columns:

doc/source/whatsnew/v0.20.0.txt

@@ -26,7 +26,7 @@ Check the :ref:`API Changes <whatsnew_0200.api_breaking>` and :ref:`deprecations
 New features
 ~~~~~~~~~~~~
 
-- Added difference from FrozenLists (:issue:`15475`)
+- Added ``.difference()`` method for FrozenLists (:issue:`15475`)
 
 - Integration with the ``feather-format``, including a new top-level ``pd.read_feather()`` and ``DataFrame.to_feather()`` method, see :ref:`here <io.feather>`.
 - ``.str.replace`` now accepts a callable, as replacement, which is passed to ``re.sub`` (:issue:`15055`)

pandas/indexes/frozen.py

@@ -28,11 +28,11 @@ class FrozenList(PandasObject, list):
 
  def __add__(self, other):
  warnings.warn("__add__ is deprecated, use union(...)", FutureWarning)
- if isinstance(other, tuple):
- other = list(other)
- return self.__class__(super(FrozenList, self).__add__(other))
+ return self.union(other)
 
- __iadd__ = __add__
+ def __iadd__(self, other):
+ warnings.warn("__iadd__ is deprecated, use union(...)", FutureWarning)
+ return self.union(other)
 
  # Python 2 compat
  def __getslice__(self, i, j):
@@ -84,11 +84,14 @@ def __repr__(self):
  pop = append = extend = remove = sort = insert = _disabled
 
  def union(self, other):
+ """Returns a FrozenList with other concatenated to the end of self"""
  if isinstance(other, tuple):
  other = list(other)
  return self.__class__(super(FrozenList, self).__add__(other))
 
  def difference(self, other):
+ """Returns a FrozenList with the same elements as self, but with elements
+ that are also in other removed."""
  other = set(other)
  temp = [x for x in self if x not in other]
  return self.__class__(temp)

pandas/tests/indexes/test_frozen.py

@@ -14,6 +14,9 @@ def setUp(self):
  self.container = FrozenList(self.lst)
  self.klass = FrozenList
 
+ def test_add(self):
+ self.assert_produces_warning(FutureWarning)
+
  def test_union(self):
  result = self.container.union((1, 2, 3))
  expected = FrozenList(self.lst + [1, 2, 3])