From 1893ffd3e97303a77b30ee05ab4e0033caa80b6a Mon Sep 17 00:00:00 2001 From: Sebastian Bank Date: Fri, 11 Mar 2016 15:01:56 +0100 Subject: [PATCH] API: deprecate Index.sym_diff in favor of symmetric_difference closes #12591 closes #12594 --- doc/source/api.rst | 2 +- doc/source/indexing.rst | 4 ++-- doc/source/whatsnew/v0.18.1.txt | 2 ++ pandas/indexes/base.py | 12 +++++++----- pandas/tests/indexes/common.py | 16 ++++++++++------ pandas/tests/indexes/test_base.py | 12 ++++++------ 6 files changed, 28 insertions(+), 20 deletions(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index 85f1984f29291..d6402100a296f 100644 --- a/doc/source/api.rst +++ b/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 --git a/doc/source/indexing.rst b/doc/source/indexing.rst index 7494f8ae88307..04b166dacf2b7 100644 --- a/doc/source/indexing.rst +++ b/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 --git a/doc/source/whatsnew/v0.18.1.txt b/doc/source/whatsnew/v0.18.1.txt index b7a0cf888f1a2..c2fd9c1278ed1 100644 --- a/doc/source/whatsnew/v0.18.1.txt +++ b/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 --git a/pandas/indexes/base.py b/pandas/indexes/base.py index 852cddc456213..58828d52b60dd 100644 --- a/pandas/indexes/base.py +++ b/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 --git a/pandas/tests/indexes/common.py b/pandas/tests/indexes/common.py index f1824267d63d8..a6aaa69183f10 100644 --- a/pandas/tests/indexes/common.py +++ b/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,7 +404,7 @@ 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] @@ -412,7 +412,7 @@ def test_symmetric_diff(self): 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 --git a/pandas/tests/indexes/test_base.py b/pandas/tests/indexes/test_base.py index 465879dd62466..24a20f7adf624 100644 --- a/pandas/tests/indexes/test_base.py +++ b/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')