DEPR: DataFrame.sort_index by keyword (#29931)

Author: jbrockmendel

doc/source/whatsnew/v1.0.0.rst

@@ -409,6 +409,7 @@ or ``matplotlib.Axes.plot``. See :ref:`plotting.formatters` for more.
 - Removed the previously deprecated :meth:`Series.get_value`, :meth:`Series.set_value`, :meth:`DataFrame.get_value`, :meth:`DataFrame.set_value` (:issue:`17739`)
 - Changed the the default value of `inplace` in :meth:`DataFrame.set_index` and :meth:`Series.set_axis`. It now defaults to False (:issue:`27600`)
 - Removed the previously deprecated :attr:`Series.cat.categorical`, :attr:`Series.cat.index`, :attr:`Series.cat.name` (:issue:`24751`)
+- Removed the previously deprecated "by" keyword from :meth:`DataFrame.sort_index`, use :meth:`DataFrame.sort_values` instead (:issue:`10726`)
 - Removed support for nested renaming in :meth:`DataFrame.aggregate`, :meth:`Series.aggregate`, :meth:`DataFrameGroupBy.aggregate`, :meth:`SeriesGroupBy.aggregate`, :meth:`Rolling.aggregate` (:issue:`18529`)
 - Passing ``datetime64`` data to :class:`TimedeltaIndex` or ``timedelta64`` data to ``DatetimeIndex`` now raises ``TypeError`` (:issue:`23539`, :issue:`23937`)
 - A tuple passed to :meth:`DataFrame.groupby` is now exclusively treated as a single key (:issue:`18314`)

pandas/core/frame.py

@@ -4764,24 +4764,12 @@ def sort_index(
         kind="quicksort",
         na_position="last",
         sort_remaining=True,
-        by=None,
     ):
 
         # TODO: this can be combined with Series.sort_index impl as
         # almost identical
 
         inplace = validate_bool_kwarg(inplace, "inplace")
-        # 10726
-        if by is not None:
-            warnings.warn(
-                "by argument to sort_index is deprecated, "
-                "please use .sort_values(by=...)",
-                FutureWarning,
-                stacklevel=2,
-            )
-            if level is not None:
-                raise ValueError("unable to simultaneously sort by and level")
-            return self.sort_values(by, axis=axis, ascending=ascending, inplace=inplace)
 
         axis = self._get_axis_number(axis)
         labels = self._get_axis(axis)

pandas/tests/frame/test_sorting.py

@@ -385,27 +385,18 @@ def test_sort_index_multicolumn(self):
         random.shuffle(B)
         frame = DataFrame({"A": A, "B": B, "C": np.random.randn(100)})
 
-        # use .sort_values #9816
-        with tm.assert_produces_warning(FutureWarning):
-            frame.sort_index(by=["A", "B"])
         result = frame.sort_values(by=["A", "B"])
         indexer = np.lexsort((frame["B"], frame["A"]))
         expected = frame.take(indexer)
         tm.assert_frame_equal(result, expected)
 
-        # use .sort_values #9816
-        with tm.assert_produces_warning(FutureWarning):
-            frame.sort_index(by=["A", "B"], ascending=False)
         result = frame.sort_values(by=["A", "B"], ascending=False)
         indexer = np.lexsort(
             (frame["B"].rank(ascending=False), frame["A"].rank(ascending=False))
         )
         expected = frame.take(indexer)
         tm.assert_frame_equal(result, expected)
 
-        # use .sort_values #9816
-        with tm.assert_produces_warning(FutureWarning):
-            frame.sort_index(by=["B", "A"])
         result = frame.sort_values(by=["B", "A"])
         indexer = np.lexsort((frame["A"], frame["B"]))
         expected = frame.take(indexer)
@@ -452,14 +443,8 @@ def test_sort_index_different_sortorder(self):
 
         df = DataFrame({"A": A, "B": B, "C": np.random.randn(100)})
 
-        # use .sort_values #9816
-        with tm.assert_produces_warning(FutureWarning):
-            df.sort_index(by=["A", "B"], ascending=[1, 0])
-        result = df.sort_values(by=["A", "B"], ascending=[1, 0])
-
         ex_indexer = np.lexsort((df.B.max() - df.B, df.A))
         expected = df.take(ex_indexer)
-        tm.assert_frame_equal(result, expected)
 
         # test with multiindex, too
         idf = df.set_index(["A", "B"])
@@ -472,59 +457,6 @@ def test_sort_index_different_sortorder(self):
         result = idf["C"].sort_index(ascending=[1, 0])
         tm.assert_series_equal(result, expected["C"])
 
-    def test_sort_index_duplicates(self):
-
-        # with 9816, these are all translated to .sort_values
-
-        df = DataFrame([range(5, 9), range(4)], columns=["a", "a", "b", "b"])
-
-        with pytest.raises(ValueError, match="not unique"):
-            # use .sort_values #9816
-            with tm.assert_produces_warning(FutureWarning):
-                df.sort_index(by="a")
-        with pytest.raises(ValueError, match="not unique"):
-            df.sort_values(by="a")
-
-        with pytest.raises(ValueError, match="not unique"):
-            # use .sort_values #9816
-            with tm.assert_produces_warning(FutureWarning):
-                df.sort_index(by=["a"])
-        with pytest.raises(ValueError, match="not unique"):
-            df.sort_values(by=["a"])
-
-        with pytest.raises(ValueError, match="not unique"):
-            # use .sort_values #9816
-            with tm.assert_produces_warning(FutureWarning):
-                # multi-column 'by' is separate codepath
-                df.sort_index(by=["a", "b"])
-        with pytest.raises(ValueError, match="not unique"):
-            # multi-column 'by' is separate codepath
-            df.sort_values(by=["a", "b"])
-
-        # with multi-index
-        # GH4370
-        df = DataFrame(
-            np.random.randn(4, 2), columns=MultiIndex.from_tuples([("a", 0), ("a", 1)])
-        )
-        with pytest.raises(ValueError, match="level"):
-            # use .sort_values #9816
-            with tm.assert_produces_warning(FutureWarning):
-                df.sort_index(by="a")
-        with pytest.raises(ValueError, match="level"):
-            df.sort_values(by="a")
-
-        # convert tuples to a list of tuples
-        # use .sort_values #9816
-        with tm.assert_produces_warning(FutureWarning):
-            df.sort_index(by=[("a", 1)])
-        expected = df.sort_values(by=[("a", 1)])
-
-        # use .sort_values #9816
-        with tm.assert_produces_warning(FutureWarning):
-            df.sort_index(by=("a", 1))
-        result = df.sort_values(by=("a", 1))
-        tm.assert_frame_equal(result, expected)
-
     def test_sort_index_level(self):
         mi = MultiIndex.from_tuples([[1, 1, 3], [1, 1, 1]], names=list("ABC"))
         df = DataFrame([[1, 2], [3, 4]], mi)