Deprecate passing args as positional in sort_values (#41505)

Author: MarcoGorelli

doc/source/whatsnew/v1.3.0.rst

@@ -682,6 +682,7 @@ Deprecations
 - Deprecated passing arguments as positional in :meth:`DataFrame.clip` and :meth:`Series.clip` (other than ``"upper"`` and ``"lower"``) (:issue:`41485`)
 - Deprecated special treatment of lists with first element a Categorical in the :class:`DataFrame` constructor; pass as ``pd.DataFrame({col: categorical, ...})`` instead (:issue:`38845`)
 - Deprecated passing arguments as positional (except for ``"method"``) in :meth:`DataFrame.interpolate` and :meth:`Series.interpolate` (:issue:`41485`)
+- Deprecated passing arguments as positional in :meth:`DataFrame.sort_values` (other than ``"by"``) and :meth:`Series.sort_values` (:issue:`41485`)
 - Deprecated passing arguments as positional in :meth:`DataFrame.dropna` and :meth:`Series.dropna` (:issue:`41485`)
 - Deprecated passing arguments as positional in :meth:`DataFrame.set_index` (other than ``"keys"``) (:issue:`41485`)
 - Deprecated passing arguments as positional (except for ``"levels"``) in :meth:`MultiIndex.set_levels` (:issue:`41485`)
@@ -691,6 +692,7 @@ Deprecations
 - Deprecated passing arguments as positional in :meth:`DataFrame.reset_index` (other than ``"level"``) and :meth:`Series.reset_index` (:issue:`41485`)
 - Deprecated construction of :class:`Series` or :class:`DataFrame` with ``DatetimeTZDtype`` data and ``datetime64[ns]`` dtype.  Use ``Series(data).dt.tz_localize(None)`` instead (:issue:`41555`,:issue:`33401`)
 - Deprecated passing arguments as positional in :meth:`DataFrame.where` and :meth:`Series.where` (other than ``"cond"`` and ``"other"``) (:issue:`41485`)
+-
 
 .. _whatsnew_130.deprecations.nuisance_columns:
 

pandas/core/frame.py

@@ -6221,6 +6221,7 @@ def f(vals) -> tuple[np.ndarray, int]:
     # ----------------------------------------------------------------------
     # Sorting
     # TODO: Just move the sort_values doc here.
+    @deprecate_nonkeyword_arguments(version=None, allowed_args=["self", "by"])
     @Substitution(**_shared_doc_kwargs)
     @Appender(NDFrame.sort_values.__doc__)
     # error: Signature of "sort_values" incompatible with supertype "NDFrame"

pandas/core/series.py

@@ -3259,6 +3259,7 @@ def update(self, other) -> None:
     # ----------------------------------------------------------------------
     # Reindexing, sorting
 
+    @deprecate_nonkeyword_arguments(version=None, allowed_args=["self"])
     def sort_values(
         self,
         axis=0,

pandas/tests/frame/methods/test_sort_values.py

@@ -856,3 +856,15 @@ def test_sort_column_level_and_index_label(
                 tm.assert_frame_equal(result, expected)
         else:
             tm.assert_frame_equal(result, expected)
+
+    def test_sort_values_pos_args_deprecation(self):
+        # https://github.com/pandas-dev/pandas/issues/41485
+        df = DataFrame({"a": [1, 2, 3]})
+        msg = (
+            r"In a future version of pandas all arguments of DataFrame\.sort_values "
+            r"except for the argument 'by' will be keyword-only"
+        )
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            result = df.sort_values("a", 0)
+        expected = DataFrame({"a": [1, 2, 3]})
+        tm.assert_frame_equal(result, expected)

pandas/tests/series/methods/test_sort_values.py

@@ -187,30 +187,42 @@ def test_sort_values_ignore_index(
         tm.assert_series_equal(result_ser, expected)
         tm.assert_series_equal(ser, Series(original_list))
 
+    def test_sort_values_pos_args_deprecation(self):
+        # https://github.com/pandas-dev/pandas/issues/41485
+        ser = Series([1, 2, 3])
+        msg = (
+            r"In a future version of pandas all arguments of Series\.sort_values "
+            r"will be keyword-only"
+        )
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            result = ser.sort_values(0)
+        expected = Series([1, 2, 3])
+        tm.assert_series_equal(result, expected)
+
 
 class TestSeriesSortingKey:
     def test_sort_values_key(self):
         series = Series(np.array(["Hello", "goodbye"]))
 
-        result = series.sort_values(0)
+        result = series.sort_values(axis=0)
         expected = series
         tm.assert_series_equal(result, expected)
 
-        result = series.sort_values(0, key=lambda x: x.str.lower())
+        result = series.sort_values(axis=0, key=lambda x: x.str.lower())
         expected = series[::-1]
         tm.assert_series_equal(result, expected)
 
     def test_sort_values_key_nan(self):
         series = Series(np.array([0, 5, np.nan, 3, 2, np.nan]))
 
-        result = series.sort_values(0)
+        result = series.sort_values(axis=0)
         expected = series.iloc[[0, 4, 3, 1, 2, 5]]
         tm.assert_series_equal(result, expected)
 
-        result = series.sort_values(0, key=lambda x: x + 5)
+        result = series.sort_values(axis=0, key=lambda x: x + 5)
         expected = series.iloc[[0, 4, 3, 1, 2, 5]]
         tm.assert_series_equal(result, expected)
 
-        result = series.sort_values(0, key=lambda x: -x, ascending=False)
+        result = series.sort_values(axis=0, key=lambda x: -x, ascending=False)
         expected = series.iloc[[0, 4, 3, 1, 2, 5]]
         tm.assert_series_equal(result, expected)