API: deprecate Index.sym_diff in favor of symmetric_difference

closes #12591
closes #12594

Author: xflr6

Diff for: doc/source/api.rst

@@ -1374,7 +1374,7 @@ Combining / joining / set operations
    Index.intersection
    Index.union
    Index.difference
-   Index.sym_diff
+   Index.symmetric_difference
 
 Selecting
 ~~~~~~~~~

Diff for: doc/source/indexing.rst

@@ -1359,7 +1359,7 @@ operators. Difference is provided via the ``.difference()`` method.
    a & b
    a.difference(b)
 
-Also available is the ``sym_diff (^)`` operation, which returns elements
+Also available is the ``symmetric_difference (^)`` operation, which returns elements
 that appear in either ``idx1`` or ``idx2`` but not both. This is
 equivalent to the Index created by ``idx1.difference(idx2).union(idx2.difference(idx1))``,
 with duplicates dropped.
@@ -1368,7 +1368,7 @@ with duplicates dropped.
 
    idx1 = pd.Index([1, 2, 3, 4])
    idx2 = pd.Index([2, 3, 4, 5])
-   idx1.sym_diff(idx2)
+   idx1.symmetric_difference(idx2)
    idx1 ^ idx2
 
 Missing values

Diff for: doc/source/whatsnew/v0.18.1.txt

@@ -60,6 +60,8 @@ API changes
 Deprecations
 ^^^^^^^^^^^^
 
+- The method name ``Index.sym_diff()`` is deprecated and can be replaced by ``Index.symmetric_difference()`` (:issue:`12591`)
+
 
 
 

Diff for: pandas/indexes/base.py

@@ -1619,7 +1619,7 @@ def __or__(self, other):
         return self.union(other)
 
     def __xor__(self, other):
-        return self.sym_diff(other)
+        return self.symmetric_difference(other)
 
     def union(self, other):
         """
@@ -1796,7 +1796,7 @@ def difference(self, other):
 
     diff = deprecate('diff', difference)
 
-    def sym_diff(self, other, result_name=None):
+    def symmetric_difference(self, other, result_name=None):
         """
         Compute the sorted symmetric difference of two Index objects.
 
@@ -1807,11 +1807,11 @@ def sym_diff(self, other, result_name=None):
 
         Returns
         -------
-        sym_diff : Index
+        symmetric_difference : Index
 
         Notes
         -----
-        ``sym_diff`` contains elements that appear in either ``idx1`` or
+        ``symmetric_difference`` contains elements that appear in either ``idx1`` or
         ``idx2`` but not both. Equivalent to the Index created by
         ``(idx1 - idx2) + (idx2 - idx1)`` with duplicates dropped.
 
@@ -1822,7 +1822,7 @@ def sym_diff(self, other, result_name=None):
         --------
         >>> idx1 = Index([1, 2, 3, 4])
         >>> idx2 = Index([2, 3, 4, 5])
-        >>> idx1.sym_diff(idx2)
+        >>> idx1.symmetric_difference(idx2)
         Int64Index([1, 5], dtype='int64')
 
         You can also use the ``^`` operator:
@@ -1843,6 +1843,8 @@ def sym_diff(self, other, result_name=None):
             attribs['freq'] = None
         return self._shallow_copy_with_infer(the_diff, **attribs)
 
