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])