+    sym_diff = deprecate('sym_diff', symmetric_difference)
+
     def get_loc(self, key, method=None, tolerance=None):
         """
         Get integer location for requested label

Diff for: pandas/tests/indexes/common.py

@@ -305,7 +305,7 @@ def test_setops_errorcases(self):
             # # non-iterable input
             cases = [0.5, 'xxx']
             methods = [idx.intersection, idx.union, idx.difference,
-                       idx.sym_diff]
+                       idx.symmetric_difference]
 
             for method in methods:
                 for case in cases:
@@ -404,15 +404,15 @@ def test_difference_base(self):
                 with tm.assertRaisesRegexp(TypeError, msg):
                     result = first.difference([1, 2, 3])
 
-    def test_symmetric_diff(self):
+    def test_symmetric_difference(self):
         for name, idx in compat.iteritems(self.indices):
             first = idx[1:]
             second = idx[:-1]
             if isinstance(idx, CategoricalIndex):
                 pass
             else:
                 answer = idx[[0, -1]]
-                result = first.sym_diff(second)
+                result = first.symmetric_difference(second)
                 self.assertTrue(tm.equalContents(result, answer))
 
             # GH 10149
@@ -422,17 +422,21 @@ def test_symmetric_diff(self):
                 if isinstance(idx, PeriodIndex):
                     msg = "can only call with other PeriodIndex-ed objects"
                     with tm.assertRaisesRegexp(ValueError, msg):
-                        result = first.sym_diff(case)
+                        result = first.symmetric_difference(case)
                 elif isinstance(idx, CategoricalIndex):
                     pass
                 else:
-                    result = first.sym_diff(case)
+                    result = first.symmetric_difference(case)
                     self.assertTrue(tm.equalContents(result, answer))
 
             if isinstance(idx, MultiIndex):
                 msg = "other must be a MultiIndex or a list of tuples"
                 with tm.assertRaisesRegexp(TypeError, msg):
-                    result = first.sym_diff([1, 2, 3])
+                    result = first.symmetric_difference([1, 2, 3])
+
+        # 12591 deprecated
+        with tm.assert_produces_warning(FutureWarning):
+            first.sym_diff(second)
 
     def test_insert_base(self):
 

Diff for: pandas/tests/indexes/test_base.py

@@ -641,11 +641,11 @@ def test_difference(self):
         self.assertEqual(len(result), 0)
         self.assertEqual(result.name, first.name)
 
-    def test_symmetric_diff(self):
+    def test_symmetric_difference(self):
         # smoke
         idx1 = Index([1, 2, 3, 4], name='idx1')
         idx2 = Index([2, 3, 4, 5])
-        result = idx1.sym_diff(idx2)
+        result = idx1.symmetric_difference(idx2)
         expected = Index([1, 5])
         self.assertTrue(tm.equalContents(result, expected))
         self.assertIsNone(result.name)
@@ -658,7 +658,7 @@ def test_symmetric_diff(self):
         # multiIndex
         idx1 = MultiIndex.from_tuples(self.tuples)
         idx2 = MultiIndex.from_tuples([('foo', 1), ('bar', 3)])
-        result = idx1.sym_diff(idx2)
+        result = idx1.symmetric_difference(idx2)
         expected = MultiIndex.from_tuples([('bar', 2), ('baz', 3), ('bar', 3)])
         self.assertTrue(tm.equalContents(result, expected))
 
@@ -667,7 +667,7 @@ def test_symmetric_diff(self):
         # and the correct non-nan values are there. punt on sorting.
         idx1 = Index([1, 2, 3, np.nan])
         idx2 = Index([0, 1, np.nan])
-        result = idx1.sym_diff(idx2)
+        result = idx1.symmetric_difference(idx2)
         # expected = Index([0.0, np.nan, 2.0, 3.0, np.nan])
 
         nans = pd.isnull(result)
@@ -679,11 +679,11 @@ def test_symmetric_diff(self):
         idx1 = Index([1, 2, 3, 4], name='idx1')
         idx2 = np.array([2, 3, 4, 5])
         expected = Index([1, 5])
-        result = idx1.sym_diff(idx2)
+        result = idx1.symmetric_difference(idx2)
         self.assertTrue(tm.equalContents(result, expected))
         self.assertEqual(result.name, 'idx1')
 
-        result = idx1.sym_diff(idx2, result_name='new_name')
+        result = idx1.symmetric_difference(idx2, result_name='new_name')
         self.assertTrue(tm.equalContents(result, expected))
         self.assertEqual(result.name, 'new_name')